mirror of
https://github.com/cc65/cc65.git
synced 2024-09-27 04:54:54 +00:00
Completed the first version of the da65 docs
git-svn-id: svn://svn.cc65.org/cc65/trunk@2270 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz
parent
98cdbaba4b
commit
53538332e5
274
doc/da65.sgml
274
doc/da65.sgml
@ -27,11 +27,11 @@ 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 information for
|
||||
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.
|
||||
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>
|
||||
@ -43,10 +43,11 @@ The assembler accepts the following options:
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: da65 [options] file
|
||||
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
|
||||
@ -58,6 +59,7 @@ Long options:
|
||||
--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
|
||||
@ -103,6 +105,16 @@ Here is a description of all the command line options:
|
||||
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
|
||||
@ -122,6 +134,7 @@ Here is a description of all the command line options:
|
||||
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
|
||||
@ -147,6 +160,255 @@ Here is a description of all the command line options:
|
||||
<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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user