1 <!doctype linuxdoc system>
4 <title>da65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
9 da65 is a 6502/65C02 disassembler that is able to read user supplied
10 information about its input data for better results. The output is ready for
11 feeding into ca65, the macro assembler supplied with the cc65 C compiler.
14 <!-- Table of contents -->
17 <!-- Begin the document -->
21 da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
22 the cc65 C compiler and generates output that is suitable for the ca65
25 Besides generating output for ca65, one of the design goals was that the user
26 is able to feed additional information about the code into the disassembler
27 for improved results. This information may include the location and size of
28 tables, and their format.
30 One nice advantage of this concept is that disassembly of copyrighted binaries
31 may be handled without problems: One can just pass the information file for
32 disassembling the binary, so everyone with a legal copy of the binary can
33 generate a nicely formatted disassembly with readable labels and other
40 <sect1>Command line option overview<p>
42 The assembler accepts the following options:
45 ---------------------------------------------------------------------------
46 Usage: da65 [options] [inputfile]
48 -g Add debug info to object file
50 -i name Specify an info file
51 -o name Name the output file
53 -F Add formfeeds to the output
54 -S addr Set the start/load address
55 -V Print the disassembler version
58 --argument-column n Specify argument start column
59 --comment-column n Specify comment start column
60 --comments n Set the comment level for the output
61 --cpu type Set cpu type
62 --debug-info Add debug info to object file
63 --formfeeds Add formfeeds to the output
64 --help Help (this text)
65 --hexoffs Use hexadecimal label offsets
66 --info name Specify an info file
67 --label-break n Add newline if label exceeds length n
68 --mnemonic-column n Specify mnemonic start column
69 --pagelength n Set the page length for the listing
70 --start-addr addr Set the start/load address
71 --text-column n Specify text start column
72 --verbose Increase verbosity
73 --version Print the disassembler version
74 ---------------------------------------------------------------------------
78 <sect1>Command line options in detail<p>
80 Here is a description of all the command line options:
84 <label id="option--argument-column">
85 <tag><tt>--argument-column n</tt></tag>
87 Specifies the column where the argument for a mnemonic or pseudo instruction
91 <label id="option--comment-column">
92 <tag><tt>--comment-column n</tt></tag>
94 Specifies the column where the comment for an instruction starts.
97 <label id="option--comments">
98 <tag><tt>--comments n</tt></tag>
100 Set the comment level for the output. Valid arguments are 0..4. Greater
101 values will increase the level of additional information written to the
102 output file in form of comments.
105 <label id="option--cpu">
106 <tag><tt>--cpu type</tt></tag>
108 Set the CPU type. The option takes a parameter, which may be one of
112 Support for the 65816 is currently not available.
115 <label id="option--formfeeds">
116 <tag><tt>-F, --formfeeds</tt></tag>
118 Add formfeeds to the generated output. This feature is useful together
119 with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
120 If <tt/--formfeeds/ is given, a formfeed is added to the output after each
124 <tag><tt>-g, --debug-info</tt></tag>
126 This option adds the <tt/.DEBUGINFO/ command to the output file, so the
127 assembler will generate debug information when reassembling the generated
131 <tag><tt>-h, --help</tt></tag>
133 Print the short option summary shown above.
136 <label id="option--info">
137 <tag><tt>-i name, --info name</tt></tag>
139 Specify an info file. The info file contains global options that may
140 override or replace command line options plus informations about the code
141 that has to be disassembled. See the separate section <ref id="infofile"
142 name="Info File Format">.
145 <label id="option-o">
146 <tag><tt>-o name</tt></tag>
148 Specify a name for an output file. The default is to use <tt/stdout/, so
149 without this switch or the corresponding <ref id="global-options"
150 name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
151 the output will go to the terminal.
154 <label id="option--label-break">
155 <tag><tt>--label-break n</tt></tag>
157 Adds a newline if the length of a label exceeds the given length.
158 Note: If the label would run into the code in the mid column, a
159 linefeed is always inserted regardless of this setting.
161 This option overrides the <ref id="global-options" name="global option">
162 <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
165 <label id="option--mnemonic-column">
166 <tag><tt>--mnemonic-column n</tt></tag>
168 Specifies the column where a mnemonic or pseudo instrcuction is output.
171 <label id="option--pagelength">
172 <tag><tt>--pagelength n</tt></tag>
174 Sets the length of a listing page in lines. After this number of lines, a
175 new page header is generated. If the <tt><ref id="option--formfeeds"
176 name="--formfeeds"></tt> is also given, a formfeed is inserted before
177 generating the page header.
179 A value of zero for the page length will disable paging of the output.
182 <label id="option--start-addr">
183 <tag><tt>-S addr, --start-addr addr</tt></tag>
185 Specify the start/load address of the binary code that is going to be
186 disassembled. The given address is interpreted as an octal value if
187 preceded with a '0' digit, as a hexadecimal value if preceded
188 with '0x', '0X', or '$', and as a decimal value in all other cases. If no
189 start address is specified, $10000 minus the size of the input file is used.
192 <label id="option--text-column">
193 <tag><tt>--text-column n</tt></tag>
195 Specifies the column where additional text is output. This additional text
196 consists of the bytes encoded in this line in text representation.
199 <tag><tt>-v, --verbose</tt></tag>
201 Increase the disassembler verbosity. Usually only needed for debugging
202 purposes. You may use this option more than one time for even more
206 <tag><tt>-V, --version</tt></tag>
208 Print the version number of the assembler. If you send any suggestions
209 or bugfixes, please include the version number.
215 <sect>Detailed workings<p>
217 <sect1>Supported CPUs<p>
219 The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
220 the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
221 for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
223 With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
224 disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
225 latter understands the same opcodes as the former, plus 16 additional bit
226 manipulation and bit test-and-branch commands.
228 While there is some code for the 65816 in the sources, it is currently
232 <sect1>Attribute map<p>
234 The disassembler works by creating an attribute map for the whole address
235 space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
236 external info file (if given) is read. Disassembly is done in several passes.
237 In all passes with the exception of the last one, information about the
238 disassembled code is gathered and added to the symbol and attribute maps. The
239 last pass generates output using the information from the maps.
243 Some instructions may generate labels in the first pass, while most other
244 instructions do not generate labels, but use them if they are available. Among
245 others, the branch and jump instructions will generate labels for the target
246 of the branch in the first pass. External labels (taken from the info file)
247 have precedence over internally generated ones, They must be valid identifiers
248 as specified for the ca65 assembler. Internal labels (generated by the
249 disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
250 address of the label in upper case letters. You should probably avoid using
251 such label names for external labels.
256 The info file is used to pass additional information about the input code to
257 the disassembler. This includes label names, data areas or tables, and global
258 options like input and output file names. See the <ref id="infofile"
259 name="next section"> for more information.
263 <sect>Info File Format<label id="infofile"><p>
265 The info file contains lists of specifications grouped together. Each group
266 directive has an identifying token and an attribute list enclosed in curly
267 braces. Attributes have a name followed by a value. The syntax of the value
268 depends on the type of the attribute. String attributes are places in double
269 quotes, numeric attributes may be specified as decimal numbers or hexadecimal
270 with a leading dollar sign. There are also attributes where the attribute
271 value is a keyword, in this case the keyword is given as is (without quotes or
272 anything). Each attribute is terminated by a semicolon.
275 group-name { attribute1 attribute-value; attribute2 attribute-value; }
281 Comments start with a hash mark (<tt/#/) and extend from the position of
282 the mark to the end of the current line. Hash marks inside of strings will
283 of course <em/not/ start a comment.
286 <sect1>Specifying global options<label id="global-options"><p>
288 Global options may be specified in a group with the name <tt/GLOBAL/. The
289 following attributes are recognized:
293 <tag><tt/ARGUMENTCOLUMN/</tag>
294 This attribute specifies the column in the output, where the argument for
295 an opcode or pseudo instruction starts. The corresponding command line
297 <tt><ref id="option--argument-column" name="--argument-column"></tt>.
300 <tag><tt/COMMENTCOLUMN/</tag>
301 This attribute specifies the column in the output, where the comment starts
302 in a line. It is only used for in-line comments. The corresponding command
304 <tt><ref id="option--comment-column" name="--comment-column"></tt>.
307 <label id="COMMENTS">
308 <tag><tt/COMMENTS/</tag>
309 This attribute may be used instead of the <tt><ref id="option--comments"
310 name="--comments"></tt> option on the command line. It takes a numerical
311 parameter between 0 and 4. Higher values increase the amount of information
312 written to the output file in form of comments.
316 This attribute may be used instead of the <tt><ref id="option--cpu"
317 name="--cpu"></tt> option on the command line. It takes a string parameter.
320 <tag><tt/INPUTNAME/</tag>
321 The attribute is followed by a string value, which gives the name of the
322 input file to read. If it is present, the disassembler does not accept an
323 input file name on the command line.
326 <tag><tt/INPUTOFFS/</tag>
327 The attribute is followed by a numerical value that gives an offset into
328 the input file which is skipped before reading data. The attribute may be
329 used to skip headers or unwanted code sections in the input file.
332 <tag><tt/INPUTSIZE/</tag>
333 <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
334 data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
338 <label id="LABELBREAK">
339 <tag><tt/LABELBREAK/</tag>
340 <tt/LABELBREAK/ is followed by a numerical value that specifies the label
341 length that will force a newline. To have all labels on their own lines,
342 you may set this value to zero.
344 See also the <tt><ref id="option--label-break" name="--label-break"></tt>
345 command line option. A <tt/LABELBREAK/ statement in the info file will
346 override any value given on the command line.
349 <tag><tt/MNEMONICCOLUMN/</tag>
350 This attribute specifies the column in the output, where the mnemonic or
351 pseudo instruction is placed. The corresponding command line option is
352 <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
355 <label id="OUTPUTNAME">
356 <tag><tt/OUTPUTNAME/</tag>
357 The attribute is followed by string value, which gives the name of the
358 output file to write. If it is present, specification of an output file on
359 the command line using the <tt><ref id="option-o" name="-o"></tt> option is
362 The default is to use <tt/stdout/ for output, so without this attribute or
363 the corresponding command line option <tt/<ref id="option-o" name="-o">/
364 the output will go to the terminal.
367 <tag><tt/PAGELENGTH/</tag>
368 This attribute may be used instead of the <tt><ref id="option--pagelength"
369 name="--pagelength"></tt> option on the command line. It takes a numerical
370 parameter. Using zero as page length (which is the default) means that no
374 <tag><tt/STARTADDR/</tag>
375 This attribute may be used instead of the <tt><ref id="option--start-addr"
376 name="--start-addr"></tt> option on the command line. It takes a numerical
377 parameter. The default for the start address is $10000 minus the size of
378 the input file (this assumes that the input file is a ROM that contains the
379 reset and irq vectors).
382 <tag><tt/TEXTCOLUMN/</tag>
383 This attribute specifies the column, where the data bytes are output
384 translated into ASCII text. It is only used if
385 <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
386 corresponding command line option is
387 <tt><ref id="option--text-column" name="--text-column"></tt>.
392 <sect1>Specifying Ranges<p>
394 The <tt/RANGE/ directive is used to give information about address ranges. The
395 following attributes are recognized:
399 <tag><tt>COMMENT</tt></tag>
400 This attribute is only allowed if a label is also given. It takes a string
401 as argument. See the description of the <tt><ref id="infofile-label"
402 name="LABEL"></tt> directive for an explanation.
404 <tag><tt>END</tt></tag>
405 This gives the end address of the range. The end address is inclusive, that
406 means, it is part of the range. Of course, it may not be smaller than the
409 <tag><tt>NAME</tt></tag>
410 This is a convenience attribute. It takes a string argument and will cause
411 the disassembler to define a label for the start of the range with the
412 given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
413 directive is not needed.
415 <tag><tt>START</tt></tag>
416 This gives the start address of the range.
418 <tag><tt>TYPE</tt></tag>
419 This attribute specifies the type of data within the range. The attribute
420 value is one of the following keywords:
423 <tag><tt>ADDRTABLE</tt></tag>
424 The range consists of data and is disassembled as a table of words
425 (16 bit values). The difference to the <tt/WORDTABLE/ type is that
426 a label is defined for each entry in the table.
428 <tag><tt>BYTETABLE</tt></tag>
429 The range consists of data and is disassembled as a byte table.
431 <tag><tt>CODE</tt></tag>
432 The range consists of code.
434 <tag><tt>DBYTETABLE</tt></tag>
435 The range consists of data and is disassembled as a table of dbytes
436 (double byte values, 16 bit values with the low byte containing the
437 most significant byte of the 16 bit value).
439 <tag><tt>DWORDTABLE</tt></tag>
440 The range consists of data and is disassembled as a table of double
441 words (32 bit values).
443 <tag><tt>RTSTABLE</tt></tag>
444 The range consists of data and is disassembled as a table of words (16 bit
445 values). The values are interpreted as words that are pushed onto the
446 stack and jump to it via <tt/RTS/. This means that they contain
447 <tt/address-1/ of a function, for which a label will get defined by the
450 <tag><tt>SKIP</tt></tag>
451 The range is simply ignored when generating the output file. Please note
452 that this means that reassembling the output file will <em/not/ generate
453 the original file, not only because the missing piece in between, but also
454 because the following code will be located on wrong addresses. Output
455 generated with <tt/SKIP/ ranges will need manual rework.
457 <tag><tt>TEXTTABLE</tt></tag>
458 The range consists of readable text.
460 <tag><tt>WORDTABLE</tt></tag>
461 The range consists of data and is disassembled as a table of words
469 <sect1>Specifying Labels<label id="infofile-label"><p>
471 The <tt/LABEL/ directive is used to give names for labels in the disassembled
472 code. The following attributes are recognized:
476 <tag><tt>ADDR</tt></tag>
477 Followed by a numerical value. Specifies the value of the label.
479 <tag><tt>COMMENT</tt></tag>
480 Attribute argument is a string. The comment will show up in a separate line
481 before the label, if the label is within code or data range, or after the
482 label if it is outside.
487 foo := $0001 ; Comment for label named "foo"
489 ; Comment for label named "bar"
493 <tag><tt>NAME</tt></tag>
494 The attribute is followed by a string value which gives the name of the
495 label. Empty names are allowed, in this case the disassembler will create
496 an unnamed label (see the assembler docs for more information about unnamed
499 <tag><tt>SIZE</tt></tag>
500 This attribute is optional and may be used to specify the size of the data
501 that follows. If a size greater than 1 is specified, the disassembler will
502 create labels in the form <tt/label+offs/ for all bytes within the given
503 range, where <tt/label/ is the label name given with the <tt/NAME/
504 attribute, and <tt/offs/ is the offset within the data.
509 <sect1>Specifying Segments<label id="infofile-segment"><p>
511 The <tt/SEGMENT/ directive is used to specify a segment within the
512 disassembled code. The following attributes are recognized:
516 <tag><tt>START</tt></tag>
517 Followed by a numerical value. Specifies the start address of the segment.
519 <tag><tt>END</tt></tag>
520 Followed by a numerical value. Specifies the end address of the segment. The
521 end address is last the address that is part of the segment.
523 <tag><tt>NAME</tt></tag>
524 The attribute is followed by a string value which gives the name of the
528 All attributes are mandatory. Segments may not overlap. Since there is no
529 explicit "end this segment" pseudo op, the disassembler cannot notify the
530 assembler that one segment has ended. This may lead to errors if you don't
531 define your segments carefully. As a rule of thumb, if you're using segments,
532 your should define segments for all disassembled code.
535 <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
537 The <tt/ASMINC/ directive is used to give the names of input files containing
538 symbol assignments in assembler syntax:
545 The usual conventions apply for symbol names. Values may be specified as hex
546 (leading $), binary (leading %) or decimal. The values may optionally
549 NOTE: The include file parser is very simple. Expressions are not allowed, and
550 anything but symbol assignments is flagged as an error (but see the
551 <tt/IGNOREUNKNOWN/ directive below).
553 The following attributes are recognized:
557 <tag><tt>FILE</tt></tag>
558 Followed by a string value. Specifies the name of the file to read.
560 <tag><tt>COMMENTSTART</tt></tag>
561 The optional attribute is followed by a character constant. It specifies the
562 character that starts a comment. The default value is a semicolon. This
563 value is ignored if <tt/IGNOREUNKNOWN/ is true.
565 <tag><tt>IGNOREUNKNOWN</tt></tag>
566 This attribute is optional and is followed by a boolean value. It allows to
567 ignore input lines that don't have a valid syntax. This allows to read in
568 assembler include files that contain more than just symbol assignments.
569 Note: When this attribute is used, the disassembler will ignore any errors
570 in the given include file. This may have undesired side effects.
575 <sect1>An Info File Example<p>
577 The following is a short example for an info file that contains most of the
578 directives explained above:
581 # This is a comment. It extends to the end of the line
583 OUTPUTNAME "kernal.s";
584 INPUTNAME "kernal.bin";
586 PAGELENGTH 0; # No paging
590 # One segment for the whole stuff
591 SEGMENT { START $E000; END $FFFF; NAME kernal; };
593 RANGE { START $E612; END $E631; TYPE Code; };
594 RANGE { START $E632; END $E640; TYPE ByteTable; };
595 RANGE { START $EA51; END $EA84; TYPE RtsTable; };
596 RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
597 RANGE { START $ED08; END $ED11; TYPE AddrTable; };
599 # Zero page variables
600 LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
601 LABEL { NAME "sal"; ADDR $93; };
602 LABEL { NAME "sah"; ADDR $94; };
603 LABEL { NAME "sas"; ADDR $95; };
606 LABEL { NAME "stack"; ADDR $100; SIZE 255; };
609 LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
610 LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
611 LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
613 # Jump table at end of kernal ROM
614 LABEL { NAME "kscrorg"; ADDR $FFED; };
615 LABEL { NAME "kplot"; ADDR $FFF0; };
616 LABEL { NAME "kiobase"; ADDR $FFF3; };
617 LABEL { NAME "kgbye"; ADDR $FFF6; };
620 LABEL { NAME "hanmi"; ADDR $FFFA; };
621 LABEL { NAME "hares"; ADDR $FFFC; };
622 LABEL { NAME "hairq"; ADDR $FFFE; };
629 <sect>Bugs/Feedback<p>
631 If you have problems using the disassembler, if you find any bugs, or if
632 you're doing something interesting with the assembler, I would be glad to hear
633 from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
634 name="uz@cc65.org">).
640 da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von
641 Bassewitz. For usage of the binaries and/or sources the following
644 This software is provided 'as-is', without any expressed or implied
645 warranty. In no event will the authors be held liable for any damages
646 arising from the use of this software.
648 Permission is granted to anyone to use this software for any purpose,
649 including commercial applications, and to alter it and redistribute it
650 freely, subject to the following restrictions:
653 <item> The origin of this software must not be misrepresented; you must not
654 claim that you wrote the original software. If you use this software
655 in a product, an acknowledgment in the product documentation would be
656 appreciated but is not required.
657 <item> Altered source versions must be plainly marked as such, and must not
658 be misrepresented as being the original software.
659 <item> This notice may not be removed or altered from any source