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 Specify a name for an output file. The default is to use <tt/stdout/, so
130 without this switch or the corresponding <ref id="global-options"
131 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
132 the output will go to the terminal.
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<label id="infofile"><p>
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; }
238 Comments start with a hash mark (<tt/#/) and extend from the position of
239 the mark to the end of the current line. Hash marks inside of strings will
240 of course <em/not/ start a comment.
243 <sect1>Specifying global options<label id="global-options"><p>
245 Global options may be specified in a group with the name <tt/GLOBAL/. The
246 following attributes are recognized:
250 <tag><tt>COMMENTS</tt></tag>
251 This attribute may be used instead of the <tt><ref id="option--comments"
252 name="--comments"></tt> option on the command line. It takes a numerical
253 parameter between 0 and 4. Higher values increase the amount of information
254 written to the output file in form of comments.
257 <tag><tt>CPU</tt></tag>
258 This attribute may be used instead of the <tt><ref id="option--cpu"
259 name="--cpu"></tt> option on the command line. It takes a string parameter.
262 <tag><tt>INPUTNAME</tt></tag>
263 The attribute is followed by a string value, which gives the name of the
264 input file to read. If it is present, the disassembler does not accept an
265 input file name on the command line.
268 <tag><tt>INPUTOFFS</tt></tag>
269 The attribute is followed by a numerical value that gives an offset into
270 the input file which is skipped before reading data. The attribute may be
271 used to skip headers or unwanted code sections in the input file.
274 <tag><tt>INPUTSIZE</tt></tag>
275 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
276 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
280 <label id="OUTPUTNAME">
281 <tag><tt>OUTPUTNAME</tt></tag>
282 The attribute is followed by string value, which gives the name of the
283 output file to write. If it is present, specification of an output file on
284 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
287 The default is to use <tt/stdout/ for output, so without this attribute or
288 the corresponding command line option <tt/<ref id="option-o" name="-o">/
289 the output will go to the terminal.
292 <tag><tt>PAGELENGTH</tt></tag>
293 This attribute may be used instead of the <tt><ref id="option--pagelength"
294 name="--pagelength"></tt> option on the command line. It takes a numerical
295 parameter. Using zero as page length (which is the default) means that no
299 <tag><tt>STARTADDR</tt></tag>
300 This attribute may be used instead of the <tt><ref id="option--start-addr"
301 name="--start-addr"></tt> option on the command line. It takes a numerical
302 parameter. The default for the start address is $10000 minus the size of
303 the input file (this assumes that the input file is a ROM that contains the
304 reset and irq vectors).
309 <sect1>Specifying Ranges<p>
311 The <tt/RANGE/ directive is used to give information about address ranges. The
312 following attributes are recognized:
316 <tag><tt>END</tt></tag>
317 This gives the end address of the range. The end address is inclusive, that
318 means, it is part of the range. Of course, it may not be smaller than the
321 <tag><tt>NAME</tt></tag>
322 This is a convenience attribute. It takes a string argument and will cause
323 the disassembler to define a label for the start of the range with the
324 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
325 directive is not needed.
327 <tag><tt>START</tt></tag>
328 This gives the start address of the range.
330 <tag><tt>TYPE</tt></tag>
331 This attribute specifies the type of data within the range. The attribute
332 value is one of the following keywords:
335 <tag><tt>ADDRTABLE</tt></tag>
336 The range consists of data and is disassembled as a table of words
337 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
338 a label is defined for each entry in the table.
340 <tag><tt>BYTETABLE</tt></tag>
341 The range consists of data and is disassembled as a byte table.
343 <tag><tt>CODE</tt></tag>
344 The range consists of code.
346 <tag><tt>DBYTETABLE</tt></tag>
347 The range consists of data and is disassembled as a table of dbytes
348 (double byte values, 16 bit values with the low byte containing the
349 most significant byte of the 16 bit value).
351 <tag><tt>DWORDTABLE</tt></tag>
352 The range consists of data and is disassembled as a table of double
353 words (32 bit values).
355 <tag><tt>RTSTABLE</tt></tag>
356 The range consists of data and is disassembled as a table of words (16 bit
357 values). The values are interpreted as words that are pushed onto the
358 stack and jump to it via <tt/RTS/. This means that they contain
359 <tt/address-1/ of a function, for which a label will get defined by the
362 <tag><tt>SKIP</tt></tag>
363 The range is simply ignored when generating the output file. Please note
364 that this means that reassembling the output file will <em/not/ generate
365 the original file, not only because the missing piece in between, but also
366 because the following code will be located on wrong addresses. Output
367 generated with <tt/SKIP/ ranges will need manual rework.
369 <tag><tt>TEXTTABLE</tt></tag>
370 The range consists of readable text.
372 <tag><tt>WORDTABLE</tt></tag>
373 The range consists of data and is disassembled as a table of words
381 <sect1>Specifying Labels<label id="infofile-label"><p>
383 The <tt/LABEL/ directive is used to give names for labels in the disassembled
384 code. The following attributes are recognized:
388 <tag><tt>ADDR</tt></tag>
389 Followed by a numerical value. Specifies the value of the label.
391 <tag><tt>NAME</tt></tag>
392 The attribute is followed by a string value which gives the name of the
395 <tag><tt>SIZE</tt></tag>
396 This attribute is optional and may be used to specifiy the size of the data
397 that follows. If a size greater than 1 is specified, the disassembler will
398 create labels in the form <tt/label+offs/ for all bytes within the given
399 range, where <tt/label/ is the label name given with the <tt/NAME/
400 attribute, and <tt/offs/ is the offset within the data.
405 <sect1>An Info File Example<p>
407 The following is a short example for an info file that contains most of the
408 directives explained above:
411 # This is a comment. It extends to the end of the line
413 OUTPUTNAME "kernal.s";
414 INPUTNAME "kernal.bin";
416 PAGELENGTH 0; # No paging
421 RANGE { START $E612; END $E631; TYPE Code; };
422 RANGE { START $E632; END $E640; TYPE ByteTable; };
423 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
424 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
425 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
427 # Zero page variables
428 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
429 LABEL { NAME "sal"; ADDR $93; };
430 LABEL { NAME "sah"; ADDR $94; };
431 LABEL { NAME "sas"; ADDR $95; };
434 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
437 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
438 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
439 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
441 # Jump table at end of kernal ROM
442 LABEL { NAME "kscrorg"; ADDR $FFED; };
443 LABEL { NAME "kplot"; ADDR $FFF0; };
444 LABEL { NAME "kiobase"; ADDR $FFF3; };
445 LABEL { NAME "kgbye"; ADDR $FFF6; };
448 LABEL { NAME "hanmi"; ADDR $FFFA; };
449 LABEL { NAME "hares"; ADDR $FFFC; };
450 LABEL { NAME "hairq"; ADDR $FFFE; };
457 <sect>Bugs/Feedback<p>
459 If you have problems using the disassembler, if you find any bugs, or if
460 you're doing something interesting with the assembler, I would be glad to hear
461 from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
462 name="uz@cc65.org">).
468 da65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
469 Bassewitz. For usage of the binaries and/or sources the following
472 This software is provided 'as-is', without any expressed or implied
473 warranty. In no event will the authors be held liable for any damages
474 arising from the use of this software.
476 Permission is granted to anyone to use this software for any purpose,
477 including commercial applications, and to alter it and redistribute it
478 freely, subject to the following restrictions:
481 <item> The origin of this software must not be misrepresented; you must not
482 claim that you wrote the original software. If you use this software
483 in a product, an acknowledgment in the product documentation would be
484 appreciated but is not required.
485 <item> Altered source versions must be plainly marked as such, and must not
486 be misrepresented as being the original software.
487 <item> This notice may not be removed or altered from any source