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 Accept line markers in the info file
57 -S addr Set the start/load address
58 -V Print the disassembler version
61 --argument-column n Specify argument start column
62 --comment-column n Specify comment start column
63 --comments n Set the comment level for the output
64 --cpu type Set cpu type
65 --debug-info Add debug info to object file
66 --formfeeds Add formfeeds to the output
67 --help Help (this text)
68 --hexoffs Use hexadecimal label offsets
69 --info name Specify an info file
70 --label-break n Add newline if label exceeds length n
71 --mnemonic-column n Specify mnemonic start column
72 --pagelength n Set the page length for the listing
73 --start-addr addr Set the start/load address
74 --sync-lines Accept line markers in the info file
75 --text-column n Specify text start column
76 --verbose Increase verbosity
77 --version Print the disassembler version
78 ---------------------------------------------------------------------------
82 <sect1>Command line options in detail<p>
84 Here is a description of all the command line options:
88 <label id="option--argument-column">
89 <tag><tt>--argument-column n</tt></tag>
91 Specifies the column where the argument for a mnemonic or pseudo instruction
95 <label id="option--comment-column">
96 <tag><tt>--comment-column n</tt></tag>
98 Specifies the column where the comment for an instruction starts.
101 <label id="option--comments">
102 <tag><tt>--comments n</tt></tag>
104 Set the comment level for the output. Valid arguments are 0..4. Greater
105 values will increase the level of additional information written to the
106 output file in form of comments.
109 <label id="option--cpu">
110 <tag><tt>--cpu type</tt></tag>
112 Set the CPU type. The option takes a parameter, which may be one of
122 6502x is for the NMOS 6502 with unofficial opcodes. huc6280 is the CPU of
123 the PC engine. 4510 is the CPU of the Commodore C65. Support for the 65816
124 currently is not available.
127 <label id="option--formfeeds">
128 <tag><tt>-F, --formfeeds</tt></tag>
130 Add formfeeds to the generated output. This feature is useful together
131 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
132 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
136 <tag><tt>-g, --debug-info</tt></tag>
138 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
139 assembler will generate debug information when re-assembling the generated
143 <tag><tt>-h, --help</tt></tag>
145 Print the short option summary shown above.
148 <label id="option--hexoffs">
149 <tag><tt>--hexoffs</tt></tag>
151 Output label offsets in hexadecimal instead of decimal notation.
154 <label id="option--info">
155 <tag><tt>-i name, --info name</tt></tag>
157 Specify an info file. The info file contains global options that may
158 override or replace command line options plus informations about the code
159 that has to be disassembled. See the separate section <ref id="infofile"
160 name="Info File Format">.
163 <label id="option-o">
164 <tag><tt>-o name</tt></tag>
166 Specify a name for an output file. The default is to use <tt/stdout/, so
167 without this switch or the corresponding <ref id="global-options"
168 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
169 the output will go to the terminal.
172 <label id="option--label-break">
173 <tag><tt>--label-break n</tt></tag>
175 Adds a newline if the length of a label exceeds the given length.
176 Note: If the label would run into the code in the mid column, a
177 linefeed is always inserted regardless of this setting.
179 This option overrides the <ref id="global-options" name="global option">
180 <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
183 <label id="option--mnemonic-column">
184 <tag><tt>--mnemonic-column n</tt></tag>
186 Specifies the column where a mnemonic or pseudo instrcuction is output.
189 <label id="option--pagelength">
190 <tag><tt>--pagelength n</tt></tag>
192 Sets the length of a listing page in lines. After this number of lines, a
193 new page header is generated. If the <tt><ref id="option--formfeeds"
194 name="--formfeeds"></tt> is also given, a formfeed is inserted before
195 generating the page header.
197 A value of zero for the page length will disable paging of the output.
200 <label id="option--start-addr">
201 <tag><tt>-S addr, --start-addr addr</tt></tag>
203 Specify the start/load address of the binary code that is going to be
204 disassembled. The given address is interpreted as an octal value if
205 preceded with a '0' digit, as a hexadecimal value if preceded
206 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
207 start address is specified, $10000 minus the size of the input file is used.
210 <label id="option--sync-lines">
211 <tag><tt>-s, --sync-lines</tt></tag>
213 Accept line markers in the info file in the following syntax:
215 #line <lineno> ["<filename>"]
216 # <lineno> "<filename>" [<flag>] ...
218 This option is intended for preprocessing info files with "cpp" or "m4".
221 <label id="option--text-column">
222 <tag><tt>--text-column n</tt></tag>
224 Specifies the column where additional text is output. This additional text
225 consists of the bytes encoded in this line in text representation.
228 <tag><tt>-v, --verbose</tt></tag>
230 Increase the disassembler verbosity. Usually only needed for debugging
231 purposes. You may use this option more than one time for even more
235 <tag><tt>-V, --version</tt></tag>
237 Print the version number of the assembler. If you send any suggestions
238 or bugfixes, please include the version number.
244 <sect>Detailed workings<p>
246 <sect1>Supported CPUs<p>
248 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
249 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
250 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
252 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
253 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
254 latter understands the same opcodes as the former, plus 16 additional bit
255 manipulation and bit test-and-branch commands.
257 When disassembling 4510 code, due to handling of 16-bit wide branches, da65
258 can produce output that can not be re-assembled, when one or more of those
259 branches point outside of the disassembled memory. This can happen when text
260 or binary data is processed.
262 While there is some code for the 65816 in the sources, it is currently
266 <sect1>Attribute map<p>
268 The disassembler works by creating an attribute map for the whole address
269 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
270 external info file (if given) is read. Disassembly is done in several passes.
271 In all passes, with the exception of the last one, information about the
272 disassembled code is gathered and added to the symbol and attribute maps. The
273 last pass generates output using the information from the maps.
277 Some instructions may generate labels in the first pass, while most other
278 instructions do not generate labels, but use them if they are available. Among
279 others, the branch and jump instructions will generate labels for the target
280 of the branch in the first pass. External labels (taken from the info file)
281 have precedence over internally generated ones, They must be valid identifiers
282 as specified for the ca65 assembler. Internal labels (generated by the
283 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
284 address of the label in upper case letters. You should probably avoid using
285 such label names for external labels.
290 The info file is used to pass additional information about the input code to
291 the disassembler. This includes label names, data areas or tables, and global
292 options like input and output file names. See the <ref id="infofile"
293 name="next section"> for more information.
297 <sect>Info File Format<label id="infofile"><p>
299 The info file contains lists of specifications grouped together. Each group
300 directive has an identifying token and an attribute list enclosed in curly
301 braces. Attributes have a name followed by a value. The syntax of the value
302 depends on the type of the attribute. String attributes are places in double
303 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
304 with a leading dollar sign. There are also attributes where the attribute
305 value is a keyword; in this case, the keyword is given as-is (without quotes or
306 anything). Each attribute is terminated by a semicolon.
309 group-name { attribute1 attribute-value; attribute2 attribute-value; }
315 Comments start with a hash mark (<tt/#/) or a double slashe (<tt>//</tt>);
316 and, extend from the position of the mark to the end of the current line.
317 Hash marks or double slashes inside of strings will <em/not/ start a comment,
321 <sect1>Specifying global options<label id="global-options"><p>
323 Global options may be specified in a group with the name <tt/GLOBAL/. The
324 following attributes are recognized:
328 <tag><tt/ARGUMENTCOLUMN/</tag>
329 This attribute specifies the column in the output, where the argument for
330 an opcode or pseudo instruction starts. The corresponding command line
332 <tt><ref id="option--argument-column" name="--argument-column"></tt>.
335 <tag><tt/COMMENTCOLUMN/</tag>
336 This attribute specifies the column in the output, where the comment starts
337 in a line. It is only used for in-line comments. The corresponding command
339 <tt><ref id="option--comment-column" name="--comment-column"></tt>.
342 <label id="COMMENTS">
343 <tag><tt/COMMENTS/</tag>
344 This attribute may be used instead of the <tt><ref id="option--comments"
345 name="--comments"></tt> option on the command line. It takes a numerical
346 parameter between 0 and 4. Higher values increase the amount of information
347 written to the output file in form of comments.
351 This attribute may be used instead of the <tt><ref id="option--cpu"
352 name="--cpu"></tt> option on the command line. For possible values see
353 there. The value is a string and must be enclosed in quotes.
356 <tag><tt/HEXOFFS/</tag>
357 The attribute is followed by a boolean value. If true, offsets to labels are
358 output in hex, otherwise they're output in decimal notation. The default is
359 false. The attribute may be changed on the command line using the <tt><ref
360 id="option--hexoffs" name="--hexoffs"></tt> option.
363 <tag><tt/INPUTNAME/</tag>
364 The attribute is followed by a string value, which gives the name of the
365 input file to read. If it is present, the disassembler does not accept an
366 input file name on the command line.
369 <tag><tt/INPUTOFFS/</tag>
370 The attribute is followed by a numerical value that gives an offset into
371 the input file which is skipped before reading data. The attribute may be
372 used to skip headers or unwanted code sections in the input file.
375 <tag><tt/INPUTSIZE/</tag>
376 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
377 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
381 <label id="LABELBREAK">
382 <tag><tt/LABELBREAK/</tag>
383 <tt/LABELBREAK/ is followed by a numerical value that specifies the label
384 length that will force a newline. To have all labels on their own lines,
385 you may set this value to zero.
387 See also the <tt><ref id="option--label-break" name="--label-break"></tt>
388 command line option. A <tt/LABELBREAK/ statement in the info file will
389 override any value given on the command line.
392 <tag><tt/MNEMONICCOLUMN/</tag>
393 This attribute specifies the column in the output, where the mnemonic or
394 pseudo instruction is placed. The corresponding command line option is
395 <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
398 <tag><tt/NEWLINEAFTERJMP/</tag>
399 This attribute is followed by a boolean value. When true, a newline is
400 inserted after each <tt/JMP/ instruction. The default is false.
403 <tag><tt/NEWLINEAFTERRTS/</tag>
404 This attribute is followed by a boolean value. When true, a newline is
405 inserted after each <tt/RTS/ instruction. The default is false.
408 <label id="OUTPUTNAME">
409 <tag><tt/OUTPUTNAME/</tag>
410 The attribute is followed by string value, which gives the name of the
411 output file to write. If it is present, specification of an output file on
412 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
415 The default is to use <tt/stdout/ for output, so without this attribute or
416 the corresponding command line option <tt/<ref id="option-o" name="-o">/
417 the output will go to the terminal.
420 <tag><tt/PAGELENGTH/</tag>
421 This attribute may be used instead of the <tt><ref id="option--pagelength"
422 name="--pagelength"></tt> option on the command line. It takes a numerical
423 parameter. Using zero as page length (which is the default) means that no
427 <tag><tt/STARTADDR/</tag>
428 This attribute may be used instead of the <tt><ref id="option--start-addr"
429 name="--start-addr"></tt> option on the command line. It takes a numerical
430 parameter. The default for the start address is $10000 minus the size of
431 the input file (this assumes that the input file is a ROM that contains the
432 reset and irq vectors).
435 <tag><tt/TEXTCOLUMN/</tag>
436 This attribute specifies the column, where the data bytes are output
437 translated into ASCII text. It is only used if
438 <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
439 corresponding command line option is
440 <tt><ref id="option--text-column" name="--text-column"></tt>.
445 <sect1>Specifying Ranges<p>
447 The <tt/RANGE/ directive is used to give information about address ranges. The
448 following attributes are recognized:
452 <tag><tt>COMMENT</tt></tag>
453 This attribute is only allowed if a label is also given. It takes a string
454 as argument. See the description of the <tt><ref id="infofile-label"
455 name="LABEL"></tt> directive for an explanation.
457 <tag><tt>END</tt></tag>
458 This gives the end address of the range. The end address is inclusive, that
459 means, it is part of the range. Of course, it may not be smaller than the
462 <tag><tt>NAME</tt></tag>
463 This is a convenience attribute. It takes a string argument and will cause
464 the disassembler to define a label for the start of the range with the
465 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
466 directive is not needed.
468 <tag><tt>START</tt></tag>
469 This gives the start address of the range.
471 <tag><tt>TYPE</tt></tag>
472 This attribute specifies the type of data within the range. The attribute
473 value is one of the following keywords:
476 <tag><tt>ADDRTABLE</tt></tag>
477 The range consists of data and is disassembled as a table of words
478 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
479 a label is defined for each entry in the table.
481 <tag><tt>BYTETABLE</tt></tag>
482 The range consists of data and is disassembled as a byte table.
484 <tag><tt>CODE</tt></tag>
485 The range consists of code.
487 <tag><tt>DBYTETABLE</tt></tag>
488 The range consists of data and is disassembled as a table of dbytes
489 (double byte values, 16 bit values with the low byte containing the
490 most significant byte of the 16 bit value).
492 <tag><tt>DWORDTABLE</tt></tag>
493 The range consists of data and is disassembled as a table of double
494 words (32 bit values).
496 <tag><tt>RTSTABLE</tt></tag>
497 The range consists of data and is disassembled as a table of words (16 bit
498 values). The values are interpreted as words that are pushed onto the
499 stack and jump to it via <tt/RTS/. This means that they contain
500 <tt/address-1/ of a function, for which a label will get defined by the
503 <tag><tt>SKIP</tt></tag>
504 The range is simply ignored when generating the output file. Please note
505 that this means that reassembling the output file will <em/not/ generate
506 the original file, not only because the missing piece in between, but also
507 because the following code will be located on wrong addresses. Output
508 generated with <tt/SKIP/ ranges will need manual rework.
510 <tag><tt>TEXTTABLE</tt></tag>
511 The range consists of readable text.
513 <tag><tt>WORDTABLE</tt></tag>
514 The range consists of data and is disassembled as a table of words
522 <sect1>Specifying Labels<label id="infofile-label"><p>
524 The <tt/LABEL/ directive is used to give names for labels in the disassembled
525 code. The following attributes are recognized:
529 <tag><tt>ADDR</tt></tag>
530 Followed by a numerical value. Specifies the value of the label.
532 <tag><tt>COMMENT</tt></tag>
533 Attribute argument is a string. The comment will show up in a separate line
534 before the label, if the label is within code or data range, or after the
535 label if it is outside.
540 foo := $0001 ; Comment for label named "foo"
542 ; Comment for label named "bar"
546 <tag><tt>NAME</tt></tag>
547 The attribute is followed by a string value which gives the name of the
548 label. Empty names are allowed, in this case the disassembler will create
549 an unnamed label (see the assembler docs for more information about unnamed
552 <tag><tt>SIZE</tt></tag>
553 This attribute is optional and may be used to specify the size of the data
554 that follows. If a size greater than 1 is specified, the disassembler will
555 create labels in the form <tt/label+offs/ for all bytes within the given
556 range, where <tt/label/ is the label name given with the <tt/NAME/
557 attribute, and <tt/offs/ is the offset within the data.
562 <sect1>Specifying Segments<label id="infofile-segment"><p>
564 The <tt/SEGMENT/ directive is used to specify a segment within the
565 disassembled code. The following attributes are recognized:
569 <tag><tt>START</tt></tag>
570 Followed by a numerical value. Specifies the start address of the segment.
572 <tag><tt>END</tt></tag>
573 Followed by a numerical value. Specifies the end address of the segment. The
574 end address is the last address that is a part of the segment.
576 <tag><tt>NAME</tt></tag>
577 The attribute is followed by a string value which gives the name of the
581 All attributes are mandatory. Segments must not overlap. The disassembler will
582 change back to the (default) <tt/.code/ segment after the end of each defined
583 segment. That might not be what you want. As a rule of thumb, if you're using
584 segments, you should define segments for all disassembled code.
587 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
589 The <tt/ASMINC/ directive is used to give the names of input files containing
590 symbol assignments in assembler syntax:
597 The usual conventions apply for symbol names. Values may be specified as hex
598 (leading $), binary (leading %) or decimal. The values may optionally
601 NOTE: The include file parser is very simple. Expressions are not allowed, and
602 anything but symbol assignments is flagged as an error (but see the
603 <tt/IGNOREUNKNOWN/ directive below).
605 The following attributes are recognized:
609 <tag><tt>FILE</tt></tag>
610 Followed by a string value. Specifies the name of the file to read.
612 <tag><tt>COMMENTSTART</tt></tag>
613 The optional attribute is followed by a character constant. It specifies the
614 character that starts a comment. The default value is a semicolon. This
615 value is ignored if <tt/IGNOREUNKNOWN/ is true.
617 <tag><tt>IGNOREUNKNOWN</tt></tag>
618 This attribute is optional and is followed by a boolean value. It allows to
619 ignore input lines that don't have a valid syntax. This allows to read in
620 assembler include files that contain more than just symbol assignments.
621 Note: When this attribute is used, the disassembler will ignore any errors
622 in the given include file. This may have undesired side effects.
627 <sect1>An Info File Example<p>
629 The following is a short example for an info file that contains most of the
630 directives explained above:
633 # This is a comment. It extends to the end of the line
635 OUTPUTNAME "kernal.s";
636 INPUTNAME "kernal.bin";
638 PAGELENGTH 0; # No paging
642 # One segment for the whole stuff
643 SEGMENT { START $E000; END $FFFF; NAME "kernal"; };
645 RANGE { START $E612; END $E631; TYPE Code; };
646 RANGE { START $E632; END $E640; TYPE ByteTable; };
647 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
648 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
649 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
651 # Zero-page variables
652 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
653 LABEL { NAME "sal"; ADDR $93; };
654 LABEL { NAME "sah"; ADDR $94; };
655 LABEL { NAME "sas"; ADDR $95; };
658 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
661 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
662 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
663 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
665 # Jump table at end of kernal ROM
666 LABEL { NAME "kscrorg"; ADDR $FFED; };
667 LABEL { NAME "kplot"; ADDR $FFF0; };
668 LABEL { NAME "kiobase"; ADDR $FFF3; };
669 LABEL { NAME "kgbye"; ADDR $FFF6; };
672 LABEL { NAME "hanmi"; ADDR $FFFA; };
673 LABEL { NAME "hares"; ADDR $FFFC; };
674 LABEL { NAME "hairq"; ADDR $FFFE; };
681 da65 (and all cc65 binutils) is (C) Copyright 1998-2011, Ullrich von
682 Bassewitz. For usage of the binaries and/or sources, the following
685 This software is provided 'as-is', without any expressed or implied
686 warranty. In no event will the authors be held liable for any damages
687 arising from the use of this software.
689 Permission is granted to anyone to use this software for any purpose,
690 including commercial applications, and to alter it and redistribute it
691 freely, subject to the following restrictions:
694 <item> The origin of this software must not be misrepresented; you must not
695 claim that you wrote the original software. If you use this software
696 in a product, an acknowledgment in the product documentation would be
697 appreciated but is not required.
698 <item> Altered source versions must be plainly marked as such, and must not
699 be misrepresented as being the original software.
700 <item> This notice may not be removed or altered from any source