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
110 6502, 6502x, 65sc02, 65c02, huc6280
112 6502x is the NMOS 6502 with illegal opcodes. huc6280 is the CPU of the PC
113 engine. Support for the 65816 is currently not available.
116 <label id="option--formfeeds">
117 <tag><tt>-F, --formfeeds</tt></tag>
119 Add formfeeds to the generated output. This feature is useful together
120 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
121 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
125 <tag><tt>-g, --debug-info</tt></tag>
127 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
128 assembler will generate debug information when reassembling the generated
132 <tag><tt>-h, --help</tt></tag>
134 Print the short option summary shown above.
137 <label id="option--hexoffs">
138 <tag><tt>--hexoffs</tt></tag>
140 Output label offsets in hexadecimal instead of decimal notation.
143 <label id="option--info">
144 <tag><tt>-i name, --info name</tt></tag>
146 Specify an info file. The info file contains global options that may
147 override or replace command line options plus informations about the code
148 that has to be disassembled. See the separate section <ref id="infofile"
149 name="Info File Format">.
152 <label id="option-o">
153 <tag><tt>-o name</tt></tag>
155 Specify a name for an output file. The default is to use <tt/stdout/, so
156 without this switch or the corresponding <ref id="global-options"
157 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
158 the output will go to the terminal.
161 <label id="option--label-break">
162 <tag><tt>--label-break n</tt></tag>
164 Adds a newline if the length of a label exceeds the given length.
165 Note: If the label would run into the code in the mid column, a
166 linefeed is always inserted regardless of this setting.
168 This option overrides the <ref id="global-options" name="global option">
169 <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
172 <label id="option--mnemonic-column">
173 <tag><tt>--mnemonic-column n</tt></tag>
175 Specifies the column where a mnemonic or pseudo instrcuction is output.
178 <label id="option--pagelength">
179 <tag><tt>--pagelength n</tt></tag>
181 Sets the length of a listing page in lines. After this number of lines, a
182 new page header is generated. If the <tt><ref id="option--formfeeds"
183 name="--formfeeds"></tt> is also given, a formfeed is inserted before
184 generating the page header.
186 A value of zero for the page length will disable paging of the output.
189 <label id="option--start-addr">
190 <tag><tt>-S addr, --start-addr addr</tt></tag>
192 Specify the start/load address of the binary code that is going to be
193 disassembled. The given address is interpreted as an octal value if
194 preceded with a '0' digit, as a hexadecimal value if preceded
195 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
196 start address is specified, $10000 minus the size of the input file is used.
199 <label id="option--text-column">
200 <tag><tt>--text-column n</tt></tag>
202 Specifies the column where additional text is output. This additional text
203 consists of the bytes encoded in this line in text representation.
206 <tag><tt>-v, --verbose</tt></tag>
208 Increase the disassembler verbosity. Usually only needed for debugging
209 purposes. You may use this option more than one time for even more
213 <tag><tt>-V, --version</tt></tag>
215 Print the version number of the assembler. If you send any suggestions
216 or bugfixes, please include the version number.
222 <sect>Detailed workings<p>
224 <sect1>Supported CPUs<p>
226 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
227 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
228 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
230 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
231 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
232 latter understands the same opcodes as the former, plus 16 additional bit
233 manipulation and bit test-and-branch commands.
235 While there is some code for the 65816 in the sources, it is currently
239 <sect1>Attribute map<p>
241 The disassembler works by creating an attribute map for the whole address
242 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
243 external info file (if given) is read. Disassembly is done in several passes.
244 In all passes with the exception of the last one, information about the
245 disassembled code is gathered and added to the symbol and attribute maps. The
246 last pass generates output using the information from the maps.
250 Some instructions may generate labels in the first pass, while most other
251 instructions do not generate labels, but use them if they are available. Among
252 others, the branch and jump instructions will generate labels for the target
253 of the branch in the first pass. External labels (taken from the info file)
254 have precedence over internally generated ones, They must be valid identifiers
255 as specified for the ca65 assembler. Internal labels (generated by the
256 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
257 address of the label in upper case letters. You should probably avoid using
258 such label names for external labels.
263 The info file is used to pass additional information about the input code to
264 the disassembler. This includes label names, data areas or tables, and global
265 options like input and output file names. See the <ref id="infofile"
266 name="next section"> for more information.
270 <sect>Info File Format<label id="infofile"><p>
272 The info file contains lists of specifications grouped together. Each group
273 directive has an identifying token and an attribute list enclosed in curly
274 braces. Attributes have a name followed by a value. The syntax of the value
275 depends on the type of the attribute. String attributes are places in double
276 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
277 with a leading dollar sign. There are also attributes where the attribute
278 value is a keyword, in this case the keyword is given as is (without quotes or
279 anything). Each attribute is terminated by a semicolon.
282 group-name { attribute1 attribute-value; attribute2 attribute-value; }
288 Comments start with a hash mark (<tt/#/) and extend from the position of
289 the mark to the end of the current line. Hash marks inside of strings will
290 of course <em/not/ start a comment.
293 <sect1>Specifying global options<label id="global-options"><p>
295 Global options may be specified in a group with the name <tt/GLOBAL/. The
296 following attributes are recognized:
300 <tag><tt/ARGUMENTCOLUMN/</tag>
301 This attribute specifies the column in the output, where the argument for
302 an opcode or pseudo instruction starts. The corresponding command line
304 <tt><ref id="option--argument-column" name="--argument-column"></tt>.
307 <tag><tt/COMMENTCOLUMN/</tag>
308 This attribute specifies the column in the output, where the comment starts
309 in a line. It is only used for in-line comments. The corresponding command
311 <tt><ref id="option--comment-column" name="--comment-column"></tt>.
314 <label id="COMMENTS">
315 <tag><tt/COMMENTS/</tag>
316 This attribute may be used instead of the <tt><ref id="option--comments"
317 name="--comments"></tt> option on the command line. It takes a numerical
318 parameter between 0 and 4. Higher values increase the amount of information
319 written to the output file in form of comments.
323 This attribute may be used instead of the <tt><ref id="option--cpu"
324 name="--cpu"></tt> option on the command line. For possible values see
325 there. The value is a string and must be enclosed in quotes.
328 <tag><tt/HEXOFFS/</tag>
329 The attribute is followed by a boolean value. If true, offsets to labels are
330 output in hex, otherwise they're output in decimal notation. The default is
331 false. The attribute may be changed on the command line using the <tt><ref
332 id="option--hexoffs" name="--hexoffs"></tt> option.
335 <tag><tt/INPUTNAME/</tag>
336 The attribute is followed by a string value, which gives the name of the
337 input file to read. If it is present, the disassembler does not accept an
338 input file name on the command line.
341 <tag><tt/INPUTOFFS/</tag>
342 The attribute is followed by a numerical value that gives an offset into
343 the input file which is skipped before reading data. The attribute may be
344 used to skip headers or unwanted code sections in the input file.
347 <tag><tt/INPUTSIZE/</tag>
348 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
349 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
353 <label id="LABELBREAK">
354 <tag><tt/LABELBREAK/</tag>
355 <tt/LABELBREAK/ is followed by a numerical value that specifies the label
356 length that will force a newline. To have all labels on their own lines,
357 you may set this value to zero.
359 See also the <tt><ref id="option--label-break" name="--label-break"></tt>
360 command line option. A <tt/LABELBREAK/ statement in the info file will
361 override any value given on the command line.
364 <tag><tt/MNEMONICCOLUMN/</tag>
365 This attribute specifies the column in the output, where the mnemonic or
366 pseudo instruction is placed. The corresponding command line option is
367 <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
370 <tag><tt/NEWLINEAFTERJMP/</tag>
371 This attribute is followed by a boolean value. When true, a newline is
372 inserted after each <tt/JMP/ instruction. The default is false.
375 <tag><tt/NEWLINEAFTERRTS/</tag>
376 This attribute is followed by a boolean value. When true, a newline is
377 inserted after each <tt/RTS/ instruction. The default is false.
380 <label id="OUTPUTNAME">
381 <tag><tt/OUTPUTNAME/</tag>
382 The attribute is followed by string value, which gives the name of the
383 output file to write. If it is present, specification of an output file on
384 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
387 The default is to use <tt/stdout/ for output, so without this attribute or
388 the corresponding command line option <tt/<ref id="option-o" name="-o">/
389 the output will go to the terminal.
392 <tag><tt/PAGELENGTH/</tag>
393 This attribute may be used instead of the <tt><ref id="option--pagelength"
394 name="--pagelength"></tt> option on the command line. It takes a numerical
395 parameter. Using zero as page length (which is the default) means that no
399 <tag><tt/STARTADDR/</tag>
400 This attribute may be used instead of the <tt><ref id="option--start-addr"
401 name="--start-addr"></tt> option on the command line. It takes a numerical
402 parameter. The default for the start address is $10000 minus the size of
403 the input file (this assumes that the input file is a ROM that contains the
404 reset and irq vectors).
407 <tag><tt/TEXTCOLUMN/</tag>
408 This attribute specifies the column, where the data bytes are output
409 translated into ASCII text. It is only used if
410 <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
411 corresponding command line option is
412 <tt><ref id="option--text-column" name="--text-column"></tt>.
417 <sect1>Specifying Ranges<p>
419 The <tt/RANGE/ directive is used to give information about address ranges. The
420 following attributes are recognized:
424 <tag><tt>COMMENT</tt></tag>
425 This attribute is only allowed if a label is also given. It takes a string
426 as argument. See the description of the <tt><ref id="infofile-label"
427 name="LABEL"></tt> directive for an explanation.
429 <tag><tt>END</tt></tag>
430 This gives the end address of the range. The end address is inclusive, that
431 means, it is part of the range. Of course, it may not be smaller than the
434 <tag><tt>NAME</tt></tag>
435 This is a convenience attribute. It takes a string argument and will cause
436 the disassembler to define a label for the start of the range with the
437 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
438 directive is not needed.
440 <tag><tt>START</tt></tag>
441 This gives the start address of the range.
443 <tag><tt>TYPE</tt></tag>
444 This attribute specifies the type of data within the range. The attribute
445 value is one of the following keywords:
448 <tag><tt>ADDRTABLE</tt></tag>
449 The range consists of data and is disassembled as a table of words
450 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
451 a label is defined for each entry in the table.
453 <tag><tt>BYTETABLE</tt></tag>
454 The range consists of data and is disassembled as a byte table.
456 <tag><tt>CODE</tt></tag>
457 The range consists of code.
459 <tag><tt>DBYTETABLE</tt></tag>
460 The range consists of data and is disassembled as a table of dbytes
461 (double byte values, 16 bit values with the low byte containing the
462 most significant byte of the 16 bit value).
464 <tag><tt>DWORDTABLE</tt></tag>
465 The range consists of data and is disassembled as a table of double
466 words (32 bit values).
468 <tag><tt>RTSTABLE</tt></tag>
469 The range consists of data and is disassembled as a table of words (16 bit
470 values). The values are interpreted as words that are pushed onto the
471 stack and jump to it via <tt/RTS/. This means that they contain
472 <tt/address-1/ of a function, for which a label will get defined by the
475 <tag><tt>SKIP</tt></tag>
476 The range is simply ignored when generating the output file. Please note
477 that this means that reassembling the output file will <em/not/ generate
478 the original file, not only because the missing piece in between, but also
479 because the following code will be located on wrong addresses. Output
480 generated with <tt/SKIP/ ranges will need manual rework.
482 <tag><tt>TEXTTABLE</tt></tag>
483 The range consists of readable text.
485 <tag><tt>WORDTABLE</tt></tag>
486 The range consists of data and is disassembled as a table of words
494 <sect1>Specifying Labels<label id="infofile-label"><p>
496 The <tt/LABEL/ directive is used to give names for labels in the disassembled
497 code. The following attributes are recognized:
501 <tag><tt>ADDR</tt></tag>
502 Followed by a numerical value. Specifies the value of the label.
504 <tag><tt>COMMENT</tt></tag>
505 Attribute argument is a string. The comment will show up in a separate line
506 before the label, if the label is within code or data range, or after the
507 label if it is outside.
512 foo := $0001 ; Comment for label named "foo"
514 ; Comment for label named "bar"
518 <tag><tt>NAME</tt></tag>
519 The attribute is followed by a string value which gives the name of the
520 label. Empty names are allowed, in this case the disassembler will create
521 an unnamed label (see the assembler docs for more information about unnamed
524 <tag><tt>SIZE</tt></tag>
525 This attribute is optional and may be used to specify the size of the data
526 that follows. If a size greater than 1 is specified, the disassembler will
527 create labels in the form <tt/label+offs/ for all bytes within the given
528 range, where <tt/label/ is the label name given with the <tt/NAME/
529 attribute, and <tt/offs/ is the offset within the data.
534 <sect1>Specifying Segments<label id="infofile-segment"><p>
536 The <tt/SEGMENT/ directive is used to specify a segment within the
537 disassembled code. The following attributes are recognized:
541 <tag><tt>START</tt></tag>
542 Followed by a numerical value. Specifies the start address of the segment.
544 <tag><tt>END</tt></tag>
545 Followed by a numerical value. Specifies the end address of the segment. The
546 end address is last the address that is part of the segment.
548 <tag><tt>NAME</tt></tag>
549 The attribute is followed by a string value which gives the name of the
553 All attributes are mandatory. Segments may not overlap. Since there is no
554 explicit "end this segment" pseudo op, the disassembler cannot notify the
555 assembler that one segment has ended. This may lead to errors if you don't
556 define your segments carefully. As a rule of thumb, if you're using segments,
557 your should define segments for all disassembled code.
560 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
562 The <tt/ASMINC/ directive is used to give the names of input files containing
563 symbol assignments in assembler syntax:
570 The usual conventions apply for symbol names. Values may be specified as hex
571 (leading $), binary (leading %) or decimal. The values may optionally
574 NOTE: The include file parser is very simple. Expressions are not allowed, and
575 anything but symbol assignments is flagged as an error (but see the
576 <tt/IGNOREUNKNOWN/ directive below).
578 The following attributes are recognized:
582 <tag><tt>FILE</tt></tag>
583 Followed by a string value. Specifies the name of the file to read.
585 <tag><tt>COMMENTSTART</tt></tag>
586 The optional attribute is followed by a character constant. It specifies the
587 character that starts a comment. The default value is a semicolon. This
588 value is ignored if <tt/IGNOREUNKNOWN/ is true.
590 <tag><tt>IGNOREUNKNOWN</tt></tag>
591 This attribute is optional and is followed by a boolean value. It allows to
592 ignore input lines that don't have a valid syntax. This allows to read in
593 assembler include files that contain more than just symbol assignments.
594 Note: When this attribute is used, the disassembler will ignore any errors
595 in the given include file. This may have undesired side effects.
600 <sect1>An Info File Example<p>
602 The following is a short example for an info file that contains most of the
603 directives explained above:
606 # This is a comment. It extends to the end of the line
608 OUTPUTNAME "kernal.s";
609 INPUTNAME "kernal.bin";
611 PAGELENGTH 0; # No paging
615 # One segment for the whole stuff
616 SEGMENT { START $E000; END $FFFF; NAME kernal; };
618 RANGE { START $E612; END $E631; TYPE Code; };
619 RANGE { START $E632; END $E640; TYPE ByteTable; };
620 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
621 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
622 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
624 # Zero page variables
625 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
626 LABEL { NAME "sal"; ADDR $93; };
627 LABEL { NAME "sah"; ADDR $94; };
628 LABEL { NAME "sas"; ADDR $95; };
631 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
634 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
635 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
636 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
638 # Jump table at end of kernal ROM
639 LABEL { NAME "kscrorg"; ADDR $FFED; };
640 LABEL { NAME "kplot"; ADDR $FFF0; };
641 LABEL { NAME "kiobase"; ADDR $FFF3; };
642 LABEL { NAME "kgbye"; ADDR $FFF6; };
645 LABEL { NAME "hanmi"; ADDR $FFFA; };
646 LABEL { NAME "hares"; ADDR $FFFC; };
647 LABEL { NAME "hairq"; ADDR $FFFE; };
654 <sect>Bugs/Feedback<p>
656 If you have problems using the disassembler, if you find any bugs, or if
657 you're doing something interesting with the assembler, I would be glad to hear
658 from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
659 name="uz@cc65.org">).
665 da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von
666 Bassewitz. For usage of the binaries and/or sources the following
669 This software is provided 'as-is', without any expressed or implied
670 warranty. In no event will the authors be held liable for any damages
671 arising from the use of this software.
673 Permission is granted to anyone to use this software for any purpose,
674 including commercial applications, and to alter it and redistribute it
675 freely, subject to the following restrictions:
678 <item> The origin of this software must not be misrepresented; you must not
679 claim that you wrote the original software. If you use this software
680 in a product, an acknowledgment in the product documentation would be
681 appreciated but is not required.
682 <item> Altered source versions must be plainly marked as such, and must not
683 be misrepresented as being the original software.
684 <item> This notice may not be removed or altered from any source