mirror of
https://github.com/cc65/cc65.git
synced 2024-11-19 06:31:31 +00:00
453 lines
15 KiB
Plaintext
453 lines
15 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
<title>da65 Users Guide
|
|
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
|
<date>2003-08-08
|
|
|
|
<abstract>
|
|
da65 is a 6502/65C02 disassembler that is able to read user supplied
|
|
information about its input data for better results. The output is ready for
|
|
feeding into ca65, the macro assembler supplied with the cc65 C compiler.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
<sect>Overview<p>
|
|
|
|
da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
|
|
the cc65 C compiler and generates output that is suitable for the ca65
|
|
macro assembler.
|
|
|
|
Besides generating output for ca65, one of the design goals was that the user
|
|
is able to feed additional information about the code into the disassembler
|
|
for improved results. This information may include the location and size of
|
|
tables, and their format.
|
|
|
|
One nice advantage of this concept is that disassembly of copyrighted binaries
|
|
may be handled without problems: One can just pass the information file for
|
|
disassembling the binary, so everyone with a legal copy of the binary can
|
|
generate a nicely formatted disassembly with readable labels and other
|
|
information.
|
|
|
|
|
|
<sect>Usage<p>
|
|
|
|
|
|
<sect1>Command line option overview<p>
|
|
|
|
The assembler accepts the following options:
|
|
|
|
<tscreen><verb>
|
|
---------------------------------------------------------------------------
|
|
Usage: da65 [options] [inputfile]
|
|
Short options:
|
|
-g Add debug info to object file
|
|
-h Help (this text)
|
|
-i name Specify an info file
|
|
-o name Name the output file
|
|
-v Increase verbosity
|
|
-F Add formfeeds to the output
|
|
-S addr Set the start/load address
|
|
-V Print the disassembler version
|
|
|
|
Long options:
|
|
--cpu type Set cpu type
|
|
--debug-info Add debug info to object file
|
|
--formfeeds Add formfeeds to the output
|
|
--help Help (this text)
|
|
--info name Specify an info file
|
|
--pagelength n Set the page length for the listing
|
|
--start-addr addr Set the start/load address
|
|
--verbose Increase verbosity
|
|
--version Print the disassembler version
|
|
---------------------------------------------------------------------------
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1>Command line options in detail<p>
|
|
|
|
Here is a description of all the command line options:
|
|
|
|
<descrip>
|
|
|
|
<label id="option--cpu">
|
|
<tag><tt>--cpu type</tt></tag>
|
|
|
|
Set the CPU type. The option takes a parameter, which may be one of
|
|
|
|
6502, 65SC02, 65C02
|
|
|
|
Support for the 65816 is currently not available.
|
|
|
|
|
|
<label id="option--formfeeds">
|
|
<tag><tt>-F, --formfeeds</tt></tag>
|
|
|
|
Add formfeeds to the generated output. This feature is useful together
|
|
with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
|
|
If <tt/--formfeeds/ is given, a formfeed is added to the output after each
|
|
page.
|
|
|
|
|
|
<tag><tt>-g, --debug-info</tt></tag>
|
|
|
|
This option adds the <tt/.DEBUGINFO/ command to the output file, so the
|
|
assembler will generate debug information when reassembling the generated
|
|
output.
|
|
|
|
|
|
<tag><tt>-h, --help</tt></tag>
|
|
|
|
Print the short option summary shown above.
|
|
|
|
|
|
<label id="option--info">
|
|
<tag><tt>-i name, --info name</tt></tag>
|
|
|
|
Specify an info file. The info file contains global options that may
|
|
override or replace command line options plus informations about the code
|
|
that has to be disassembled. See the separate section <ref id="infofile"
|
|
name="Info File Format">.
|
|
|
|
|
|
<label id="option-o">
|
|
<tag><tt>-o name</tt></tag>
|
|
|
|
The default output name is the name of the input file with the extension
|
|
replaced by ".dis". If you don't like that, you may give another name with
|
|
the -o option. The output file will be placed in the same directory as
|
|
the source file, or, if -o is given, the full path in this name is used.
|
|
|
|
|
|
<label id="option--pagelength">
|
|
<tag><tt>--pagelength n</tt></tag>
|
|
|
|
Sets the length of a listing page in lines. After this number of lines, a
|
|
new page header is generated. If the <tt><ref id="option--formfeeds"
|
|
name="--formfeeds"></tt> is also given, a formfeed is inserted before
|
|
generating the page header.
|
|
|
|
A value of -1 for the page length will disable paging of the output.
|
|
|
|
|
|
<label id="option--start-addr">
|
|
<tag><tt>-S addr, --start-addr addr</tt></tag>
|
|
|
|
Specify the start/load address of the binary code that is going to be
|
|
disassembled. The given address is interpreted as an octal value if
|
|
preceeded with a '0' digit, as a hexadecimal value if preceeded with '0x',
|
|
'0X', or '$', and as a decimal value in all other cases. If no start address
|
|
is specified, 0xC000 is used - which is often not what you want.
|
|
|
|
|
|
<tag><tt>-v, --verbose</tt></tag>
|
|
|
|
Increase the assembler verbosity. Usually only needed for debugging
|
|
purposes. You may use this option more than one time for even more
|
|
verbose output.
|
|
|
|
|
|
<tag><tt>-V, --version</tt></tag>
|
|
|
|
Print the version number of the assembler. If you send any suggestions
|
|
or bugfixes, please include the version number.
|
|
|
|
</descrip>
|
|
<p>
|
|
|
|
|
|
<sect>Detailed workings<p>
|
|
|
|
<sect1>Supported CPUs<p>
|
|
|
|
The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
|
|
the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
|
|
for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
|
|
|
|
With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
|
|
disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
|
|
latter understands the same opcodes as the former, plus 16 additional bit
|
|
manipulation and bit test-and-branch commands.
|
|
|
|
While there is some code for the 65816 in the sources, it is currently
|
|
unsupported.
|
|
|
|
|
|
<sect1>Attribute map<p>
|
|
|
|
The disassembler works by creating an attribute map for the whole address
|
|
space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
|
|
external info file (if given) is read. Disassembly is done in several passes.
|
|
In all passes with the exception of the last one, information about the
|
|
disassembled code is gathered and added to the symbol and attribute maps. The
|
|
last pass generates output using the information from the maps.
|
|
|
|
<sect1>Labels<p>
|
|
|
|
Some instructions may generate labels in the first pass, while most other
|
|
instructions do not generate labels, but use them if they are available. Among
|
|
others, the branch and jump instructions will generate labels for the target
|
|
of the branch in the first pass. External labels (taken from the info file)
|
|
have precedence over internally generated ones, They must be valid identifiers
|
|
as specified for the ca65 assembler. Internal labels (generated by the
|
|
disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
|
|
address of the label in upper case letters. You should probably avoid using
|
|
such label names for external labels.
|
|
|
|
|
|
<sect1>Info File<p>
|
|
|
|
The info file is used to pass additional information about the input code to
|
|
the disassembler. This includes label names, data areas or tables, and global
|
|
options like input and output file names. See the <ref id="infofile"
|
|
name="next section"> for more information.
|
|
|
|
|
|
|
|
<sect>Info File Format<p><label id="infofile">
|
|
|
|
The info file contains lists of specifications grouped together. Each group
|
|
directive has an identifying token and an attribute list enclosed in curly
|
|
braces. Attributes have a name followed by a value. The syntax of the value
|
|
depends on the type of the attribute. String attributes are places in double
|
|
quotes, numeric attributes may be specified as decimal numbers or hexadecimal
|
|
with a leading dollar sign. There are also attributes where the attribute
|
|
value is a keyword, in this case the keyword is given as is (without quotes or
|
|
anything). Each attribute is terminated by a semicolon.
|
|
|
|
<tscreen><verb>
|
|
group-name { attribute1 attribute-value; attribute2 attribute-value; }
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1>Specifying global options<p>
|
|
|
|
Global options may be specified in a group with the name <tt/GLOBAL/. The
|
|
following attributes are recognized:
|
|
|
|
<descrip>
|
|
|
|
<tag><tt>INPUTNAME</tt></tag>
|
|
|
|
The attribute is followed by a string value, which gives the name of the
|
|
input file to read. If it is present, the disassembler does not accept an
|
|
input file name on the command line.
|
|
|
|
|
|
<tag><tt>OUTPUTNAME</tt></tag>
|
|
|
|
The attribute is followed by string value, which gives the name of the
|
|
output file to write. If it is present, specification of an output file on
|
|
the command line using the <tt><ref id="option-o" name="-o"></tt> option is
|
|
not allowed.
|
|
|
|
If no output name is specified, the name of the input file with the
|
|
extension replaced by ".dis" is used.
|
|
|
|
|
|
<tag><tt>PAGELENGTH</tt></tag>
|
|
|
|
This attribute may be used instead of the <tt><ref id="option--pagelength"
|
|
name="--pagelength"></tt> option on the command line. It takes a numerical
|
|
parameter.
|
|
|
|
|
|
<tag><tt>STARTADDR</tt></tag>
|
|
|
|
This attribute may be used instead of the <tt><ref id="option--start-addr"
|
|
name="--start-addr"></tt> option on the command line. It takes a numerical
|
|
parameter.
|
|
|
|
|
|
<tag><tt>CPU</tt></tag>
|
|
|
|
This attribute may be used instead of the <tt><ref id="option--cpu"
|
|
name="--cpu"></tt> option on the command line. It takes a string parameter.
|
|
|
|
</descrip>
|
|
|
|
|
|
<sect1>Specifying Ranges<p>
|
|
|
|
The <tt/RANGE/ directive is used to give information about address ranges. The
|
|
following attributes are recognized:
|
|
|
|
<descrip>
|
|
|
|
<tag><tt>START</tt></tag>
|
|
|
|
This gives the start address of the range.
|
|
|
|
|
|
<tag><tt>END</tt></tag>
|
|
|
|
This gives the end address of the range. The end address is inclusive, that
|
|
means, it is part of the range. Of course, it may not be smaller than the
|
|
start address.
|
|
|
|
|
|
<tag><tt>TYPE</tt></tag>
|
|
|
|
This attribute specifies the type of data within the range. The attribute
|
|
value is one of the following keywords:
|
|
|
|
<descrip>
|
|
<tag><tt>CODE</tt></tag>
|
|
The range consists of code.
|
|
|
|
<tag><tt>BYTETABLE</tt></tag>
|
|
The range consists of data and is disassembled as a byte table.
|
|
|
|
<tag><tt>WORDTABLE</tt></tag>
|
|
The range consists of data and is disassembled as a table of words
|
|
(16 bit values).
|
|
|
|
<tag><tt>DWORDTABLE</tt></tag>
|
|
The range consists of data and is disassembled as a table of double
|
|
words (32 bit values).
|
|
|
|
<tag><tt>ADDRTABLE</tt></tag>
|
|
The range consists of data and is disassembled as a table of words
|
|
(16 bit values). The difference to the <tt/WORDTABLE/ type is that
|
|
a label is defined for each entry in the table.
|
|
|
|
<tag><tt>RTSTABLE</tt></tag>
|
|
The range consists of data and is disassembled as a table of words (16 bit
|
|
values). The values are interpreted as words that are pushed onto the
|
|
stack and jump to it via <tt/RTS/. This means that they contain
|
|
<tt/address-1/ of a function, for which a label will get defined by the
|
|
disassembler.
|
|
|
|
<tag><tt>TEXTTABLE</tt></tag>
|
|
The range consists of readable text.
|
|
</descrip>
|
|
|
|
</descrip>
|
|
|
|
|
|
<sect1>Specifying Labels<p>
|
|
|
|
The <tt/LABEL/ directive is used to give names for labels in the disassembled
|
|
code. The following attributes are recognized:
|
|
|
|
<descrip>
|
|
|
|
<tag><tt>NAME</tt></tag>
|
|
|
|
The attribute is followed by a string value which gives the name of the
|
|
label.
|
|
|
|
|
|
<tag><tt>ADDR</tt></tag>
|
|
|
|
Followed by a numerical value. Specifies the value of the label.
|
|
|
|
|
|
<tag><tt>SIZE</tt></tag>
|
|
|
|
This attribute is optional and may be used to specifiy the size of the data
|
|
that follows. If a size greater than 1 is specified, the disassembler will
|
|
create labels in the form <tt/label+offs/ for all bytes within the given
|
|
range, where <tt/label/ is the label name given with the <tt/NAME/
|
|
attribute, and <tt/offs/ is the offset within the data.
|
|
|
|
</descrip>
|
|
|
|
|
|
<sect1>An Info File Example<p>
|
|
|
|
The following is a short example for an info file that contains most of the
|
|
directives explained above:
|
|
|
|
<tscreen><verb>
|
|
GLOBAL {
|
|
OUTPUTNAME "kernal.s";
|
|
INPUTNAME "kernal.bin";
|
|
STARTADDR $E000;
|
|
PAGELENGTH -1; # No paging
|
|
CPU "6502";
|
|
};
|
|
|
|
|
|
RANGE { START $E612; END $E631; TYPE Code; };
|
|
RANGE { START $E632; END $E640; TYPE ByteTable; };
|
|
RANGE { START $EA51; END $EA84; TYPE RtsTable; };
|
|
RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
|
|
RANGE { START $ED08; END $ED11; TYPE AddrTable; };
|
|
|
|
# Zero page variables
|
|
LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
|
|
LABEL { NAME "sal"; ADDR $93; };
|
|
LABEL { NAME "sah"; ADDR $94; };
|
|
LABEL { NAME "sas"; ADDR $95; };
|
|
|
|
# Stack
|
|
LABEL { NAME "stack"; ADDR $100; SIZE 255; };
|
|
|
|
# Indirect vectors
|
|
LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
|
|
LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
|
|
LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
|
|
|
|
# Jump table at end of kernal ROM
|
|
LABEL { NAME "kscrorg"; ADDR $FFED; };
|
|
LABEL { NAME "kplot"; ADDR $FFF0; };
|
|
LABEL { NAME "kiobase"; ADDR $FFF3; };
|
|
LABEL { NAME "kgbye"; ADDR $FFF6; };
|
|
|
|
# Hardware vectors
|
|
LABEL { NAME "hanmi"; ADDR $FFFA; };
|
|
LABEL { NAME "hares"; ADDR $FFFC; };
|
|
LABEL { NAME "hairq"; ADDR $FFFE; };
|
|
</verb></tscreen>
|
|
|
|
|
|
|
|
|
|
|
|
<sect>Bugs/Feedback<p>
|
|
|
|
If you have problems using the disassembler, if you find any bugs, or if
|
|
you're doing something interesting with the assembler, I would be glad to hear
|
|
from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
|
|
name="uz@cc65.org">).
|
|
|
|
|
|
|
|
<sect>Copyright<p>
|
|
|
|
da65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
|
|
Bassewitz. For usage of the binaries and/or sources the following
|
|
conditions do apply:
|
|
|
|
This software is provided 'as-is', without any expressed or implied
|
|
warranty. In no event will the authors be held liable for any damages
|
|
arising from the use of this software.
|
|
|
|
Permission is granted to anyone to use this software for any purpose,
|
|
including commercial applications, and to alter it and redistribute it
|
|
freely, subject to the following restrictions:
|
|
|
|
<enum>
|
|
<item> The origin of this software must not be misrepresented; you must not
|
|
claim that you wrote the original software. If you use this software
|
|
in a product, an acknowledgment in the product documentation would be
|
|
appreciated but is not required.
|
|
<item> Altered source versions must be plainly marked as such, and must not
|
|
be misrepresented as being the original software.
|
|
<item> This notice may not be removed or altered from any source
|
|
distribution.
|
|
</enum>
|
|
|
|
|
|
|
|
</article>
|
|
|
|
|
|
|
|
|