X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fda65.sgml;h=a8e32e1c851aab07b74061d70a0b875a9b60dbce;hb=977bca922b423adecb69da632221effe4fd8cf09;hp=dc2db66fb65b9c88175496eb891ae465775ae6d1;hpb=a71c6b72b01b21eda080f30b9c0bb222fddbc14b;p=cc65 diff --git a/doc/da65.sgml b/doc/da65.sgml index dc2db66fb..a8e32e1c8 100644 --- a/doc/da65.sgml +++ b/doc/da65.sgml @@ -2,12 +2,14 @@
da65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-08-08 +<author> +<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> +<date>2014-11-23 <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 +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> @@ -23,7 +25,7 @@ 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 +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. @@ -55,15 +57,20 @@ Short options: -V Print the disassembler version Long options: + --argument-column n Specify argument start column + --comment-column n Specify comment start column --comments n Set the comment level for the output --cpu type Set cpu type --debug-info Add debug info to object file --formfeeds Add formfeeds to the output --help Help (this text) + --hexoffs Use hexadecimal label offsets --info name Specify an info file --label-break n Add newline if label exceeds length n + --mnemonic-column n Specify mnemonic start column --pagelength n Set the page length for the listing --start-addr addr Set the start/load address + --text-column n Specify text start column --verbose Increase verbosity --version Print the disassembler version --------------------------------------------------------------------------- @@ -76,6 +83,19 @@ Here is a description of all the command line options: <descrip> + <label id="option--argument-column"> + <tag><tt>--argument-column n</tt></tag> + + Specifies the column where the argument for a mnemonic or pseudo instruction + starts. + + + <label id="option--comment-column"> + <tag><tt>--comment-column n</tt></tag> + + Specifies the column where the comment for an instruction starts. + + <label id="option--comments"> <tag><tt>--comments n</tt></tag> @@ -88,10 +108,18 @@ Here is a description of all the command line options: <tag><tt>--cpu type</tt></tag> Set the CPU type. The option takes a parameter, which may be one of + <itemize> + <item>6502 + <item>6502x + <item>65sc02 + <item>65c02 + <item>huc6280 + <item>4510 + </itemize> - 6502, 65SC02, 65C02 - - Support for the 65816 is currently not available. + 6502x is for the NMOS 6502 with unofficial opcodes. huc6280 is the CPU of + the PC engine. 4510 is the CPU of the Commodore C65. Support for the 65816 + currently is not available. <label id="option--formfeeds"> @@ -106,7 +134,7 @@ Here is a description of all the command line options: <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 + assembler will generate debug information when re-assembling the generated output. @@ -115,6 +143,12 @@ Here is a description of all the command line options: Print the short option summary shown above. + <label id="option--hexoffs"> + <tag><tt>--hexoffs</tt></tag> + + Output label offsets in hexadecimal instead of decimal notation. + + <label id="option--info"> <tag><tt>-i name, --info name</tt></tag> @@ -144,6 +178,12 @@ Here is a description of all the command line options: <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>. + <label id="option--mnemonic-column"> + <tag><tt>--mnemonic-column n</tt></tag> + + Specifies the column where a mnemonic or pseudo instrcuction is output. + + <label id="option--pagelength"> <tag><tt>--pagelength n</tt></tag> @@ -165,6 +205,13 @@ Here is a description of all the command line options: start address is specified, $10000 minus the size of the input file is used. + <label id="option--text-column"> + <tag><tt>--text-column n</tt></tag> + + Specifies the column where additional text is output. This additional text + consists of the bytes encoded in this line in text representation. + + <tag><tt>-v, --verbose</tt></tag> Increase the disassembler verbosity. Usually only needed for debugging @@ -194,6 +241,11 @@ 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. +When disassembling 4510 code, due to handling of 16-bit wide branches, da65 +can produce output that can not be re-assembled, when one or more of those +branches point outside of the disassembled memory. This can happen when text +or binary data is processed. + While there is some code for the 65816 in the sources, it is currently unsupported. @@ -203,7 +255,7 @@ unsupported. 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 +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. @@ -237,19 +289,19 @@ 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 +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; } + group-name { attribute1 attribute-value; attribute2 attribute-value; } </verb></tscreen> <sect1>Comments<p> -Comments start with a hash mark (<tt/#/) and extend from the position of +Comments start with a hash mark (<tt/#/); and, extend from the position of the mark to the end of the current line. Hash marks inside of strings will -of course <em/not/ start a comment. +<em/not/ start a comment, of course. <sect1>Specifying global options<label id="global-options"><p> @@ -259,38 +311,61 @@ following attributes are recognized: <descrip> - <tag><tt>COMMENTS</tt></tag> + <tag><tt/ARGUMENTCOLUMN/</tag> + This attribute specifies the column in the output, where the argument for + an opcode or pseudo instruction starts. The corresponding command line + option is + <tt><ref id="option--argument-column" name="--argument-column"></tt>. + + + <tag><tt/COMMENTCOLUMN/</tag> + This attribute specifies the column in the output, where the comment starts + in a line. It is only used for in-line comments. The corresponding command + line option is + <tt><ref id="option--comment-column" name="--comment-column"></tt>. + + + <label id="COMMENTS"> + <tag><tt/COMMENTS/</tag> This attribute may be used instead of the <tt><ref id="option--comments" name="--comments"></tt> option on the command line. It takes a numerical parameter between 0 and 4. Higher values increase the amount of information written to the output file in form of comments. - <tag><tt>CPU</tt></tag> + <tag><tt/CPU/</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. + name="--cpu"></tt> option on the command line. For possible values see + there. The value is a string and must be enclosed in quotes. - <tag><tt>INPUTNAME</tt></tag> + <tag><tt/HEXOFFS/</tag> + The attribute is followed by a boolean value. If true, offsets to labels are + output in hex, otherwise they're output in decimal notation. The default is + false. The attribute may be changed on the command line using the <tt><ref + id="option--hexoffs" name="--hexoffs"></tt> option. + + + <tag><tt/INPUTNAME/</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>INPUTOFFS</tt></tag> + <tag><tt/INPUTOFFS/</tag> The attribute is followed by a numerical value that gives an offset into the input file which is skipped before reading data. The attribute may be used to skip headers or unwanted code sections in the input file. - <tag><tt>INPUTSIZE</tt></tag> + <tag><tt/INPUTSIZE/</tag> <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/ is ignored. <label id="LABELBREAK"> - <tag><tt>LABELBREAK</tt></tag> + <tag><tt/LABELBREAK/</tag> <tt/LABELBREAK/ is followed by a numerical value that specifies the label length that will force a newline. To have all labels on their own lines, you may set this value to zero. @@ -300,8 +375,24 @@ following attributes are recognized: override any value given on the command line. + <tag><tt/MNEMONICCOLUMN/</tag> + This attribute specifies the column in the output, where the mnemonic or + pseudo instruction is placed. The corresponding command line option is + <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>. + + + <tag><tt/NEWLINEAFTERJMP/</tag> + This attribute is followed by a boolean value. When true, a newline is + inserted after each <tt/JMP/ instruction. The default is false. + + + <tag><tt/NEWLINEAFTERRTS/</tag> + This attribute is followed by a boolean value. When true, a newline is + inserted after each <tt/RTS/ instruction. The default is false. + + <label id="OUTPUTNAME"> - <tag><tt>OUTPUTNAME</tt></tag> + <tag><tt/OUTPUTNAME/</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 @@ -312,20 +403,28 @@ following attributes are recognized: the output will go to the terminal. - <tag><tt>PAGELENGTH</tt></tag> + <tag><tt/PAGELENGTH/</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. Using zero as page length (which is the default) means that no pages are generated. - <tag><tt>STARTADDR</tt></tag> + <tag><tt/STARTADDR/</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. The default for the start address is $10000 minus the size of the input file (this assumes that the input file is a ROM that contains the reset and irq vectors). + + <tag><tt/TEXTCOLUMN/</tag> + This attribute specifies the column, where the data bytes are output + translated into ASCII text. It is only used if + <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The + corresponding command line option is + <tt><ref id="option--text-column" name="--text-column"></tt>. + </descrip> @@ -446,14 +545,39 @@ code. The following attributes are recognized: </descrip> +<sect1>Specifying Segments<label id="infofile-segment"><p> + +The <tt/SEGMENT/ directive is used to specify a segment within the +disassembled code. The following attributes are recognized: + +<descrip> + + <tag><tt>START</tt></tag> + Followed by a numerical value. Specifies the start address of the segment. + + <tag><tt>END</tt></tag> + Followed by a numerical value. Specifies the end address of the segment. The + end address is the last address that is a part of the segment. + + <tag><tt>NAME</tt></tag> + The attribute is followed by a string value which gives the name of the + segment. +</descrip> + +All attributes are mandatory. Segments must not overlap. The disassembler will +change back to the (default) <tt/.code/ segment after the end of each defined +segment. That might not be what you want. As a rule of thumb, if you're using +segments, you should define segments for all disassembled code. + + <sect1>Specifying Assembler Includes<label id="infofile-asminc"><p> The <tt/ASMINC/ directive is used to give the names of input files containing symbol assignments in assembler syntax: <tscreen><verb> - Name = value - Name := value + Name = value + Name := value </verb></tscreen> The usual conventions apply for symbol names. Values may be specified as hex @@ -501,56 +625,47 @@ directives explained above: CPU "6502"; }; + # One segment for the whole stuff + SEGMENT { START $E000; END $FFFF; NAME "kernal"; }; - 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; }; + 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; }; + # 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; }; + 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 + 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; }; + 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; }; + 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 +da65 (and all cc65 binutils) is (C) Copyright 1998-2011, 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 @@ -562,20 +677,16 @@ 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. +<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> - - - -