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 --argument-column n Specify argument start column
59 --comment-column n Specify comment start column
60 --comments n Set the comment level for the output
61 --cpu type Set cpu type
62 --debug-info Add debug info to object file
63 --formfeeds Add formfeeds to the output
64 --help Help (this text)
65 --hexoffs Use hexadecimal label offsets
66 --info name Specify an info file
67 --label-break n Add newline if label exceeds length n
68 --mnemonic-column n Specify mnemonic start column
69 --pagelength n Set the page length for the listing
70 --start-addr addr Set the start/load address
71 --text-column n Specify text start column
72 --verbose Increase verbosity
73 --version Print the disassembler version
74 ---------------------------------------------------------------------------
78 <sect1>Command line options in detail<p>
80 Here is a description of all the command line options:
84 <label id="option--argument-column">
85 <tag><tt>--argument-column n</tt></tag>
87 Specifies the column where the argument for a mnemonic or pseudo instruction
91 <label id="option--comment-column">
92 <tag><tt>--comment-column n</tt></tag>
94 Specifies the column where the comment for an instruction starts.
97 <label id="option--comments">
98 <tag><tt>--comments n</tt></tag>
100 Set the comment level for the output. Valid arguments are 0..4. Greater
101 values will increase the level of additional information written to the
102 output file in form of comments.
105 <label id="option--cpu">
106 <tag><tt>--cpu type</tt></tag>
108 Set the CPU type. The option takes a parameter, which may be one of
112 Support for the 65816 is currently not available.
115 <label id="option--formfeeds">
116 <tag><tt>-F, --formfeeds</tt></tag>
118 Add formfeeds to the generated output. This feature is useful together
119 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
120 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
124 <tag><tt>-g, --debug-info</tt></tag>
126 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
127 assembler will generate debug information when reassembling the generated
131 <tag><tt>-h, --help</tt></tag>
133 Print the short option summary shown above.
136 <label id="option--hexoffs">
137 <tag><tt>--hexoffs</tt></tag>
139 Output label offsets in hexadecimal instead of decimal notation.
142 <label id="option--info">
143 <tag><tt>-i name, --info name</tt></tag>
145 Specify an info file. The info file contains global options that may
146 override or replace command line options plus informations about the code
147 that has to be disassembled. See the separate section <ref id="infofile"
148 name="Info File Format">.
151 <label id="option-o">
152 <tag><tt>-o name</tt></tag>
154 Specify a name for an output file. The default is to use <tt/stdout/, so
155 without this switch or the corresponding <ref id="global-options"
156 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
157 the output will go to the terminal.
160 <label id="option--label-break">
161 <tag><tt>--label-break n</tt></tag>
163 Adds a newline if the length of a label exceeds the given length.
164 Note: If the label would run into the code in the mid column, a
165 linefeed is always inserted regardless of this setting.
167 This option overrides the <ref id="global-options" name="global option">
168 <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
171 <label id="option--mnemonic-column">
172 <tag><tt>--mnemonic-column n</tt></tag>
174 Specifies the column where a mnemonic or pseudo instrcuction is output.
177 <label id="option--pagelength">
178 <tag><tt>--pagelength n</tt></tag>
180 Sets the length of a listing page in lines. After this number of lines, a
181 new page header is generated. If the <tt><ref id="option--formfeeds"
182 name="--formfeeds"></tt> is also given, a formfeed is inserted before
183 generating the page header.
185 A value of zero for the page length will disable paging of the output.
188 <label id="option--start-addr">
189 <tag><tt>-S addr, --start-addr addr</tt></tag>
191 Specify the start/load address of the binary code that is going to be
192 disassembled. The given address is interpreted as an octal value if
193 preceded with a '0' digit, as a hexadecimal value if preceded
194 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
195 start address is specified, $10000 minus the size of the input file is used.
198 <label id="option--text-column">
199 <tag><tt>--text-column n</tt></tag>
201 Specifies the column where additional text is output. This additional text
202 consists of the bytes encoded in this line in text representation.
205 <tag><tt>-v, --verbose</tt></tag>
207 Increase the disassembler verbosity. Usually only needed for debugging
208 purposes. You may use this option more than one time for even more
212 <tag><tt>-V, --version</tt></tag>
214 Print the version number of the assembler. If you send any suggestions
215 or bugfixes, please include the version number.
221 <sect>Detailed workings<p>
223 <sect1>Supported CPUs<p>
225 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
226 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
227 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
229 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
230 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
231 latter understands the same opcodes as the former, plus 16 additional bit
232 manipulation and bit test-and-branch commands.
234 While there is some code for the 65816 in the sources, it is currently
238 <sect1>Attribute map<p>
240 The disassembler works by creating an attribute map for the whole address
241 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
242 external info file (if given) is read. Disassembly is done in several passes.
243 In all passes with the exception of the last one, information about the
244 disassembled code is gathered and added to the symbol and attribute maps. The
245 last pass generates output using the information from the maps.
249 Some instructions may generate labels in the first pass, while most other
250 instructions do not generate labels, but use them if they are available. Among
251 others, the branch and jump instructions will generate labels for the target
252 of the branch in the first pass. External labels (taken from the info file)
253 have precedence over internally generated ones, They must be valid identifiers
254 as specified for the ca65 assembler. Internal labels (generated by the
255 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
256 address of the label in upper case letters. You should probably avoid using
257 such label names for external labels.
262 The info file is used to pass additional information about the input code to
263 the disassembler. This includes label names, data areas or tables, and global
264 options like input and output file names. See the <ref id="infofile"
265 name="next section"> for more information.
269 <sect>Info File Format<label id="infofile"><p>
271 The info file contains lists of specifications grouped together. Each group
272 directive has an identifying token and an attribute list enclosed in curly
273 braces. Attributes have a name followed by a value. The syntax of the value
274 depends on the type of the attribute. String attributes are places in double
275 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
276 with a leading dollar sign. There are also attributes where the attribute
277 value is a keyword, in this case the keyword is given as is (without quotes or
278 anything). Each attribute is terminated by a semicolon.
281 group-name { attribute1 attribute-value; attribute2 attribute-value; }
287 Comments start with a hash mark (<tt/#/) and extend from the position of
288 the mark to the end of the current line. Hash marks inside of strings will
289 of course <em/not/ start a comment.
292 <sect1>Specifying global options<label id="global-options"><p>
294 Global options may be specified in a group with the name <tt/GLOBAL/. The
295 following attributes are recognized:
299 <tag><tt/ARGUMENTCOLUMN/</tag>
300 This attribute specifies the column in the output, where the argument for
301 an opcode or pseudo instruction starts. The corresponding command line
303 <tt><ref id="option--argument-column" name="--argument-column"></tt>.
306 <tag><tt/COMMENTCOLUMN/</tag>
307 This attribute specifies the column in the output, where the comment starts
308 in a line. It is only used for in-line comments. The corresponding command
310 <tt><ref id="option--comment-column" name="--comment-column"></tt>.
313 <label id="COMMENTS">
314 <tag><tt/COMMENTS/</tag>
315 This attribute may be used instead of the <tt><ref id="option--comments"
316 name="--comments"></tt> option on the command line. It takes a numerical
317 parameter between 0 and 4. Higher values increase the amount of information
318 written to the output file in form of comments.
322 This attribute may be used instead of the <tt><ref id="option--cpu"
323 name="--cpu"></tt> option on the command line. It takes a string parameter.
326 <tag><tt/HEXOFFS/</tag>
327 The attribute is followed by a boolean value. If true, offsets to labels are
328 output in hex, otherwise they're output in decimal notation. The default is
329 false. The attribute may be changed on the command line using the <tt><ref
330 id="option--hexoffs" name="--hexoffs"></tt> option.
333 <tag><tt/INPUTNAME/</tag>
334 The attribute is followed by a string value, which gives the name of the
335 input file to read. If it is present, the disassembler does not accept an
336 input file name on the command line.
339 <tag><tt/INPUTOFFS/</tag>
340 The attribute is followed by a numerical value that gives an offset into
341 the input file which is skipped before reading data. The attribute may be
342 used to skip headers or unwanted code sections in the input file.
345 <tag><tt/INPUTSIZE/</tag>
346 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
347 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
351 <label id="LABELBREAK">
352 <tag><tt/LABELBREAK/</tag>
353 <tt/LABELBREAK/ is followed by a numerical value that specifies the label
354 length that will force a newline. To have all labels on their own lines,
355 you may set this value to zero.
357 See also the <tt><ref id="option--label-break" name="--label-break"></tt>
358 command line option. A <tt/LABELBREAK/ statement in the info file will
359 override any value given on the command line.
362 <tag><tt/MNEMONICCOLUMN/</tag>
363 This attribute specifies the column in the output, where the mnemonic or
364 pseudo instruction is placed. The corresponding command line option is
365 <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
368 <label id="OUTPUTNAME">
369 <tag><tt/OUTPUTNAME/</tag>
370 The attribute is followed by string value, which gives the name of the
371 output file to write. If it is present, specification of an output file on
372 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
375 The default is to use <tt/stdout/ for output, so without this attribute or
376 the corresponding command line option <tt/<ref id="option-o" name="-o">/
377 the output will go to the terminal.
380 <tag><tt/PAGELENGTH/</tag>
381 This attribute may be used instead of the <tt><ref id="option--pagelength"
382 name="--pagelength"></tt> option on the command line. It takes a numerical
383 parameter. Using zero as page length (which is the default) means that no
387 <tag><tt/STARTADDR/</tag>
388 This attribute may be used instead of the <tt><ref id="option--start-addr"
389 name="--start-addr"></tt> option on the command line. It takes a numerical
390 parameter. The default for the start address is $10000 minus the size of
391 the input file (this assumes that the input file is a ROM that contains the
392 reset and irq vectors).
395 <tag><tt/TEXTCOLUMN/</tag>
396 This attribute specifies the column, where the data bytes are output
397 translated into ASCII text. It is only used if
398 <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
399 corresponding command line option is
400 <tt><ref id="option--text-column" name="--text-column"></tt>.
405 <sect1>Specifying Ranges<p>
407 The <tt/RANGE/ directive is used to give information about address ranges. The
408 following attributes are recognized:
412 <tag><tt>COMMENT</tt></tag>
413 This attribute is only allowed if a label is also given. It takes a string
414 as argument. See the description of the <tt><ref id="infofile-label"
415 name="LABEL"></tt> directive for an explanation.
417 <tag><tt>END</tt></tag>
418 This gives the end address of the range. The end address is inclusive, that
419 means, it is part of the range. Of course, it may not be smaller than the
422 <tag><tt>NAME</tt></tag>
423 This is a convenience attribute. It takes a string argument and will cause
424 the disassembler to define a label for the start of the range with the
425 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
426 directive is not needed.
428 <tag><tt>START</tt></tag>
429 This gives the start address of the range.
431 <tag><tt>TYPE</tt></tag>
432 This attribute specifies the type of data within the range. The attribute
433 value is one of the following keywords:
436 <tag><tt>ADDRTABLE</tt></tag>
437 The range consists of data and is disassembled as a table of words
438 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
439 a label is defined for each entry in the table.
441 <tag><tt>BYTETABLE</tt></tag>
442 The range consists of data and is disassembled as a byte table.
444 <tag><tt>CODE</tt></tag>
445 The range consists of code.
447 <tag><tt>DBYTETABLE</tt></tag>
448 The range consists of data and is disassembled as a table of dbytes
449 (double byte values, 16 bit values with the low byte containing the
450 most significant byte of the 16 bit value).
452 <tag><tt>DWORDTABLE</tt></tag>
453 The range consists of data and is disassembled as a table of double
454 words (32 bit values).
456 <tag><tt>RTSTABLE</tt></tag>
457 The range consists of data and is disassembled as a table of words (16 bit
458 values). The values are interpreted as words that are pushed onto the
459 stack and jump to it via <tt/RTS/. This means that they contain
460 <tt/address-1/ of a function, for which a label will get defined by the
463 <tag><tt>SKIP</tt></tag>
464 The range is simply ignored when generating the output file. Please note
465 that this means that reassembling the output file will <em/not/ generate
466 the original file, not only because the missing piece in between, but also
467 because the following code will be located on wrong addresses. Output
468 generated with <tt/SKIP/ ranges will need manual rework.
470 <tag><tt>TEXTTABLE</tt></tag>
471 The range consists of readable text.
473 <tag><tt>WORDTABLE</tt></tag>
474 The range consists of data and is disassembled as a table of words
482 <sect1>Specifying Labels<label id="infofile-label"><p>
484 The <tt/LABEL/ directive is used to give names for labels in the disassembled
485 code. The following attributes are recognized:
489 <tag><tt>ADDR</tt></tag>
490 Followed by a numerical value. Specifies the value of the label.
492 <tag><tt>COMMENT</tt></tag>
493 Attribute argument is a string. The comment will show up in a separate line
494 before the label, if the label is within code or data range, or after the
495 label if it is outside.
500 foo := $0001 ; Comment for label named "foo"
502 ; Comment for label named "bar"
506 <tag><tt>NAME</tt></tag>
507 The attribute is followed by a string value which gives the name of the
508 label. Empty names are allowed, in this case the disassembler will create
509 an unnamed label (see the assembler docs for more information about unnamed
512 <tag><tt>SIZE</tt></tag>
513 This attribute is optional and may be used to specify the size of the data
514 that follows. If a size greater than 1 is specified, the disassembler will
515 create labels in the form <tt/label+offs/ for all bytes within the given
516 range, where <tt/label/ is the label name given with the <tt/NAME/
517 attribute, and <tt/offs/ is the offset within the data.
522 <sect1>Specifying Segments<label id="infofile-segment"><p>
524 The <tt/SEGMENT/ directive is used to specify a segment within the
525 disassembled code. The following attributes are recognized:
529 <tag><tt>START</tt></tag>
530 Followed by a numerical value. Specifies the start address of the segment.
532 <tag><tt>END</tt></tag>
533 Followed by a numerical value. Specifies the end address of the segment. The
534 end address is last the address that is part of the segment.
536 <tag><tt>NAME</tt></tag>
537 The attribute is followed by a string value which gives the name of the
541 All attributes are mandatory. Segments may not overlap. Since there is no
542 explicit "end this segment" pseudo op, the disassembler cannot notify the
543 assembler that one segment has ended. This may lead to errors if you don't
544 define your segments carefully. As a rule of thumb, if you're using segments,
545 your should define segments for all disassembled code.
548 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
550 The <tt/ASMINC/ directive is used to give the names of input files containing
551 symbol assignments in assembler syntax:
558 The usual conventions apply for symbol names. Values may be specified as hex
559 (leading $), binary (leading %) or decimal. The values may optionally
562 NOTE: The include file parser is very simple. Expressions are not allowed, and
563 anything but symbol assignments is flagged as an error (but see the
564 <tt/IGNOREUNKNOWN/ directive below).
566 The following attributes are recognized:
570 <tag><tt>FILE</tt></tag>
571 Followed by a string value. Specifies the name of the file to read.
573 <tag><tt>COMMENTSTART</tt></tag>
574 The optional attribute is followed by a character constant. It specifies the
575 character that starts a comment. The default value is a semicolon. This
576 value is ignored if <tt/IGNOREUNKNOWN/ is true.
578 <tag><tt>IGNOREUNKNOWN</tt></tag>
579 This attribute is optional and is followed by a boolean value. It allows to
580 ignore input lines that don't have a valid syntax. This allows to read in
581 assembler include files that contain more than just symbol assignments.
582 Note: When this attribute is used, the disassembler will ignore any errors
583 in the given include file. This may have undesired side effects.
588 <sect1>An Info File Example<p>
590 The following is a short example for an info file that contains most of the
591 directives explained above:
594 # This is a comment. It extends to the end of the line
596 OUTPUTNAME "kernal.s";
597 INPUTNAME "kernal.bin";
599 PAGELENGTH 0; # No paging
603 # One segment for the whole stuff
604 SEGMENT { START $E000; END $FFFF; NAME kernal; };
606 RANGE { START $E612; END $E631; TYPE Code; };
607 RANGE { START $E632; END $E640; TYPE ByteTable; };
608 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
609 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
610 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
612 # Zero page variables
613 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
614 LABEL { NAME "sal"; ADDR $93; };
615 LABEL { NAME "sah"; ADDR $94; };
616 LABEL { NAME "sas"; ADDR $95; };
619 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
622 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
623 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
624 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
626 # Jump table at end of kernal ROM
627 LABEL { NAME "kscrorg"; ADDR $FFED; };
628 LABEL { NAME "kplot"; ADDR $FFF0; };
629 LABEL { NAME "kiobase"; ADDR $FFF3; };
630 LABEL { NAME "kgbye"; ADDR $FFF6; };
633 LABEL { NAME "hanmi"; ADDR $FFFA; };
634 LABEL { NAME "hares"; ADDR $FFFC; };
635 LABEL { NAME "hairq"; ADDR $FFFE; };
642 <sect>Bugs/Feedback<p>
644 If you have problems using the disassembler, if you find any bugs, or if
645 you're doing something interesting with the assembler, I would be glad to hear
646 from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
647 name="uz@cc65.org">).
653 da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von
654 Bassewitz. For usage of the binaries and/or sources the following
657 This software is provided 'as-is', without any expressed or implied
658 warranty. In no event will the authors be held liable for any damages
659 arising from the use of this software.
661 Permission is granted to anyone to use this software for any purpose,
662 including commercial applications, and to alter it and redistribute it
663 freely, subject to the following restrictions:
666 <item> The origin of this software must not be misrepresented; you must not
667 claim that you wrote the original software. If you use this software
668 in a product, an acknowledgment in the product documentation would be
669 appreciated but is not required.
670 <item> Altered source versions must be plainly marked as such, and must not
671 be misrepresented as being the original software.
672 <item> This notice may not be removed or altered from any source