1 <!doctype linuxdoc system>
4 <title>da65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
9 da65 is a 6502/65C02 disassembler that is able to read user supplied
10 information about its input data for better results. The output is ready for
11 feeding into ca65, the macro assembler supplied with the cc65 C compiler.
14 <!-- Table of contents -->
17 <!-- Begin the document -->
21 da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
22 the cc65 C compiler and generates output that is suitable for the ca65
25 Besides generating output for ca65, one of the design goals was that the user
26 is able to feed additional information about the code into the disassembler
27 for improved results. This information may include the location and size of
28 tables, and their format.
30 One nice advantage of this concept is that disassembly of copyrighted binaries
31 may be handled without problems: One can just pass the information file for
32 disassembling the binary, so everyone with a legal copy of the binary can
33 generate a nicely formatted disassembly with readable labels and other
40 <sect1>Command line option overview<p>
42 The assembler accepts the following options:
45 ---------------------------------------------------------------------------
46 Usage: da65 [options] [inputfile]
48 -g Add debug info to object file
50 -i name Specify an info file
51 -o name Name the output file
53 -F Add formfeeds to the output
54 -S addr Set the start/load address
55 -V Print the disassembler version
58 --comments n Set the comment level for the output
59 --cpu type Set cpu type
60 --debug-info Add debug info to object file
61 --formfeeds Add formfeeds to the output
62 --help Help (this text)
63 --info name Specify an info file
64 --pagelength n Set the page length for the listing
65 --start-addr addr Set the start/load address
66 --verbose Increase verbosity
67 --version Print the disassembler version
68 ---------------------------------------------------------------------------
72 <sect1>Command line options in detail<p>
74 Here is a description of all the command line options:
78 <label id="option--comments">
79 <tag><tt>--comments n</tt></tag>
81 Set the comment level for the output. Valid arguments are 0..4. Greater
82 values will increase the level of additional information written to the
83 output file in form of comments.
86 <label id="option--cpu">
87 <tag><tt>--cpu type</tt></tag>
89 Set the CPU type. The option takes a parameter, which may be one of
93 Support for the 65816 is currently not available.
96 <label id="option--formfeeds">
97 <tag><tt>-F, --formfeeds</tt></tag>
99 Add formfeeds to the generated output. This feature is useful together
100 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
101 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
105 <tag><tt>-g, --debug-info</tt></tag>
107 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
108 assembler will generate debug information when reassembling the generated
112 <tag><tt>-h, --help</tt></tag>
114 Print the short option summary shown above.
117 <label id="option--info">
118 <tag><tt>-i name, --info name</tt></tag>
120 Specify an info file. The info file contains global options that may
121 override or replace command line options plus informations about the code
122 that has to be disassembled. See the separate section <ref id="infofile"
123 name="Info File Format">.
126 <label id="option-o">
127 <tag><tt>-o name</tt></tag>
129 The default output name is the name of the input file with the extension
130 replaced by ".dis". If you don't like that, you may give another name with
131 the -o option. The output file will be placed in the same directory as
132 the source file, or, if -o is given, the full path in this name is used.
135 <label id="option--pagelength">
136 <tag><tt>--pagelength n</tt></tag>
138 Sets the length of a listing page in lines. After this number of lines, a
139 new page header is generated. If the <tt><ref id="option--formfeeds"
140 name="--formfeeds"></tt> is also given, a formfeed is inserted before
141 generating the page header.
143 A value of -1 for the page length will disable paging of the output.
146 <label id="option--start-addr">
147 <tag><tt>-S addr, --start-addr addr</tt></tag>
149 Specify the start/load address of the binary code that is going to be
150 disassembled. The given address is interpreted as an octal value if
151 preceeded with a '0' digit, as a hexadecimal value if preceeded with '0x',
152 '0X', or '$', and as a decimal value in all other cases. If no start address
153 is specified, $10000 minus the size of the input file is used.
156 <tag><tt>-v, --verbose</tt></tag>
158 Increase the disassembler verbosity. Usually only needed for debugging
159 purposes. You may use this option more than one time for even more
163 <tag><tt>-V, --version</tt></tag>
165 Print the version number of the assembler. If you send any suggestions
166 or bugfixes, please include the version number.
172 <sect>Detailed workings<p>
174 <sect1>Supported CPUs<p>
176 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
177 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
178 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
180 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
181 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
182 latter understands the same opcodes as the former, plus 16 additional bit
183 manipulation and bit test-and-branch commands.
185 While there is some code for the 65816 in the sources, it is currently
189 <sect1>Attribute map<p>
191 The disassembler works by creating an attribute map for the whole address
192 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
193 external info file (if given) is read. Disassembly is done in several passes.
194 In all passes with the exception of the last one, information about the
195 disassembled code is gathered and added to the symbol and attribute maps. The
196 last pass generates output using the information from the maps.
200 Some instructions may generate labels in the first pass, while most other
201 instructions do not generate labels, but use them if they are available. Among
202 others, the branch and jump instructions will generate labels for the target
203 of the branch in the first pass. External labels (taken from the info file)
204 have precedence over internally generated ones, They must be valid identifiers
205 as specified for the ca65 assembler. Internal labels (generated by the
206 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
207 address of the label in upper case letters. You should probably avoid using
208 such label names for external labels.
213 The info file is used to pass additional information about the input code to
214 the disassembler. This includes label names, data areas or tables, and global
215 options like input and output file names. See the <ref id="infofile"
216 name="next section"> for more information.
220 <sect>Info File Format<p><label id="infofile">
222 The info file contains lists of specifications grouped together. Each group
223 directive has an identifying token and an attribute list enclosed in curly
224 braces. Attributes have a name followed by a value. The syntax of the value
225 depends on the type of the attribute. String attributes are places in double
226 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
227 with a leading dollar sign. There are also attributes where the attribute
228 value is a keyword, in this case the keyword is given as is (without quotes or
229 anything). Each attribute is terminated by a semicolon.
232 group-name { attribute1 attribute-value; attribute2 attribute-value; }
236 <sect1>Specifying global options<p>
238 Global options may be specified in a group with the name <tt/GLOBAL/. The
239 following attributes are recognized:
243 <tag><tt>COMMENTS</tt></tag>
245 This attribute may be used instead of the <tt><ref id="option--comments"
246 name="--comments"></tt> option on the command line. It takes a numerical
247 parameter between 0 and 4. Higher values increase the amount of information
248 written to the output file in form of comments.
251 <tag><tt>CPU</tt></tag>
253 This attribute may be used instead of the <tt><ref id="option--cpu"
254 name="--cpu"></tt> option on the command line. It takes a string parameter.
257 <tag><tt>INPUTNAME</tt></tag>
259 The attribute is followed by a string value, which gives the name of the
260 input file to read. If it is present, the disassembler does not accept an
261 input file name on the command line.
264 <tag><tt>OUTPUTNAME</tt></tag>
266 The attribute is followed by string value, which gives the name of the
267 output file to write. If it is present, specification of an output file on
268 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
271 If no output name is specified, the name of the input file with the
272 extension replaced by ".dis" is used.
275 <tag><tt>PAGELENGTH</tt></tag>
277 This attribute may be used instead of the <tt><ref id="option--pagelength"
278 name="--pagelength"></tt> option on the command line. It takes a numerical
279 parameter. Using zero as page length (which is the default) means that no
283 <tag><tt>STARTADDR</tt></tag>
285 This attribute may be used instead of the <tt><ref id="option--start-addr"
286 name="--start-addr"></tt> option on the command line. It takes a numerical
287 parameter. The default for the start address is $10000 minus the size of
288 the input file (this assumes that the input file is a ROM that contains the
289 reset and irq vectors).
294 <sect1>Specifying Ranges<p>
296 The <tt/RANGE/ directive is used to give information about address ranges. The
297 following attributes are recognized:
301 <tag><tt>START</tt></tag>
303 This gives the start address of the range.
306 <tag><tt>END</tt></tag>
308 This gives the end address of the range. The end address is inclusive, that
309 means, it is part of the range. Of course, it may not be smaller than the
313 <tag><tt>TYPE</tt></tag>
315 This attribute specifies the type of data within the range. The attribute
316 value is one of the following keywords:
319 <tag><tt>CODE</tt></tag>
320 The range consists of code.
322 <tag><tt>BYTETABLE</tt></tag>
323 The range consists of data and is disassembled as a byte table.
325 <tag><tt>DBYTETABLE</tt></tag>
326 The range consists of data and is disassembled as a table of dbytes
327 (double byte values, 16 bit values with the low byte containing the
328 most significant byte of the 16 bit value).
330 <tag><tt>WORDTABLE</tt></tag>
331 The range consists of data and is disassembled as a table of words
334 <tag><tt>DWORDTABLE</tt></tag>
335 The range consists of data and is disassembled as a table of double
336 words (32 bit values).
338 <tag><tt>ADDRTABLE</tt></tag>
339 The range consists of data and is disassembled as a table of words
340 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
341 a label is defined for each entry in the table.
343 <tag><tt>RTSTABLE</tt></tag>
344 The range consists of data and is disassembled as a table of words (16 bit
345 values). The values are interpreted as words that are pushed onto the
346 stack and jump to it via <tt/RTS/. This means that they contain
347 <tt/address-1/ of a function, for which a label will get defined by the
350 <tag><tt>TEXTTABLE</tt></tag>
351 The range consists of readable text.
357 <sect1>Specifying Labels<p>
359 The <tt/LABEL/ directive is used to give names for labels in the disassembled
360 code. The following attributes are recognized:
364 <tag><tt>NAME</tt></tag>
366 The attribute is followed by a string value which gives the name of the
370 <tag><tt>ADDR</tt></tag>
372 Followed by a numerical value. Specifies the value of the label.
375 <tag><tt>SIZE</tt></tag>
377 This attribute is optional and may be used to specifiy the size of the data
378 that follows. If a size greater than 1 is specified, the disassembler will
379 create labels in the form <tt/label+offs/ for all bytes within the given
380 range, where <tt/label/ is the label name given with the <tt/NAME/
381 attribute, and <tt/offs/ is the offset within the data.
386 <sect1>An Info File Example<p>
388 The following is a short example for an info file that contains most of the
389 directives explained above:
393 OUTPUTNAME "kernal.s";
394 INPUTNAME "kernal.bin";
396 PAGELENGTH 0; # No paging
401 RANGE { START $E612; END $E631; TYPE Code; };
402 RANGE { START $E632; END $E640; TYPE ByteTable; };
403 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
404 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
405 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
407 # Zero page variables
408 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
409 LABEL { NAME "sal"; ADDR $93; };
410 LABEL { NAME "sah"; ADDR $94; };
411 LABEL { NAME "sas"; ADDR $95; };
414 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
417 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
418 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
419 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
421 # Jump table at end of kernal ROM
422 LABEL { NAME "kscrorg"; ADDR $FFED; };
423 LABEL { NAME "kplot"; ADDR $FFF0; };
424 LABEL { NAME "kiobase"; ADDR $FFF3; };
425 LABEL { NAME "kgbye"; ADDR $FFF6; };
428 LABEL { NAME "hanmi"; ADDR $FFFA; };
429 LABEL { NAME "hares"; ADDR $FFFC; };
430 LABEL { NAME "hairq"; ADDR $FFFE; };
437 <sect>Bugs/Feedback<p>
439 If you have problems using the disassembler, if you find any bugs, or if
440 you're doing something interesting with the assembler, I would be glad to hear
441 from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
442 name="uz@cc65.org">).
448 da65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
449 Bassewitz. For usage of the binaries and/or sources the following
452 This software is provided 'as-is', without any expressed or implied
453 warranty. In no event will the authors be held liable for any damages
454 arising from the use of this software.
456 Permission is granted to anyone to use this software for any purpose,
457 including commercial applications, and to alter it and redistribute it
458 freely, subject to the following restrictions:
461 <item> The origin of this software must not be misrepresented; you must not
462 claim that you wrote the original software. If you use this software
463 in a product, an acknowledgment in the product documentation would be
464 appreciated but is not required.
465 <item> Altered source versions must be plainly marked as such, and must not
466 be misrepresented as being the original software.
467 <item> This notice may not be removed or altered from any source