Mercurial > hg > forks > dxa

comparison dxa.1 @ 0:4410c9c7750d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial import.
author Matti Hamalainen <ccr@tnsp.org>
date Tue, 24 Feb 2015 18:53:52 +0200
parents
children 84c0facfc43c
comparison
equal deleted inserted replaced
-1:000000000000 0:4410c9c7750d
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/