Mercurial > hg > forks > dxa
annotate dxa.1 @ 14:84c0facfc43c
Merge changes from upstream v0.1.4.
| author | Matti Hamalainen <ccr@tnsp.org> |
|---|---|
| date | Thu, 14 Oct 2021 01:38:52 +0300 |
| parents | 4410c9c7750d |
| children |
| rev | line source |
|---|---|
|
14
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
1 .TH DXA "1" "31 January 2019" |
| 0 | 2 |
| 3 .SH NAME | |
| 4 dxa \- 6502/R65C02 disassembler | |
| 5 | |
| 6 .SH SYNOPSIS | |
| 7 .B dxa | |
| 8 [\fIOPTION\fR]... \fIFILE\fR | |
| 9 | |
| 10 .SH DESCRIPTION | |
| 11 .B dxa | |
| 12 is the semi-official disassembler option for the | |
| 13 .BR xa (1) | |
| 14 package, a weakly patched version of Marko Mäkelä's | |
| 15 .B d65 | |
| 16 disassembler that generates output similar to the de facto coding | |
| 17 conventions used for | |
| 18 .BR xa (1). | |
| 19 The package is designed to intelligently(?) scan arbitrary code and (with | |
| 20 hints) can identify the difference between data and valid machine code, | |
| 21 generating a sane looking, "perfect" disassembly with data and code portions. | |
| 22 .LP | |
| 23 Perfect, in this case, means that you can take what | |
| 24 .B dxa | |
| 25 spits out and feed it right back into | |
| 26 .BR xa (1), | |
| 27 and get the exact same object file you started with, even if sometimes | |
| 28 .B dxa | |
| 29 can't identify everything correctly. With a few extra options, you can tease | |
| 30 and twist the output to generate something not quite so parseable, or even | |
| 31 more like true assembler source. | |
| 32 .SH OPTIONS | |
| 33 For historical and compatibility reasons, the long options (--) only exist | |
| 34 if | |
| 35 .B dxa | |
| 36 were compiled with LONG_OPTIONS enabled in options.h. | |
| 37 .TP | |
| 38 .B \--datablock xxxx-yyyy | |
| 39 .TP | |
| 40 .B \-b xxxx-yyyy | |
| 41 Defines the memory range xxxx to yyyy (hexadecimal, inclusive) to be a data | |
| 42 block. The memory range can be further specified: | |
| 43 .RS | |
| 44 .IP * | |
| 45 If the range is preceded by ! (an exclamation point), such as | |
| 46 .BR !c000-cfff , | |
| 47 then it is | |
| 48 further defined to be a data block with no vectors in it either. | |
| 49 .IP * | |
| 50 If the range is preceded by ? (a question mark), then it is further | |
| 51 defined to be a data block that is completely unused and therefore | |
| 52 no valid routine may contain instructions whose parameter lie in this | |
| 53 range. Useful for providing enhanced protection against misinterpreting | |
| 54 data to be program code, but be careful, or some code may be listed as | |
| 55 data. For instance, the Commodore 64 firmware uses the base address $CFFF | |
| 56 when initializing the video chip, and the BASIC interpreter uses the | |
| 57 addresses $9FEA and $9FEB while loading the instruction pointers. | |
| 58 In addition to this, there are a number of BIT instructions used for | |
| 59 skipping the next instruction. Thus, you must allow addresses like $1A9, | |
| 60 $2A9 and so on. | |
| 61 .RE | |
| 62 .TP | |
| 63 .B \--datablocks filename | |
| 64 .TP | |
| 65 .B \-B filename | |
| 66 Reads data blocks from file | |
| 67 .B filename | |
| 68 as if they had been specified on the command | |
| 69 line, one per line (such as xxxx-yyyy, ?xxxx-yyyy, etc.). | |
| 70 .TP | |
| 71 .B \--labels filename | |
| 72 .TP | |
| 73 .B \-l filename | |
| 74 Causes label names to be read from file | |
| 75 .BR filename . | |
| 76 This file format is the same as the labelfile/symbol table file generated | |
| 77 by | |
| 78 .BR xa (1) | |
| 79 with the | |
| 80 .B \-l | |
| 81 option. The | |
| 82 .B \-l | |
| 83 was chosen on purpose for consistency with | |
| 84 .BR xa (1). | |
| 85 .TP | |
| 86 .B \--routine xxxx | |
| 87 .TP | |
| 88 .B \-r xxxx | |
| 89 Specifies an address (in hexadecimal) that is declared to be a valid routine. | |
| 90 .B It is strongly recommended | |
| 91 that you specify the initial execution address as a routine. | |
|
14
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
92 For example, for a Commodore 64 binary with a BASIC header that performs |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
93 .B SYS |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
94 .BR 2064 , |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
95 specify |
| 0 | 96 .B \-r0810 |
|
14
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
97 so that disassembly starts at that location (or use the |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
98 .B \-U |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
99 option, which can automatically do this for you). Note that specifying this |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
100 manually may have interactions with datablock detection |
| 0 | 101 .RB ( \-d ). |
| 102 .TP | |
| 103 .B \--routines filename | |
| 104 .TP | |
| 105 .B \-R filename | |
| 106 Causes a list of routines to be read from file | |
| 107 .BR filename , | |
| 108 one per line as if they had been specified on the command line. | |
| 109 .TP | |
| 110 .B \--addresses option | |
| 111 .TP | |
| 112 .B \-a option | |
| 113 Determines if and what kind of address information should be dumped with the | |
| 114 disassembly, if any. Note that this may make your output no longer intelligible | |
| 115 to | |
| 116 .BR xa (1). | |
| 117 The valid options are: | |
| 118 .RS | |
| 119 .TP | |
| 120 .B disabled | |
| 121 Dump source only with no address information. This is the default. | |
| 122 .TP | |
| 123 .B enabled | |
| 124 Write the current address at the beginning of each line. | |
| 125 .TP | |
| 126 .B dump | |
| 127 Write the current address at the beginning of each line, along with a hexdump | |
| 128 of the bytes for which the statement was generated. | |
| 129 .RE | |
| 130 .TP | |
| 131 .B \--colon-newline | |
| 132 .TP | |
| 133 .B \-N | |
| 134 .TP | |
| 135 .B \--no-colon-newline | |
| 136 .TP | |
| 137 .B \-n | |
| 138 A purely cosmetic option to determine how labels are emitted. Many people, | |
| 139 including myself, prefer a listing where the label is given, then a tab, | |
| 140 then the code | |
| 141 .RB ( \-n ). | |
| 142 Since this is | |
| 143 .I my | |
| 144 preference, it's the default. On the other hand, there are also many who | |
| 145 prefer to have the label demarcated by a colon and a newline, and the code | |
| 146 beginning indented on the next line. This is the way | |
| 147 .B d65 | |
| 148 used to do it, and is still supported with | |
| 149 .BR \-N . | |
| 150 .TP | |
| 151 .B \--processor option | |
| 152 .TP | |
| 153 .B \-p option | |
| 154 Specify the instruction set. Note that specifying an instruction set that | |
| 155 permits and disassembles illegal and/or undocumented | |
| 156 NMOS opcodes may make your output unintelligible to | |
| 157 .BR xa (1). | |
| 158 Only one may be specified. The valid options are: | |
| 159 .RS | |
| 160 .TP | |
| 161 .B standard-nmos6502 | |
| 162 Only official opcodes will be recognized. This is the default. | |
| 163 .TP | |
| 164 .B r65c02 | |
| 165 Opcodes specific to the Rockwell 65C02 (R65C02) will also be allowed. | |
| 166 .TP | |
| 167 .B all-nmos6502 | |
| 168 Allows all 256 NMOS opcodes to be disassembled, whether documented or | |
| 169 undocumented. | |
| 170 Note that instructions generated by this mode are not guaranteed to work on | |
| 171 all NMOS 6502s. | |
| 172 .TP | |
| 173 .B rational-nmos6502 | |
| 174 Only allows "rational" undocumented instructions. This excludes ANE, SHA, | |
| 175 SHS, SHY, SHX, LXA and LAXS. This is a judgment call. | |
| 176 .TP | |
| 177 .B useful-nmos6502 | |
| 178 Only allows "useful" undocumented instructions. This excludes ANE, SHA, | |
| 179 SHS, SHY, SHX, LXA, LAXS, NOOP and STP. This is a judgment call. | |
| 180 .TP | |
| 181 .B traditional-nmos6502 | |
| 182 Only allows the most widely accepted undocumented instructions based on | |
| 183 combinations of ALU and RMW operations. This excludes ANE, SHA, SHS, SHY, | |
| 184 SHX, LXA, LAXS, NOOP, STP, ARR, ASR, ANC, SBX and USBC. | |
| 185 This is a judgment call. | |
| 186 .RE | |
| 187 .TP | |
| 188 .B \--get-sa | |
| 189 .TP | |
| 190 .B \-G | |
| 191 .TP | |
| 192 .B \--no-get-sa xxxx | |
| 193 .TP | |
| 194 .B \-g xxxx | |
| 195 Enables or disables automatic starting address detection. If enabled (the | |
| 196 default), | |
| 197 .B dxa | |
| 198 looks at the first two bytes as a 16-bit word in 6502 little-endian format | |
| 199 and considers that to be the starting address for the object, discarding them | |
| 200 without further interpretation. This is very useful for Commodore computers in | |
| 201 particular. If your binary does not have a starting address, you must | |
| 202 specify one using | |
| 203 .B \-g | |
| 204 or | |
| 205 .B \--no-get-sa | |
| 206 followed by a hexadecimal address. The starting address will then be encoded | |
| 207 into the output using | |
| 208 .BR "* =" . | |
| 209 .TP | |
| 210 .B \--no-word-sa | |
| 211 .TP | |
| 212 .B \-q | |
| 213 .TP | |
| 214 .B \--word-sa | |
| 215 .TP | |
| 216 .B \-Q | |
| 217 Only relevant if automatic starting address detection is enabled. If so, | |
| 218 the default is to also emit the starting address as a | |
| 219 .B \&.word | |
| 220 pseudo-op before the starting address indicated with | |
| 221 .B * = | |
| 222 so that it will be regenerated on re-assembly | |
| 223 .RB ( \-Q ). | |
| 224 Otherwise, if this option is disabled, the starting address word will not be | |
| 225 re-emitted and | |
| 226 will need to be tacked back on if the target requires it. If you specify an | |
| 227 address with | |
| 228 .BR \-g , | |
| 229 then that address will be used here too. | |
| 230 .TP | |
|
14
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
231 .B \--no-detect-basic |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
232 .TP |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
233 .B \-u |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
234 .TP |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
235 .B \--detect-basic |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
236 .TP |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
237 .B \-U |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
238 If the starting address is recognized as a typical BASIC entry point |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
239 (currently supported for Commodore computers), then |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
240 .B dxa |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
241 will attempt to see if a BASIC header is present, and if so, determine its |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
242 length and mark the section as a completely dead |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
243 datablock not eligible for further disassembly or referencing. If the |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
244 first line is a construct such as |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
245 .B 10 SYS |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
246 .BR 2061 , |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
247 then |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
248 .B dxa |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
249 will additionally parse the provided address and mark it as a valid routine |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
250 if the address is within the boundaries of the disassembled file. |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
251 Note that although its heuristics |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
252 are designed to be permissive, it may nevertheless misinterpret certain files |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
253 with intentionally pathologic line link addresses, and unusual applications |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
254 where the linked machine code is designed to actually |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
255 .I modify |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
256 the BASIC text may not |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
257 disassemble correctly with this option. These are highly atypical situations, |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
258 so this option will likely become the default in a future release. |
|
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
259 .TP |
| 0 | 260 .B \--verbose |
| 261 .TP | |
| 262 .B \-v | |
| 263 Enables verbose output, which may or may not be useful in the same way that | |
| 264 Schroedinger's Cat may or may not be dead. | |
| 265 .TP | |
| 266 .B \--help | |
| 267 .TP | |
| 268 .B \-? | |
| 269 .TP | |
| 270 .B \-V | |
| 271 A quick summary of options. | |
| 272 .LP | |
| 273 The following options control how program code is scanned and determined | |
| 274 to be a valid (or invalid) portion of a putative routine. | |
| 275 .TP | |
| 276 .B \--datablock-detection option | |
| 277 .TP | |
| 278 .B \-d option | |
| 279 This controls how the program automatically detects data blocks for addresses | |
| 280 where no previous hints are specified. Only one method may be specified. | |
| 281 The valid options are: | |
| 282 .RS | |
| 283 .TP | |
| 284 .B poor | |
| 285 As much as the object as possible will be listed as program code, even if | |
| 286 there are illegal instructions present. This is the default. | |
| 287 .TP | |
| 288 .B strict | |
| 289 Assumes that all declared routines call and execute only valid instructions. If | |
| 290 any portion of code declared as a routine leads to an address block containing | |
| 291 illegal opcodes, a consistency error will occur and disassembly will stop. | |
| 292 .TP | |
| 293 .B skip-scanning | |
| 294 Program addresses that are not referenced by any routine will not be scanned | |
| 295 for valid routines (thus data a priori). | |
| 296 .RE | |
| 297 .TP | |
| 298 .B \--no-external-labels | |
| 299 .TP | |
| 300 .B \-e | |
| 301 .TP | |
| 302 .B \--external-labels | |
| 303 .TP | |
| 304 .B \-E | |
| 305 Controls whether labels should be generated for addresses outside of the | |
| 306 program itself. The default is not to (i.e., leave the addresses absolute). | |
| 307 .TP | |
| 308 .B \--address-tables option | |
| 309 .TP | |
| 310 .B \-t option | |
| 311 Controls detection of address tables/dispatch tables. The following options | |
| 312 are available: | |
| 313 .RS | |
| 314 .TP | |
| 315 .B ignore | |
| 316 Don't attempt to detect address tables. | |
| 317 .TP | |
| 318 .B detect-all | |
| 319 Address tables referencing any label will be detected. | |
| 320 .TP | |
| 321 .B detect-internal | |
| 322 Address tables with labels whose addresses lie within the program's address | |
| 323 range will be detected. This is the default. | |
| 324 .RE | |
| 325 .TP | |
| 326 .B \--no-suspect-jsr | |
| 327 .TP | |
| 328 .B \-j | |
| 329 .TP | |
| 330 .B \--suspect-jsr | |
| 331 .TP | |
| 332 .B \-J | |
| 333 These options indicate whether JSRs are always expected to return to the | |
| 334 following instruction or not. This will affect how routines are parsed. For | |
| 335 example, the Commodore 128 KERNAL has a routine called PRIMM that prints a | |
| 336 null-terminated string directly following the JSR instruction, returning after | |
| 337 the null byte. In this case, | |
| 338 .B \-J | |
| 339 should be specified to alert the disassembler that this is possible. The | |
| 340 default is to expect "normal" JSRs (i.e., | |
| 341 .BR \-j ). | |
| 342 .TP | |
| 343 .B \--no-one-byte-routines | |
| 344 .TP | |
| 345 .B \-o | |
| 346 .TP | |
| 347 .B \--one-byte-routines | |
| 348 .TP | |
| 349 .B \-O | |
| 350 These options permit or inhibit a single RTS, RTI or BRK instruction (or STP | |
| 351 if enabled by the instruction set), or a conditional branch, from being | |
| 352 automatically identified as a routine. The default is to inhibit this; specific | |
| 353 cases may be selectively overridden with the | |
| 354 .B \-r | |
| 355 option. | |
| 356 .TP | |
| 357 .B \--no-stupid-jumps | |
| 358 .TP | |
| 359 .B \-m | |
| 360 .TP | |
| 361 .B \--stupid-jumps | |
| 362 .TP | |
| 363 .B \-M | |
| 364 These options consider jumps or branches to the current address (such as | |
| 365 JMP *, BCC *) to be invalid or valid code depending on which is specified. | |
| 366 Note that BVC * is always accepted as the V flag can sometimes be toggled | |
| 367 by an external hardware signal. The default is to consider them | |
| 368 invalid otherwise. | |
| 369 .TP | |
| 370 .B \--no-allow-brk | |
| 371 .TP | |
| 372 .B \-w | |
| 373 .TP | |
| 374 .B \--allow-brk | |
| 375 .TP | |
| 376 .B \-W | |
| 377 These options control if BRK (or STP if enabled by the instruction set) should | |
| 378 be treated as a valid exit from a routine, just like RTS or RTI. The default | |
| 379 is not to do so. | |
| 380 .TP | |
| 381 .B \--no-suspect-branches | |
| 382 .TP | |
| 383 .B \-c | |
| 384 .TP | |
| 385 .B \--suspect-branches | |
| 386 .TP | |
| 387 .B \-C | |
| 388 These options are rarely needed, but account for the case where a program may | |
| 389 intentionally obfuscate its code using branches with unusual destination | |
| 390 addresses like LDA #2:BEQ *-1. In the default case, this would be considered | |
| 391 to be invalid and not treated as a routine | |
| 392 .RB ( \-c ); | |
| 393 if | |
| 394 .B \-C | |
| 395 is specified, it would be accepted as valid. | |
| 396 .SH BUGS/TO-DO | |
| 397 There are probably quite a few bugs yet to be found. | |
| 398 .LP | |
| 399 65816 opcodes are not (yet) supported. | |
| 400 .LP | |
| 401 There are a few options Marko created that aren't hooked up to anything (and | |
| 402 are not documented here on purpose). I might finish these later. | |
| 403 | |
| 404 .SH "SEE ALSO" | |
| 405 .BR xa (1), | |
| 406 .BR file65 (1), | |
| 407 .BR ldo65 (1), | |
| 408 .BR printcbm (1), | |
| 409 .BR reloc65 (1), | |
| 410 .BR uncpk (1) | |
| 411 | |
| 412 .SH AUTHOR | |
| 413 This manual page was written by Cameron Kaiser <ckaiser@floodgap.com>. | |
| 414 .B dxa | |
| 415 is based on | |
| 416 .B d65 | |
| 417 0.2.1 by Marko Mäkelä. | |
| 418 Original package (C)1993, 1994, 2000 Marko Mäkelä. Additional changes | |
|
14
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
419 (C)2006-2019 Cameron Kaiser. |
| 0 | 420 .B dxa |
| 421 is maintained independently. | |
| 422 | |
|
14
84c0facfc43c
Merge changes from upstream v0.1.4.
Matti Hamalainen <ccr@tnsp.org>
parents:
0
diff
changeset
|
423 .SH WEBSITE |
| 0 | 424 http://www.floodgap.com/retrotech/xa/ |