|
0
|
1 .TH DXA "1" "31 January 2007"
|
|
|
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.
|
|
|
92 For example, for a Commodore 64 binary with a
|
|
|
93 .B SYS 2064
|
|
|
94 header, add
|
|
|
95 .B \-r0810
|
|
|
96 so that disassembly starts at that location. This may have interactions with
|
|
|
97 datablock detection
|
|
|
98 .RB ( \-d ).
|
|
|
99 .TP
|
|
|
100 .B \--routines filename
|
|
|
101 .TP
|
|
|
102 .B \-R filename
|
|
|
103 Causes a list of routines to be read from file
|
|
|
104 .BR filename ,
|
|
|
105 one per line as if they had been specified on the command line.
|
|
|
106 .TP
|
|
|
107 .B \--addresses option
|
|
|
108 .TP
|
|
|
109 .B \-a option
|
|
|
110 Determines if and what kind of address information should be dumped with the
|
|
|
111 disassembly, if any. Note that this may make your output no longer intelligible
|
|
|
112 to
|
|
|
113 .BR xa (1).
|
|
|
114 The valid options are:
|
|
|
115 .RS
|
|
|
116 .TP
|
|
|
117 .B disabled
|
|
|
118 Dump source only with no address information. This is the default.
|
|
|
119 .TP
|
|
|
120 .B enabled
|
|
|
121 Write the current address at the beginning of each line.
|
|
|
122 .TP
|
|
|
123 .B dump
|
|
|
124 Write the current address at the beginning of each line, along with a hexdump
|
|
|
125 of the bytes for which the statement was generated.
|
|
|
126 .RE
|
|
|
127 .TP
|
|
|
128 .B \--colon-newline
|
|
|
129 .TP
|
|
|
130 .B \-N
|
|
|
131 .TP
|
|
|
132 .B \--no-colon-newline
|
|
|
133 .TP
|
|
|
134 .B \-n
|
|
|
135 A purely cosmetic option to determine how labels are emitted. Many people,
|
|
|
136 including myself, prefer a listing where the label is given, then a tab,
|
|
|
137 then the code
|
|
|
138 .RB ( \-n ).
|
|
|
139 Since this is
|
|
|
140 .I my
|
|
|
141 preference, it's the default. On the other hand, there are also many who
|
|
|
142 prefer to have the label demarcated by a colon and a newline, and the code
|
|
|
143 beginning indented on the next line. This is the way
|
|
|
144 .B d65
|
|
|
145 used to do it, and is still supported with
|
|
|
146 .BR \-N .
|
|
|
147 .TP
|
|
|
148 .B \--processor option
|
|
|
149 .TP
|
|
|
150 .B \-p option
|
|
|
151 Specify the instruction set. Note that specifying an instruction set that
|
|
|
152 permits and disassembles illegal and/or undocumented
|
|
|
153 NMOS opcodes may make your output unintelligible to
|
|
|
154 .BR xa (1).
|
|
|
155 Only one may be specified. The valid options are:
|
|
|
156 .RS
|
|
|
157 .TP
|
|
|
158 .B standard-nmos6502
|
|
|
159 Only official opcodes will be recognized. This is the default.
|
|
|
160 .TP
|
|
|
161 .B r65c02
|
|
|
162 Opcodes specific to the Rockwell 65C02 (R65C02) will also be allowed.
|
|
|
163 .TP
|
|
|
164 .B all-nmos6502
|
|
|
165 Allows all 256 NMOS opcodes to be disassembled, whether documented or
|
|
|
166 undocumented.
|
|
|
167 Note that instructions generated by this mode are not guaranteed to work on
|
|
|
168 all NMOS 6502s.
|
|
|
169 .TP
|
|
|
170 .B rational-nmos6502
|
|
|
171 Only allows "rational" undocumented instructions. This excludes ANE, SHA,
|
|
|
172 SHS, SHY, SHX, LXA and LAXS. This is a judgment call.
|
|
|
173 .TP
|
|
|
174 .B useful-nmos6502
|
|
|
175 Only allows "useful" undocumented instructions. This excludes ANE, SHA,
|
|
|
176 SHS, SHY, SHX, LXA, LAXS, NOOP and STP. This is a judgment call.
|
|
|
177 .TP
|
|
|
178 .B traditional-nmos6502
|
|
|
179 Only allows the most widely accepted undocumented instructions based on
|
|
|
180 combinations of ALU and RMW operations. This excludes ANE, SHA, SHS, SHY,
|
|
|
181 SHX, LXA, LAXS, NOOP, STP, ARR, ASR, ANC, SBX and USBC.
|
|
|
182 This is a judgment call.
|
|
|
183 .RE
|
|
|
184 .TP
|
|
|
185 .B \--get-sa
|
|
|
186 .TP
|
|
|
187 .B \-G
|
|
|
188 .TP
|
|
|
189 .B \--no-get-sa xxxx
|
|
|
190 .TP
|
|
|
191 .B \-g xxxx
|
|
|
192 Enables or disables automatic starting address detection. If enabled (the
|
|
|
193 default),
|
|
|
194 .B dxa
|
|
|
195 looks at the first two bytes as a 16-bit word in 6502 little-endian format
|
|
|
196 and considers that to be the starting address for the object, discarding them
|
|
|
197 without further interpretation. This is very useful for Commodore computers in
|
|
|
198 particular. If your binary does not have a starting address, you must
|
|
|
199 specify one using
|
|
|
200 .B \-g
|
|
|
201 or
|
|
|
202 .B \--no-get-sa
|
|
|
203 followed by a hexadecimal address. The starting address will then be encoded
|
|
|
204 into the output using
|
|
|
205 .BR "* =" .
|
|
|
206 .TP
|
|
|
207 .B \--no-word-sa
|
|
|
208 .TP
|
|
|
209 .B \-q
|
|
|
210 .TP
|
|
|
211 .B \--word-sa
|
|
|
212 .TP
|
|
|
213 .B \-Q
|
|
|
214 Only relevant if automatic starting address detection is enabled. If so,
|
|
|
215 the default is to also emit the starting address as a
|
|
|
216 .B \&.word
|
|
|
217 pseudo-op before the starting address indicated with
|
|
|
218 .B * =
|
|
|
219 so that it will be regenerated on re-assembly
|
|
|
220 .RB ( \-Q ).
|
|
|
221 Otherwise, if this option is disabled, the starting address word will not be
|
|
|
222 re-emitted and
|
|
|
223 will need to be tacked back on if the target requires it. If you specify an
|
|
|
224 address with
|
|
|
225 .BR \-g ,
|
|
|
226 then that address will be used here too.
|
|
|
227 .TP
|
|
|
228 .B \--verbose
|
|
|
229 .TP
|
|
|
230 .B \-v
|
|
|
231 Enables verbose output, which may or may not be useful in the same way that
|
|
|
232 Schroedinger's Cat may or may not be dead.
|
|
|
233 .TP
|
|
|
234 .B \--help
|
|
|
235 .TP
|
|
|
236 .B \-?
|
|
|
237 .TP
|
|
|
238 .B \-V
|
|
|
239 A quick summary of options.
|
|
|
240 .LP
|
|
|
241 The following options control how program code is scanned and determined
|
|
|
242 to be a valid (or invalid) portion of a putative routine.
|
|
|
243 .TP
|
|
|
244 .B \--datablock-detection option
|
|
|
245 .TP
|
|
|
246 .B \-d option
|
|
|
247 This controls how the program automatically detects data blocks for addresses
|
|
|
248 where no previous hints are specified. Only one method may be specified.
|
|
|
249 The valid options are:
|
|
|
250 .RS
|
|
|
251 .TP
|
|
|
252 .B poor
|
|
|
253 As much as the object as possible will be listed as program code, even if
|
|
|
254 there are illegal instructions present. This is the default.
|
|
|
255 .TP
|
|
|
256 .B strict
|
|
|
257 Assumes that all declared routines call and execute only valid instructions. If
|
|
|
258 any portion of code declared as a routine leads to an address block containing
|
|
|
259 illegal opcodes, a consistency error will occur and disassembly will stop.
|
|
|
260 .TP
|
|
|
261 .B skip-scanning
|
|
|
262 Program addresses that are not referenced by any routine will not be scanned
|
|
|
263 for valid routines (thus data a priori).
|
|
|
264 .RE
|
|
|
265 .TP
|
|
|
266 .B \--no-external-labels
|
|
|
267 .TP
|
|
|
268 .B \-e
|
|
|
269 .TP
|
|
|
270 .B \--external-labels
|
|
|
271 .TP
|
|
|
272 .B \-E
|
|
|
273 Controls whether labels should be generated for addresses outside of the
|
|
|
274 program itself. The default is not to (i.e., leave the addresses absolute).
|
|
|
275 .TP
|
|
|
276 .B \--address-tables option
|
|
|
277 .TP
|
|
|
278 .B \-t option
|
|
|
279 Controls detection of address tables/dispatch tables. The following options
|
|
|
280 are available:
|
|
|
281 .RS
|
|
|
282 .TP
|
|
|
283 .B ignore
|
|
|
284 Don't attempt to detect address tables.
|
|
|
285 .TP
|
|
|
286 .B detect-all
|
|
|
287 Address tables referencing any label will be detected.
|
|
|
288 .TP
|
|
|
289 .B detect-internal
|
|
|
290 Address tables with labels whose addresses lie within the program's address
|
|
|
291 range will be detected. This is the default.
|
|
|
292 .RE
|
|
|
293 .TP
|
|
|
294 .B \--no-suspect-jsr
|
|
|
295 .TP
|
|
|
296 .B \-j
|
|
|
297 .TP
|
|
|
298 .B \--suspect-jsr
|
|
|
299 .TP
|
|
|
300 .B \-J
|
|
|
301 These options indicate whether JSRs are always expected to return to the
|
|
|
302 following instruction or not. This will affect how routines are parsed. For
|
|
|
303 example, the Commodore 128 KERNAL has a routine called PRIMM that prints a
|
|
|
304 null-terminated string directly following the JSR instruction, returning after
|
|
|
305 the null byte. In this case,
|
|
|
306 .B \-J
|
|
|
307 should be specified to alert the disassembler that this is possible. The
|
|
|
308 default is to expect "normal" JSRs (i.e.,
|
|
|
309 .BR \-j ).
|
|
|
310 .TP
|
|
|
311 .B \--no-one-byte-routines
|
|
|
312 .TP
|
|
|
313 .B \-o
|
|
|
314 .TP
|
|
|
315 .B \--one-byte-routines
|
|
|
316 .TP
|
|
|
317 .B \-O
|
|
|
318 These options permit or inhibit a single RTS, RTI or BRK instruction (or STP
|
|
|
319 if enabled by the instruction set), or a conditional branch, from being
|
|
|
320 automatically identified as a routine. The default is to inhibit this; specific
|
|
|
321 cases may be selectively overridden with the
|
|
|
322 .B \-r
|
|
|
323 option.
|
|
|
324 .TP
|
|
|
325 .B \--no-stupid-jumps
|
|
|
326 .TP
|
|
|
327 .B \-m
|
|
|
328 .TP
|
|
|
329 .B \--stupid-jumps
|
|
|
330 .TP
|
|
|
331 .B \-M
|
|
|
332 These options consider jumps or branches to the current address (such as
|
|
|
333 JMP *, BCC *) to be invalid or valid code depending on which is specified.
|
|
|
334 Note that BVC * is always accepted as the V flag can sometimes be toggled
|
|
|
335 by an external hardware signal. The default is to consider them
|
|
|
336 invalid otherwise.
|
|
|
337 .TP
|
|
|
338 .B \--no-allow-brk
|
|
|
339 .TP
|
|
|
340 .B \-w
|
|
|
341 .TP
|
|
|
342 .B \--allow-brk
|
|
|
343 .TP
|
|
|
344 .B \-W
|
|
|
345 These options control if BRK (or STP if enabled by the instruction set) should
|
|
|
346 be treated as a valid exit from a routine, just like RTS or RTI. The default
|
|
|
347 is not to do so.
|
|
|
348 .TP
|
|
|
349 .B \--no-suspect-branches
|
|
|
350 .TP
|
|
|
351 .B \-c
|
|
|
352 .TP
|
|
|
353 .B \--suspect-branches
|
|
|
354 .TP
|
|
|
355 .B \-C
|
|
|
356 These options are rarely needed, but account for the case where a program may
|
|
|
357 intentionally obfuscate its code using branches with unusual destination
|
|
|
358 addresses like LDA #2:BEQ *-1. In the default case, this would be considered
|
|
|
359 to be invalid and not treated as a routine
|
|
|
360 .RB ( \-c );
|
|
|
361 if
|
|
|
362 .B \-C
|
|
|
363 is specified, it would be accepted as valid.
|
|
|
364 .SH BUGS/TO-DO
|
|
|
365 There are probably quite a few bugs yet to be found.
|
|
|
366 .LP
|
|
|
367 65816 opcodes are not (yet) supported.
|
|
|
368 .LP
|
|
|
369 The disassembler can easily be confused by the common idiom of tacking on
|
|
|
370 BASIC text to call an appended ML routine. There probably should be a special
|
|
|
371 case option for this. One workaround is to use the
|
|
|
372 .B \--datablock
|
|
|
373 option and specify the range as unused (such as in the case of
|
|
|
374 .B 10 SYS2061
|
|
|
375 (Commodore), giving
|
|
|
376 .B \-b ?0801-080c
|
|
|
377 to ignore that range as data).
|
|
|
378 .LP
|
|
|
379 There are a few options Marko created that aren't hooked up to anything (and
|
|
|
380 are not documented here on purpose). I might finish these later.
|
|
|
381
|
|
|
382 .SH "SEE ALSO"
|
|
|
383 .BR xa (1),
|
|
|
384 .BR file65 (1),
|
|
|
385 .BR ldo65 (1),
|
|
|
386 .BR printcbm (1),
|
|
|
387 .BR reloc65 (1),
|
|
|
388 .BR uncpk (1)
|
|
|
389
|
|
|
390 .SH AUTHOR
|
|
|
391 This manual page was written by Cameron Kaiser <ckaiser@floodgap.com>.
|
|
|
392 .B dxa
|
|
|
393 is based on
|
|
|
394 .B d65
|
|
|
395 0.2.1 by Marko Mäkelä.
|
|
|
396 Original package (C)1993, 1994, 2000 Marko Mäkelä. Additional changes
|
|
|
397 (C)2006 Cameron Kaiser.
|
|
|
398 .B dxa
|
|
|
399 is maintained independently.
|
|
|
400
|
|
|
401 .SHWEBSITE
|
|
|
402 http://www.floodgap.com/retrotech/xa/
|
