1 <!doctype linuxdoc system>
4 <title>da65 Users Guide
6 <url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
7 <url url="mailto:greg.king5@verizon.net" name="Greg King">
11 da65 is a 6502/65C02 disassembler that is able to read user-supplied
12 information about its input data, for better results. The output is ready for
13 feeding into ca65, the macro assembler supplied with the cc65 C compiler.
16 <!-- Table of contents -->
19 <!-- Begin the document -->
23 da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
24 the cc65 C compiler and generates output that is suitable for the ca65
27 Besides generating output for ca65, one of the design goals was that the user
28 is able to feed additional information about the code into the disassembler,
29 for improved results. This information may include the location and size of
30 tables, and their format.
32 One nice advantage of this concept is that disassembly of copyrighted binaries
33 may be handled without problems: One can just pass the information file for
34 disassembling the binary, so everyone with a legal copy of the binary can
35 generate a nicely formatted disassembly with readable labels and other
42 <sect1>Command line option overview<p>
44 The assembler accepts the following options:
47 ---------------------------------------------------------------------------
48 Usage: da65 [options] [inputfile]
50 -g Add debug info to object file
52 -i name Specify an info file
53 -o name Name the output file
55 -F Add formfeeds to the output
56 -S addr Set the start/load address
57 -V Print the disassembler version
60 --argument-column n Specify argument start column
61 --comment-column n Specify comment start column
62 --comments n Set the comment level for the output
63 --cpu type Set cpu type
64 --debug-info Add debug info to object file
65 --formfeeds Add formfeeds to the output
66 --help Help (this text)
67 --hexoffs Use hexadecimal label offsets
68 --info name Specify an info file
69 --label-break n Add newline if label exceeds length n
70 --mnemonic-column n Specify mnemonic start column
71 --pagelength n Set the page length for the listing
72 --start-addr addr Set the start/load address
73 --text-column n Specify text start column
74 --verbose Increase verbosity
75 --version Print the disassembler version
76 ---------------------------------------------------------------------------
80 <sect1>Command line options in detail<p>
82 Here is a description of all the command line options:
86 <label id="option--argument-column">
87 <tag><tt>--argument-column n</tt></tag>
89 Specifies the column where the argument for a mnemonic or pseudo instruction
93 <label id="option--comment-column">
94 <tag><tt>--comment-column n</tt></tag>
96 Specifies the column where the comment for an instruction starts.
99 <label id="option--comments">
100 <tag><tt>--comments n</tt></tag>
102 Set the comment level for the output. Valid arguments are 0..4. Greater
103 values will increase the level of additional information written to the
104 output file in form of comments.
107 <label id="option--cpu">
108 <tag><tt>--cpu type</tt></tag>
110 Set the CPU type. The option takes a parameter, which may be one of
120 6502x is for the NMOS 6502 with unofficial opcodes. huc6280 is the CPU of
121 the PC engine. 4510 is the CPU of the Commodore C65. Support for the 65816
122 currently is not available.
125 <label id="option--formfeeds">
126 <tag><tt>-F, --formfeeds</tt></tag>
128 Add formfeeds to the generated output. This feature is useful together
129 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
130 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
134 <tag><tt>-g, --debug-info</tt></tag>
136 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
137 assembler will generate debug information when re-assembling the generated
141 <tag><tt>-h, --help</tt></tag>
143 Print the short option summary shown above.
146 <label id="option--hexoffs">
147 <tag><tt>--hexoffs</tt></tag>
149 Output label offsets in hexadecimal instead of decimal notation.
152 <label id="option--info">
153 <tag><tt>-i name, --info name</tt></tag>
155 Specify an info file. The info file contains global options that may
156 override or replace command line options plus informations about the code
157 that has to be disassembled. See the separate section <ref id="infofile"
158 name="Info File Format">.
161 <label id="option-o">
162 <tag><tt>-o name</tt></tag>
164 Specify a name for an output file. The default is to use <tt/stdout/, so
165 without this switch or the corresponding <ref id="global-options"
166 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
167 the output will go to the terminal.
170 <label id="option--label-break">
171 <tag><tt>--label-break n</tt></tag>
173 Adds a newline if the length of a label exceeds the given length.
174 Note: If the label would run into the code in the mid column, a
175 linefeed is always inserted regardless of this setting.
177 This option overrides the <ref id="global-options" name="global option">
178 <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
181 <label id="option--mnemonic-column">
182 <tag><tt>--mnemonic-column n</tt></tag>
184 Specifies the column where a mnemonic or pseudo instrcuction is output.
187 <label id="option--pagelength">
188 <tag><tt>--pagelength n</tt></tag>
190 Sets the length of a listing page in lines. After this number of lines, a
191 new page header is generated. If the <tt><ref id="option--formfeeds"
192 name="--formfeeds"></tt> is also given, a formfeed is inserted before
193 generating the page header.
195 A value of zero for the page length will disable paging of the output.
198 <label id="option--start-addr">
199 <tag><tt>-S addr, --start-addr addr</tt></tag>
201 Specify the start/load address of the binary code that is going to be
202 disassembled. The given address is interpreted as an octal value if
203 preceded with a '0' digit, as a hexadecimal value if preceded
204 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
205 start address is specified, $10000 minus the size of the input file is used.
208 <label id="option--text-column">
209 <tag><tt>--text-column n</tt></tag>
211 Specifies the column where additional text is output. This additional text
212 consists of the bytes encoded in this line in text representation.
215 <tag><tt>-v, --verbose</tt></tag>
217 Increase the disassembler verbosity. Usually only needed for debugging
218 purposes. You may use this option more than one time for even more
222 <tag><tt>-V, --version</tt></tag>
224 Print the version number of the assembler. If you send any suggestions
225 or bugfixes, please include the version number.
231 <sect>Detailed workings<p>
233 <sect1>Supported CPUs<p>
235 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
236 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
237 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
239 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
240 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
241 latter understands the same opcodes as the former, plus 16 additional bit
242 manipulation and bit test-and-branch commands.
244 When disassembling 4510 code, due to handling of 16-bit wide branches, da65
245 can produce output that can not be re-assembled, when one or more of those
246 branches point outside of the disassembled memory. This can happen when text
247 or binary data is processed.
249 While there is some code for the 65816 in the sources, it is currently
253 <sect1>Attribute map<p>
255 The disassembler works by creating an attribute map for the whole address
256 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
257 external info file (if given) is read. Disassembly is done in several passes.
258 In all passes, with the exception of the last one, information about the
259 disassembled code is gathered and added to the symbol and attribute maps. The
260 last pass generates output using the information from the maps.
264 Some instructions may generate labels in the first pass, while most other
265 instructions do not generate labels, but use them if they are available. Among
266 others, the branch and jump instructions will generate labels for the target
267 of the branch in the first pass. External labels (taken from the info file)
268 have precedence over internally generated ones, They must be valid identifiers
269 as specified for the ca65 assembler. Internal labels (generated by the
270 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
271 address of the label in upper case letters. You should probably avoid using
272 such label names for external labels.
277 The info file is used to pass additional information about the input code to
278 the disassembler. This includes label names, data areas or tables, and global
279 options like input and output file names. See the <ref id="infofile"
280 name="next section"> for more information.
284 <sect>Info File Format<label id="infofile"><p>
286 The info file contains lists of specifications grouped together. Each group
287 directive has an identifying token and an attribute list enclosed in curly
288 braces. Attributes have a name followed by a value. The syntax of the value
289 depends on the type of the attribute. String attributes are places in double
290 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
291 with a leading dollar sign. There are also attributes where the attribute
292 value is a keyword; in this case, the keyword is given as-is (without quotes or
293 anything). Each attribute is terminated by a semicolon.
296 group-name { attribute1 attribute-value; attribute2 attribute-value; }
302 Comments start with a hash mark (<tt/#/); and, extend from the position of
303 the mark to the end of the current line. Hash marks inside of strings will
304 <em/not/ start a comment, of course.
307 <sect1>Specifying global options<label id="global-options"><p>
309 Global options may be specified in a group with the name <tt/GLOBAL/. The
310 following attributes are recognized:
314 <tag><tt/ARGUMENTCOLUMN/</tag>
315 This attribute specifies the column in the output, where the argument for
316 an opcode or pseudo instruction starts. The corresponding command line
318 <tt><ref id="option--argument-column" name="--argument-column"></tt>.
321 <tag><tt/COMMENTCOLUMN/</tag>
322 This attribute specifies the column in the output, where the comment starts
323 in a line. It is only used for in-line comments. The corresponding command
325 <tt><ref id="option--comment-column" name="--comment-column"></tt>.
328 <label id="COMMENTS">
329 <tag><tt/COMMENTS/</tag>
330 This attribute may be used instead of the <tt><ref id="option--comments"
331 name="--comments"></tt> option on the command line. It takes a numerical
332 parameter between 0 and 4. Higher values increase the amount of information
333 written to the output file in form of comments.
337 This attribute may be used instead of the <tt><ref id="option--cpu"
338 name="--cpu"></tt> option on the command line. For possible values see
339 there. The value is a string and must be enclosed in quotes.
342 <tag><tt/HEXOFFS/</tag>
343 The attribute is followed by a boolean value. If true, offsets to labels are
344 output in hex, otherwise they're output in decimal notation. The default is
345 false. The attribute may be changed on the command line using the <tt><ref
346 id="option--hexoffs" name="--hexoffs"></tt> option.
349 <tag><tt/INPUTNAME/</tag>
350 The attribute is followed by a string value, which gives the name of the
351 input file to read. If it is present, the disassembler does not accept an
352 input file name on the command line.
355 <tag><tt/INPUTOFFS/</tag>
356 The attribute is followed by a numerical value that gives an offset into
357 the input file which is skipped before reading data. The attribute may be
358 used to skip headers or unwanted code sections in the input file.
361 <tag><tt/INPUTSIZE/</tag>
362 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
363 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
367 <label id="LABELBREAK">
368 <tag><tt/LABELBREAK/</tag>
369 <tt/LABELBREAK/ is followed by a numerical value that specifies the label
370 length that will force a newline. To have all labels on their own lines,
371 you may set this value to zero.
373 See also the <tt><ref id="option--label-break" name="--label-break"></tt>
374 command line option. A <tt/LABELBREAK/ statement in the info file will
375 override any value given on the command line.
378 <tag><tt/MNEMONICCOLUMN/</tag>
379 This attribute specifies the column in the output, where the mnemonic or
380 pseudo instruction is placed. The corresponding command line option is
381 <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
384 <tag><tt/NEWLINEAFTERJMP/</tag>
385 This attribute is followed by a boolean value. When true, a newline is
386 inserted after each <tt/JMP/ instruction. The default is false.
389 <tag><tt/NEWLINEAFTERRTS/</tag>
390 This attribute is followed by a boolean value. When true, a newline is
391 inserted after each <tt/RTS/ instruction. The default is false.
394 <label id="OUTPUTNAME">
395 <tag><tt/OUTPUTNAME/</tag>
396 The attribute is followed by string value, which gives the name of the
397 output file to write. If it is present, specification of an output file on
398 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
401 The default is to use <tt/stdout/ for output, so without this attribute or
402 the corresponding command line option <tt/<ref id="option-o" name="-o">/
403 the output will go to the terminal.
406 <tag><tt/PAGELENGTH/</tag>
407 This attribute may be used instead of the <tt><ref id="option--pagelength"
408 name="--pagelength"></tt> option on the command line. It takes a numerical
409 parameter. Using zero as page length (which is the default) means that no
413 <tag><tt/STARTADDR/</tag>
414 This attribute may be used instead of the <tt><ref id="option--start-addr"
415 name="--start-addr"></tt> option on the command line. It takes a numerical
416 parameter. The default for the start address is $10000 minus the size of
417 the input file (this assumes that the input file is a ROM that contains the
418 reset and irq vectors).
421 <tag><tt/TEXTCOLUMN/</tag>
422 This attribute specifies the column, where the data bytes are output
423 translated into ASCII text. It is only used if
424 <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
425 corresponding command line option is
426 <tt><ref id="option--text-column" name="--text-column"></tt>.
431 <sect1>Specifying Ranges<p>
433 The <tt/RANGE/ directive is used to give information about address ranges. The
434 following attributes are recognized:
438 <tag><tt>COMMENT</tt></tag>
439 This attribute is only allowed if a label is also given. It takes a string
440 as argument. See the description of the <tt><ref id="infofile-label"
441 name="LABEL"></tt> directive for an explanation.
443 <tag><tt>END</tt></tag>
444 This gives the end address of the range. The end address is inclusive, that
445 means, it is part of the range. Of course, it may not be smaller than the
448 <tag><tt>NAME</tt></tag>
449 This is a convenience attribute. It takes a string argument and will cause
450 the disassembler to define a label for the start of the range with the
451 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
452 directive is not needed.
454 <tag><tt>START</tt></tag>
455 This gives the start address of the range.
457 <tag><tt>TYPE</tt></tag>
458 This attribute specifies the type of data within the range. The attribute
459 value is one of the following keywords:
462 <tag><tt>ADDRTABLE</tt></tag>
463 The range consists of data and is disassembled as a table of words
464 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
465 a label is defined for each entry in the table.
467 <tag><tt>BYTETABLE</tt></tag>
468 The range consists of data and is disassembled as a byte table.
470 <tag><tt>CODE</tt></tag>
471 The range consists of code.
473 <tag><tt>DBYTETABLE</tt></tag>
474 The range consists of data and is disassembled as a table of dbytes
475 (double byte values, 16 bit values with the low byte containing the
476 most significant byte of the 16 bit value).
478 <tag><tt>DWORDTABLE</tt></tag>
479 The range consists of data and is disassembled as a table of double
480 words (32 bit values).
482 <tag><tt>RTSTABLE</tt></tag>
483 The range consists of data and is disassembled as a table of words (16 bit
484 values). The values are interpreted as words that are pushed onto the
485 stack and jump to it via <tt/RTS/. This means that they contain
486 <tt/address-1/ of a function, for which a label will get defined by the
489 <tag><tt>SKIP</tt></tag>
490 The range is simply ignored when generating the output file. Please note
491 that this means that reassembling the output file will <em/not/ generate
492 the original file, not only because the missing piece in between, but also
493 because the following code will be located on wrong addresses. Output
494 generated with <tt/SKIP/ ranges will need manual rework.
496 <tag><tt>TEXTTABLE</tt></tag>
497 The range consists of readable text.
499 <tag><tt>WORDTABLE</tt></tag>
500 The range consists of data and is disassembled as a table of words
508 <sect1>Specifying Labels<label id="infofile-label"><p>
510 The <tt/LABEL/ directive is used to give names for labels in the disassembled
511 code. The following attributes are recognized:
515 <tag><tt>ADDR</tt></tag>
516 Followed by a numerical value. Specifies the value of the label.
518 <tag><tt>COMMENT</tt></tag>
519 Attribute argument is a string. The comment will show up in a separate line
520 before the label, if the label is within code or data range, or after the
521 label if it is outside.
526 foo := $0001 ; Comment for label named "foo"
528 ; Comment for label named "bar"
532 <tag><tt>NAME</tt></tag>
533 The attribute is followed by a string value which gives the name of the
534 label. Empty names are allowed, in this case the disassembler will create
535 an unnamed label (see the assembler docs for more information about unnamed
538 <tag><tt>SIZE</tt></tag>
539 This attribute is optional and may be used to specify the size of the data
540 that follows. If a size greater than 1 is specified, the disassembler will
541 create labels in the form <tt/label+offs/ for all bytes within the given
542 range, where <tt/label/ is the label name given with the <tt/NAME/
543 attribute, and <tt/offs/ is the offset within the data.
548 <sect1>Specifying Segments<label id="infofile-segment"><p>
550 The <tt/SEGMENT/ directive is used to specify a segment within the
551 disassembled code. The following attributes are recognized:
555 <tag><tt>START</tt></tag>
556 Followed by a numerical value. Specifies the start address of the segment.
558 <tag><tt>END</tt></tag>
559 Followed by a numerical value. Specifies the end address of the segment. The
560 end address is the last address that is a part of the segment.
562 <tag><tt>NAME</tt></tag>
563 The attribute is followed by a string value which gives the name of the
567 All attributes are mandatory. Segments must not overlap. The disassembler will
568 change back to the (default) <tt/.code/ segment after the end of each defined
569 segment. That might not be what you want. As a rule of thumb, if you're using
570 segments, you should define segments for all disassembled code.
573 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
575 The <tt/ASMINC/ directive is used to give the names of input files containing
576 symbol assignments in assembler syntax:
583 The usual conventions apply for symbol names. Values may be specified as hex
584 (leading $), binary (leading %) or decimal. The values may optionally
587 NOTE: The include file parser is very simple. Expressions are not allowed, and
588 anything but symbol assignments is flagged as an error (but see the
589 <tt/IGNOREUNKNOWN/ directive below).
591 The following attributes are recognized:
595 <tag><tt>FILE</tt></tag>
596 Followed by a string value. Specifies the name of the file to read.
598 <tag><tt>COMMENTSTART</tt></tag>
599 The optional attribute is followed by a character constant. It specifies the
600 character that starts a comment. The default value is a semicolon. This
601 value is ignored if <tt/IGNOREUNKNOWN/ is true.
603 <tag><tt>IGNOREUNKNOWN</tt></tag>
604 This attribute is optional and is followed by a boolean value. It allows to
605 ignore input lines that don't have a valid syntax. This allows to read in
606 assembler include files that contain more than just symbol assignments.
607 Note: When this attribute is used, the disassembler will ignore any errors
608 in the given include file. This may have undesired side effects.
613 <sect1>An Info File Example<p>
615 The following is a short example for an info file that contains most of the
616 directives explained above:
619 # This is a comment. It extends to the end of the line
621 OUTPUTNAME "kernal.s";
622 INPUTNAME "kernal.bin";
624 PAGELENGTH 0; # No paging
628 # One segment for the whole stuff
629 SEGMENT { START $E000; END $FFFF; NAME "kernal"; };
631 RANGE { START $E612; END $E631; TYPE Code; };
632 RANGE { START $E632; END $E640; TYPE ByteTable; };
633 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
634 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
635 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
637 # Zero-page variables
638 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
639 LABEL { NAME "sal"; ADDR $93; };
640 LABEL { NAME "sah"; ADDR $94; };
641 LABEL { NAME "sas"; ADDR $95; };
644 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
647 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
648 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
649 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
651 # Jump table at end of kernal ROM
652 LABEL { NAME "kscrorg"; ADDR $FFED; };
653 LABEL { NAME "kplot"; ADDR $FFF0; };
654 LABEL { NAME "kiobase"; ADDR $FFF3; };
655 LABEL { NAME "kgbye"; ADDR $FFF6; };
658 LABEL { NAME "hanmi"; ADDR $FFFA; };
659 LABEL { NAME "hares"; ADDR $FFFC; };
660 LABEL { NAME "hairq"; ADDR $FFFE; };
667 da65 (and all cc65 binutils) is (C) Copyright 1998-2011, Ullrich von
668 Bassewitz. For usage of the binaries and/or sources, the following
671 This software is provided 'as-is', without any expressed or implied
672 warranty. In no event will the authors be held liable for any damages
673 arising from the use of this software.
675 Permission is granted to anyone to use this software for any purpose,
676 including commercial applications, and to alter it and redistribute it
677 freely, subject to the following restrictions:
680 <item> The origin of this software must not be misrepresented; you must not
681 claim that you wrote the original software. If you use this software
682 in a product, an acknowledgment in the product documentation would be
683 appreciated but is not required.
684 <item> Altered source versions must be plainly marked as such, and must not
685 be misrepresented as being the original software.
686 <item> This notice may not be removed or altered from any source