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">
10 da65 is a 6502/65C02 disassembler that is able to read user-supplied
11 information about its input data, for better results. The output is ready for
12 feeding into ca65, the macro assembler supplied with the cc65 C compiler.
15 <!-- Table of contents -->
18 <!-- Begin the document -->
22 da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
23 the cc65 C compiler and generates output that is suitable for the ca65
26 Besides generating output for ca65, one of the design goals was that the user
27 is able to feed additional information about the code into the disassembler,
28 for improved results. This information may include the location and size of
29 tables, and their format.
31 One nice advantage of this concept is that disassembly of copyrighted binaries
32 may be handled without problems: One can just pass the information file for
33 disassembling the binary, so everyone with a legal copy of the binary can
34 generate a nicely formatted disassembly with readable labels and other
41 <sect1>Command line option overview<p>
43 The assembler accepts the following options:
46 ---------------------------------------------------------------------------
47 Usage: da65 [options] [inputfile]
49 -g Add debug info to object file
51 -i name Specify an info file
52 -o name Name the output file
54 -F Add formfeeds to the output
55 -s Accept line markers in the info file
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 --sync-lines Accept line markers in the info file
74 --text-column n Specify text start column
75 --verbose Increase verbosity
76 --version Print the disassembler version
77 ---------------------------------------------------------------------------
81 <sect1>Command line options in detail<p>
83 Here is a description of all the command line options:
87 <label id="option--argument-column">
88 <tag><tt>--argument-column n</tt></tag>
90 Specifies the column where the argument for a mnemonic or pseudo instruction
94 <label id="option--comment-column">
95 <tag><tt>--comment-column n</tt></tag>
97 Specifies the column where the comment for an instruction starts.
100 <label id="option--comments">
101 <tag><tt>--comments n</tt></tag>
103 Set the comment level for the output. Valid arguments are 0..4. Greater
104 values will increase the level of additional information written to the
105 output file in form of comments.
108 <label id="option--cpu">
109 <tag><tt>--cpu type</tt></tag>
111 Set the CPU type. The option takes a parameter, which may be one of
121 6502x is for the NMOS 6502 with unofficial opcodes. huc6280 is the CPU of
122 the PC engine. 4510 is the CPU of the Commodore C65. Support for the 65816
123 currently is not available.
126 <label id="option--formfeeds">
127 <tag><tt>-F, --formfeeds</tt></tag>
129 Add formfeeds to the generated output. This feature is useful together
130 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
131 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
135 <tag><tt>-g, --debug-info</tt></tag>
137 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
138 assembler will generate debug information when re-assembling the generated
142 <tag><tt>-h, --help</tt></tag>
144 Print the short option summary shown above.
147 <label id="option--hexoffs">
148 <tag><tt>--hexoffs</tt></tag>
150 Output label offsets in hexadecimal instead of decimal notation.
153 <label id="option--info">
154 <tag><tt>-i name, --info name</tt></tag>
156 Specify an info file. The info file contains global options that may
157 override or replace command line options plus informations about the code
158 that has to be disassembled. See the separate section <ref id="infofile"
159 name="Info File Format">.
162 <label id="option-o">
163 <tag><tt>-o name</tt></tag>
165 Specify a name for an output file. The default is to use <tt/stdout/, so
166 without this switch or the corresponding <ref id="global-options"
167 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
168 the output will go to the terminal.
171 <label id="option--label-break">
172 <tag><tt>--label-break n</tt></tag>
174 Adds a newline if the length of a label exceeds the given length.
175 Note: If the label would run into the code in the mid column, a
176 linefeed is always inserted regardless of this setting.
178 This option overrides the <ref id="global-options" name="global option">
179 <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
182 <label id="option--mnemonic-column">
183 <tag><tt>--mnemonic-column n</tt></tag>
185 Specifies the column where a mnemonic or pseudo instrcuction is output.
188 <label id="option--pagelength">
189 <tag><tt>--pagelength n</tt></tag>
191 Sets the length of a listing page in lines. After this number of lines, a
192 new page header is generated. If the <tt><ref id="option--formfeeds"
193 name="--formfeeds"></tt> is also given, a formfeed is inserted before
194 generating the page header.
196 A value of zero for the page length will disable paging of the output.
199 <label id="option--start-addr">
200 <tag><tt>-S addr, --start-addr addr</tt></tag>
202 Specify the start/load address of the binary code that is going to be
203 disassembled. The given address is interpreted as an octal value if
204 preceded with a '0' digit, as a hexadecimal value if preceded
205 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
206 start address is specified, $10000 minus the size of the input file is used.
209 <label id="option--sync-lines">
210 <tag><tt>-s, --sync-lines</tt></tag>
212 Accept line markers in the info file in the following syntax:
214 #line <lineno> ["<filename>"]
215 # <lineno> "<filename>" [<flag>] ...
217 This option is intended for preprocessing info files with "cpp" or "m4".
220 <label id="option--text-column">
221 <tag><tt>--text-column n</tt></tag>
223 Specifies the column where additional text is output. This additional text
224 consists of the bytes encoded in this line in text representation.
227 <tag><tt>-v, --verbose</tt></tag>
229 Increase the disassembler verbosity. Usually only needed for debugging
230 purposes. You may use this option more than one time for even more
234 <tag><tt>-V, --version</tt></tag>
236 Print the version number of the assembler. If you send any suggestions
237 or bugfixes, please include the version number.
243 <sect>Detailed workings<p>
245 <sect1>Supported CPUs<p>
247 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
248 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
249 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
251 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
252 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
253 latter understands the same opcodes as the former, plus 16 additional bit
254 manipulation and bit test-and-branch commands.
256 When disassembling 4510 code, due to handling of 16-bit wide branches, da65
257 can produce output that can not be re-assembled, when one or more of those
258 branches point outside of the disassembled memory. This can happen when text
259 or binary data is processed.
261 While there is some code for the 65816 in the sources, it is currently
265 <sect1>Attribute map<p>
267 The disassembler works by creating an attribute map for the whole address
268 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
269 external info file (if given) is read. Disassembly is done in several passes.
270 In all passes, with the exception of the last one, information about the
271 disassembled code is gathered and added to the symbol and attribute maps. The
272 last pass generates output using the information from the maps.
276 Some instructions may generate labels in the first pass, while most other
277 instructions do not generate labels, but use them if they are available. Among
278 others, the branch and jump instructions will generate labels for the target
279 of the branch in the first pass. External labels (taken from the info file)
280 have precedence over internally generated ones, They must be valid identifiers
281 as specified for the ca65 assembler. Internal labels (generated by the
282 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
283 address of the label in upper case letters. You should probably avoid using
284 such label names for external labels.
289 The info file is used to pass additional information about the input code to
290 the disassembler. This includes label names, data areas or tables, and global
291 options like input and output file names. See the <ref id="infofile"
292 name="next section"> for more information.
296 <sect>Info File Format<label id="infofile"><p>
298 The info file contains lists of specifications grouped together. Each group
299 directive has an identifying token and an attribute list enclosed in curly
300 braces. Attributes have a name followed by a value. The syntax of the value
301 depends on the type of the attribute. String attributes are places in double
302 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
303 with a leading dollar sign. There are also attributes where the attribute
304 value is a keyword; in this case, the keyword is given as-is (without quotes or
305 anything). Each attribute is terminated by a semicolon.
308 group-name { attribute1 attribute-value; attribute2 attribute-value; }
314 Comments start with a hash mark (<tt/#/) or a double slash (<tt>//</tt>);
315 and, extend from the position of the mark to the end of the current line.
316 Hash marks or double slashes inside of strings will <em/not/ start a comment,
320 <sect1>Specifying global options<label id="global-options"><p>
322 Global options may be specified in a group with the name <tt/GLOBAL/. The
323 following attributes are recognized:
327 <tag><tt/ARGUMENTCOLUMN/</tag>
328 This attribute specifies the column in the output, where the argument for
329 an opcode or pseudo instruction starts. The corresponding command line
331 <tt><ref id="option--argument-column" name="--argument-column"></tt>.
334 <tag><tt/COMMENTCOLUMN/</tag>
335 This attribute specifies the column in the output, where the comment starts
336 in a line. It is only used for in-line comments. The corresponding command
338 <tt><ref id="option--comment-column" name="--comment-column"></tt>.
341 <label id="COMMENTS">
342 <tag><tt/COMMENTS/</tag>
343 This attribute may be used instead of the <tt><ref id="option--comments"
344 name="--comments"></tt> option on the command line. It takes a numerical
345 parameter between 0 and 4. Higher values increase the amount of information
346 written to the output file in form of comments.
350 This attribute may be used instead of the <tt><ref id="option--cpu"
351 name="--cpu"></tt> option on the command line. For possible values see
352 there. The value is a string and must be enclosed in quotes.
355 <tag><tt/HEXOFFS/</tag>
356 The attribute is followed by a boolean value. If true, offsets to labels are
357 output in hex, otherwise they're output in decimal notation. The default is
358 false. The attribute may be changed on the command line using the <tt><ref
359 id="option--hexoffs" name="--hexoffs"></tt> option.
362 <tag><tt/INPUTNAME/</tag>
363 The attribute is followed by a string value, which gives the name of the
364 input file to read. If it is present, the disassembler does not accept an
365 input file name on the command line.
368 <tag><tt/INPUTOFFS/</tag>
369 The attribute is followed by a numerical value that gives an offset into
370 the input file which is skipped before reading data. The attribute may be
371 used to skip headers or unwanted code sections in the input file.
374 <tag><tt/INPUTSIZE/</tag>
375 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
376 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
380 <label id="LABELBREAK">
381 <tag><tt/LABELBREAK/</tag>
382 <tt/LABELBREAK/ is followed by a numerical value that specifies the label
383 length that will force a newline. To have all labels on their own lines,
384 you may set this value to zero.
386 See also the <tt><ref id="option--label-break" name="--label-break"></tt>
387 command line option. A <tt/LABELBREAK/ statement in the info file will
388 override any value given on the command line.
391 <tag><tt/MNEMONICCOLUMN/</tag>
392 This attribute specifies the column in the output, where the mnemonic or
393 pseudo instruction is placed. The corresponding command line option is
394 <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
397 <tag><tt/NEWLINEAFTERJMP/</tag>
398 This attribute is followed by a boolean value. When true, a newline is
399 inserted after each <tt/JMP/ instruction. The default is false.
402 <tag><tt/NEWLINEAFTERRTS/</tag>
403 This attribute is followed by a boolean value. When true, a newline is
404 inserted after each <tt/RTS/ instruction. The default is false.
407 <label id="OUTPUTNAME">
408 <tag><tt/OUTPUTNAME/</tag>
409 The attribute is followed by string value, which gives the name of the
410 output file to write. If it is present, specification of an output file on
411 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
414 The default is to use <tt/stdout/ for output, so without this attribute or
415 the corresponding command line option <tt/<ref id="option-o" name="-o">/
416 the output will go to the terminal.
419 <tag><tt/PAGELENGTH/</tag>
420 This attribute may be used instead of the <tt><ref id="option--pagelength"
421 name="--pagelength"></tt> option on the command line. It takes a numerical
422 parameter. Using zero as page length (which is the default) means that no
426 <tag><tt/STARTADDR/</tag>
427 This attribute may be used instead of the <tt><ref id="option--start-addr"
428 name="--start-addr"></tt> option on the command line. It takes a numerical
429 parameter. The default for the start address is $10000 minus the size of
430 the input file (this assumes that the input file is a ROM that contains the
431 reset and irq vectors).
434 <tag><tt/TEXTCOLUMN/</tag>
435 This attribute specifies the column, where the data bytes are output
436 translated into ASCII text. It is only used if
437 <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
438 corresponding command line option is
439 <tt><ref id="option--text-column" name="--text-column"></tt>.
444 <sect1>Specifying Ranges<p>
446 The <tt/RANGE/ directive is used to give information about address ranges. The
447 following attributes are recognized:
451 <tag><tt>COMMENT</tt></tag>
452 This attribute is only allowed if a label is also given. It takes a string
453 as argument. See the description of the <tt><ref id="infofile-label"
454 name="LABEL"></tt> directive for an explanation.
456 <tag><tt>END</tt></tag>
457 This gives the end address of the range. The end address is inclusive, that
458 means, it is part of the range. Of course, it may not be smaller than the
461 <tag><tt>NAME</tt></tag>
462 This is a convenience attribute. It takes a string argument and will cause
463 the disassembler to define a label for the start of the range with the
464 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
465 directive is not needed.
467 <tag><tt>START</tt></tag>
468 This gives the start address of the range.
470 <tag><tt>TYPE</tt></tag>
471 This attribute specifies the type of data within the range. The attribute
472 value is one of the following keywords:
475 <tag><tt>ADDRTABLE</tt></tag>
476 The range consists of data and is disassembled as a table of words
477 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
478 a label is defined for each entry in the table.
480 <tag><tt>BYTETABLE</tt></tag>
481 The range consists of data and is disassembled as a byte table.
483 <tag><tt>CODE</tt></tag>
484 The range consists of code.
486 <tag><tt>DBYTETABLE</tt></tag>
487 The range consists of data and is disassembled as a table of dbytes
488 (double byte values, 16 bit values with the low byte containing the
489 most significant byte of the 16 bit value).
491 <tag><tt>DWORDTABLE</tt></tag>
492 The range consists of data and is disassembled as a table of double
493 words (32 bit values).
495 <tag><tt>RTSTABLE</tt></tag>
496 The range consists of data and is disassembled as a table of words (16 bit
497 values). The values are interpreted as words that are pushed onto the
498 stack and jump to it via <tt/RTS/. This means that they contain
499 <tt/address-1/ of a function, for which a label will get defined by the
502 <tag><tt>SKIP</tt></tag>
503 The range is simply ignored when generating the output file. Please note
504 that this means that reassembling the output file will <em/not/ generate
505 the original file, not only because the missing piece in between, but also
506 because the following code will be located on wrong addresses. Output
507 generated with <tt/SKIP/ ranges will need manual rework.
509 <tag><tt>TEXTTABLE</tt></tag>
510 The range consists of readable text.
512 <tag><tt>WORDTABLE</tt></tag>
513 The range consists of data and is disassembled as a table of words
521 <sect1>Specifying Labels<label id="infofile-label"><p>
523 The <tt/LABEL/ directive is used to give names for labels in the disassembled
524 code. The following attributes are recognized:
528 <tag><tt>ADDR</tt></tag>
529 Followed by a numerical value. Specifies the value of the label.
531 <tag><tt>COMMENT</tt></tag>
532 Attribute argument is a string. The comment will show up in a separate line
533 before the label, if the label is within code or data range, or after the
534 label if it is outside.
539 foo := $0001 ; Comment for label named "foo"
541 ; Comment for label named "bar"
545 <tag><tt>NAME</tt></tag>
546 The attribute is followed by a string value which gives the name of the
547 label. Empty names are allowed, in this case the disassembler will create
548 an unnamed label (see the assembler docs for more information about unnamed
551 <tag><tt>SIZE</tt></tag>
552 This attribute is optional and may be used to specify the size of the data
553 that follows. If a size greater than 1 is specified, the disassembler will
554 create labels in the form <tt/label+offs/ for all bytes within the given
555 range, where <tt/label/ is the label name given with the <tt/NAME/
556 attribute, and <tt/offs/ is the offset within the data.
558 <tag><tt>PARAMSIZE</tt></tag>
559 This optional attribute is followed by a numerical value. It tells the
560 assembler that subroutine calls to this label are followed by
561 "inline parameters" with the given number of bytes, like this:
564 JSR LabelWithParamSize2
573 <sect1>Specifying Segments<label id="infofile-segment"><p>
575 The <tt/SEGMENT/ directive is used to specify a segment within the
576 disassembled code. The following attributes are recognized:
580 <tag><tt>START</tt></tag>
581 Followed by a numerical value. Specifies the start address of the segment.
583 <tag><tt>END</tt></tag>
584 Followed by a numerical value. Specifies the end address of the segment. The
585 end address is the last address that is a part of the segment.
587 <tag><tt>NAME</tt></tag>
588 The attribute is followed by a string value which gives the name of the
592 All attributes are mandatory. Segments must not overlap. The disassembler will
593 change back to the (default) <tt/.code/ segment after the end of each defined
594 segment. That might not be what you want. As a rule of thumb, if you're using
595 segments, you should define segments for all disassembled code.
598 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
600 The <tt/ASMINC/ directive is used to give the names of input files containing
601 symbol assignments in assembler syntax:
608 The usual conventions apply for symbol names. Values may be specified as hex
609 (leading $), binary (leading %) or decimal. The values may optionally
612 NOTE: The include file parser is very simple. Expressions are not allowed, and
613 anything but symbol assignments is flagged as an error (but see the
614 <tt/IGNOREUNKNOWN/ directive below).
616 The following attributes are recognized:
620 <tag><tt>FILE</tt></tag>
621 Followed by a string value. Specifies the name of the file to read.
623 <tag><tt>COMMENTSTART</tt></tag>
624 The optional attribute is followed by a character constant. It specifies the
625 character that starts a comment. The default value is a semicolon. This
626 value is ignored if <tt/IGNOREUNKNOWN/ is true.
628 <tag><tt>IGNOREUNKNOWN</tt></tag>
629 This attribute is optional and is followed by a boolean value. It allows to
630 ignore input lines that don't have a valid syntax. This allows to read in
631 assembler include files that contain more than just symbol assignments.
632 Note: When this attribute is used, the disassembler will ignore any errors
633 in the given include file. This may have undesired side effects.
638 <sect1>An Info File Example<p>
640 The following is a short example for an info file that contains most of the
641 directives explained above:
644 # This is a comment. It extends to the end of the line
646 OUTPUTNAME "kernal.s";
647 INPUTNAME "kernal.bin";
649 PAGELENGTH 0; # No paging
653 # One segment for the whole stuff
654 SEGMENT { START $E000; END $FFFF; NAME "kernal"; };
656 RANGE { START $E612; END $E631; TYPE Code; };
657 RANGE { START $E632; END $E640; TYPE ByteTable; };
658 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
659 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
660 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
662 # Zero-page variables
663 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
664 LABEL { NAME "sal"; ADDR $93; };
665 LABEL { NAME "sah"; ADDR $94; };
666 LABEL { NAME "sas"; ADDR $95; };
669 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
672 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
673 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
674 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
676 # Jump table at end of kernal ROM
677 LABEL { NAME "kscrorg"; ADDR $FFED; };
678 LABEL { NAME "kplot"; ADDR $FFF0; };
679 LABEL { NAME "kiobase"; ADDR $FFF3; };
680 LABEL { NAME "kgbye"; ADDR $FFF6; };
683 LABEL { NAME "hanmi"; ADDR $FFFA; };
684 LABEL { NAME "hares"; ADDR $FFFC; };
685 LABEL { NAME "hairq"; ADDR $FFFE; };
692 da65 (and all cc65 binutils) is (C) Copyright 1998-2011, Ullrich von
693 Bassewitz. For usage of the binaries and/or sources, the following
696 This software is provided 'as-is', without any expressed or implied
697 warranty. In no event will the authors be held liable for any damages
698 arising from the use of this software.
700 Permission is granted to anyone to use this software for any purpose,
701 including commercial applications, and to alter it and redistribute it
702 freely, subject to the following restrictions:
705 <item> The origin of this software must not be misrepresented; you must not
706 claim that you wrote the original software. If you use this software
707 in a product, an acknowledgment in the product documentation would be
708 appreciated but is not required.
709 <item> Altered source versions must be plainly marked as such, and must not
710 be misrepresented as being the original software.
711 <item> This notice may not be removed or altered from any source