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 zero 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 preceded with a '0' digit, as a hexadecimal value if preceded
152 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
153 start address 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>COMMENT</tt></tag>
317 This attribute is only allowed if a label is also given. It takes a string
318 as argument. See the description of the <tt><ref id="infofile-label"
319 name="LABEL"></tt> directive for an explanation.
321 <tag><tt>END</tt></tag>
322 This gives the end address of the range. The end address is inclusive, that
323 means, it is part of the range. Of course, it may not be smaller than the
326 <tag><tt>NAME</tt></tag>
327 This is a convenience attribute. It takes a string argument and will cause
328 the disassembler to define a label for the start of the range with the
329 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
330 directive is not needed.
332 <tag><tt>START</tt></tag>
333 This gives the start address of the range.
335 <tag><tt>TYPE</tt></tag>
336 This attribute specifies the type of data within the range. The attribute
337 value is one of the following keywords:
340 <tag><tt>ADDRTABLE</tt></tag>
341 The range consists of data and is disassembled as a table of words
342 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
343 a label is defined for each entry in the table.
345 <tag><tt>BYTETABLE</tt></tag>
346 The range consists of data and is disassembled as a byte table.
348 <tag><tt>CODE</tt></tag>
349 The range consists of code.
351 <tag><tt>DBYTETABLE</tt></tag>
352 The range consists of data and is disassembled as a table of dbytes
353 (double byte values, 16 bit values with the low byte containing the
354 most significant byte of the 16 bit value).
356 <tag><tt>DWORDTABLE</tt></tag>
357 The range consists of data and is disassembled as a table of double
358 words (32 bit values).
360 <tag><tt>RTSTABLE</tt></tag>
361 The range consists of data and is disassembled as a table of words (16 bit
362 values). The values are interpreted as words that are pushed onto the
363 stack and jump to it via <tt/RTS/. This means that they contain
364 <tt/address-1/ of a function, for which a label will get defined by the
367 <tag><tt>SKIP</tt></tag>
368 The range is simply ignored when generating the output file. Please note
369 that this means that reassembling the output file will <em/not/ generate
370 the original file, not only because the missing piece in between, but also
371 because the following code will be located on wrong addresses. Output
372 generated with <tt/SKIP/ ranges will need manual rework.
374 <tag><tt>TEXTTABLE</tt></tag>
375 The range consists of readable text.
377 <tag><tt>WORDTABLE</tt></tag>
378 The range consists of data and is disassembled as a table of words
386 <sect1>Specifying Labels<label id="infofile-label"><p>
388 The <tt/LABEL/ directive is used to give names for labels in the disassembled
389 code. The following attributes are recognized:
393 <tag><tt>ADDR</tt></tag>
394 Followed by a numerical value. Specifies the value of the label.
396 <tag><tt>COMMENT</tt></tag>
397 Attribute argument is a string. The comment will show up in a separate line
398 before the label, if the label is within code or data range, or after the
399 label if it is outside.
404 foo := $0001 ; Comment for label named "foo"
406 ; Comment for label named "bar"
410 <tag><tt>NAME</tt></tag>
411 The attribute is followed by a string value which gives the name of the
414 <tag><tt>SIZE</tt></tag>
415 This attribute is optional and may be used to specify the size of the data
416 that follows. If a size greater than 1 is specified, the disassembler will
417 create labels in the form <tt/label+offs/ for all bytes within the given
418 range, where <tt/label/ is the label name given with the <tt/NAME/
419 attribute, and <tt/offs/ is the offset within the data.
424 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
426 The <tt/ASMINC/ directive is used to give the names of input files containing
427 symbol assignments in assembler syntax:
434 The usual conventions apply for symbol names. Values may be specified as hex
435 (leading $), binary (leading %) or decimal. The values may optionally
438 NOTE: The include file parser is very simple. Expressions are not allowed, and
439 anything but symbol assignments is flagged as an error (but see the
440 <tt/IGNOREUNKNOWN/ directive below).
442 The following attributes are recognized:
446 <tag><tt>FILE</tt></tag>
447 Followed by a string value. Specifies the name of the file to read.
449 <tag><tt>COMMENTSTART</tt></tag>
450 The optional attribute is followed by a character constant. It specifies the
451 character that starts a comment. The default value is a semicolon. This
452 value is ignored if <tt/IGNOREUNKNOWN/ is true.
454 <tag><tt>IGNOREUNKNOWN</tt></tag>
455 This attribute is optional and is followed by a boolean value. It allows to
456 ignore input lines that don't have a valid syntax. This allows to read in
457 assembler include files that contain more than just symbol assignments.
458 Note: When this attribute is used, the disassembler will ignore any errors
459 in the given include file. This may have undesired side effects.
464 <sect1>An Info File Example<p>
466 The following is a short example for an info file that contains most of the
467 directives explained above:
470 # This is a comment. It extends to the end of the line
472 OUTPUTNAME "kernal.s";
473 INPUTNAME "kernal.bin";
475 PAGELENGTH 0; # No paging
480 RANGE { START $E612; END $E631; TYPE Code; };
481 RANGE { START $E632; END $E640; TYPE ByteTable; };
482 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
483 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
484 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
486 # Zero page variables
487 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
488 LABEL { NAME "sal"; ADDR $93; };
489 LABEL { NAME "sah"; ADDR $94; };
490 LABEL { NAME "sas"; ADDR $95; };
493 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
496 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
497 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
498 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
500 # Jump table at end of kernal ROM
501 LABEL { NAME "kscrorg"; ADDR $FFED; };
502 LABEL { NAME "kplot"; ADDR $FFF0; };
503 LABEL { NAME "kiobase"; ADDR $FFF3; };
504 LABEL { NAME "kgbye"; ADDR $FFF6; };
507 LABEL { NAME "hanmi"; ADDR $FFFA; };
508 LABEL { NAME "hares"; ADDR $FFFC; };
509 LABEL { NAME "hairq"; ADDR $FFFE; };
516 <sect>Bugs/Feedback<p>
518 If you have problems using the disassembler, if you find any bugs, or if
519 you're doing something interesting with the assembler, I would be glad to hear
520 from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
521 name="uz@cc65.org">).
527 da65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
528 Bassewitz. For usage of the binaries and/or sources the following
531 This software is provided 'as-is', without any expressed or implied
532 warranty. In no event will the authors be held liable for any damages
533 arising from the use of this software.
535 Permission is granted to anyone to use this software for any purpose,
536 including commercial applications, and to alter it and redistribute it
537 freely, subject to the following restrictions:
540 <item> The origin of this software must not be misrepresented; you must not
541 claim that you wrote the original software. If you use this software
542 in a product, an acknowledgment in the product documentation would be
543 appreciated but is not required.
544 <item> Altered source versions must be plainly marked as such, and must not
545 be misrepresented as being the original software.
546 <item> This notice may not be removed or altered from any source