

















                                    Dunfield

                            8080 Cross Disassembler


                                  Users Guide





                                  Release 1.2

                               Revised 05-Jan-98










                         Dunfield Development Services
                         -----------------------------
                             High quality tools for
                              Embedded Development
                                 at low prices.

                            http://www.dunfield.com


                       Copyright 1991-2006 Dave Dunfield
                              All rights reserved.



                                  DISASSEMBLER

                               TABLE OF CONTENTS


                                                                         Page

     1. INTRODUCTION                                                        1


     2. USING THE DISASSEMBLER                                              2

        2.1 Command Syntax                                                  2
        2.2 Command Option Switches                                         2
        2.3 Output File                                                     4

     3. PREDEFINED SYMBOLS AND BLOCK TYPES                                  5


     4. ADDING COMMENTS                                                     8

    DISASSEMBLER                                                     Page: 1


    1. INTRODUCTION

          Dunfield cross disassemblers run on a PC compatible computer,  and
       process binary machine  code  for  a  specific  processor,  producing
       either an assembly listing,  or an assembly source file  representing
       the content of that code.

          The disassemblers feature several advanced features, including:

          - Accept a user defined symbol table
          - Generate initial symbol table
          - Accept definitions for memory block bytes (Code, data etc.)
          - Merge a file of comments into the disassembly output.

          With careful use of these features,  you can generate  a  complete
       assembly source file for a given binary image,  without resorting  to
       editing the output of the disassembler. This allows you to re-run the
       disassemler as many times as you like without losing the  definitions
       and comments that you insert.  (With most disassemblers,  every  time
       you run the disassembler, you have to start fresh).

          This package contains a cross disassembler for the 8080 processor.

            DIS80       - 8080 Disassembler
    DISASSEMBLER                                                     Page: 2


    2. USING THE DISASSEMBLER

    NOTE: All numbers entered into the disassembler, either on the command line,
    or within it's various control files can be entered in any of the following
    number bases by immediately preceeding them with the indicated character:

            % - Binary      (base 2)
            @ - Octal       (base 8)
            & - Decimal     (base 10)
            $ - Hexidecimal (base 16)

       In the remainder of this document,  the number base indicated for  an
       entry indicates the default base that will be assumed if  it  is  not
       explicitly specified using one of these characters.

       2.1 Command Syntax

             The syntax of the disassembler command is:

                DIS80 <filename> [option switches...] [>outfile]

             <filename>  is the name of the file containing the machine code
          to be disassembled. The file is read as pure binary data.  If your
          file is in some other format  (Such as the INTEL or  MOTOROLA  HEX
          download records that are output by many PROM readers),  you  must
          convert it to binary before running the  disassembler.  For  INTEL
          and MOTOROLA format files, you can use the supplied HEXFMT command
          to perform the conversion.

       2.2 Command Option Switches

          -A - Assembly source output

               This option suppresses the output of the Address, Opcode data
               and ASCII text fields in the output file. When this option is
               enabled,  the resulting output file is suitable for input  to
               our cross assemblers.

          -B - define Byte symbols

               Similar to '-d' below, except that symbols are also generated
               for 8 bit (BYTE) symbols.

          -D - Define symbols

               Causes the disassembler to pre-define default symbols for any
               addresses or other 16 bit references which occur  within  the
               memory range of the image.  Symbols are  defined  as  'Hxxxx'
               where 'xxxx' is the hexidecimal memory address.  Symbols will
               be generated for ALL qualifying references.  Any symbol which
               does not correspond to addresses occuring  within  the  image
               are output as 'EQU' statements at the end.
    DISASSEMBLER                                                     Page: 3


          -E - Exclude EQU symbols

               When using the  'w='  option to write the symbol table  to  a
               file, this option inhibits the output of symbols which do not
               occur within the range of addresses occupied by the image.

          A=value - set starting Address

               Specifies the address (in hex) of the first instruction which
               is disassembled.  If not given,  a default value of $0000  is
               assumed.

          B=size - set Beginning offset

               Specify offset into file  to  begin  disassembly.  When  this
               parameter is  given,  the  disassembler  skips  'size'  bytes
               (decimal) into the input file before beginning disassembly.

          C=file - load Comments

               This option causes the assembler to  load  comments  for  the
               output listing from the named file.

          D=file - Load symbol/type data

               This option causes  the  assembler  to  load  symbols  and/or
               memory block definitions from the named file.

          N=num - set Number of instructions

               If this  parameter  is  given,  the  disassembler  will  only
               process the requested 'num' (decimal) number of instructions.

          W=file - Write symbol/type data

               If this parameter is given,  the disassembler will write  out
               it's symbol table and memory block type  data  to  the  named
               file.  This is a good way to generate an initial symbol table
               file for an image (which you can edit as you progress).
    DISASSEMBLER                                                     Page: 4


       2.3 Output File

             The disassembler writes it output  file  to  the  DOS  standard
          output device,  which will normally appear on the PC console,  but
          may be redirected to a file with the '>' operator.

             The format of each  line  output  by  the  disassembler  is  as
          follows:

          <Address> <Opcode> <Ascii> <Label> <Instruction> <Operands>

             <Address>  is the hexidecimal address at which the  instruction
          on this line occurs.  This field is disabled from the listing when
          the '-a' option is used.  Unless otherwise specified  (with 'a='),
          the disassembler assumes  that  the  first  instruction  processed
          occurs at address $0000.

             <Opcode>  is  the  actual  data  values  which  make   up   the
          instruction opcode.  Multiple bytes may be displayed, depending on
          the length of the instruction which is represented  by  the  first
          byte(s).  This field is disabled from the listing  when  the  '-a'
          option is used.

             <Ascii>  is the  ASCII  TEXT  representation  of  the  <Opcode>
          values.  Any unprintable characters  will  be  displayed  as  dots
          ('.'). This field is useful to help identify text data areas.  The
          text field is disabled from the listing when the  '-a'  option  is
          used.

             <Label>  is any label which occurs at this address.  This field
          may appear when any of the '-b', '-d', or 'd=' options are used.

             <Instruction>  is  the  assembly  language  instruction   which
          represents the <Opcode> values.

             The  <Operands>  field  will  contain  any  operands   to   the
          instruction.
    DISASSEMBLER                                                     Page: 5


    3. PREDEFINED SYMBOLS AND BLOCK TYPES

          The disassmbler can load (with 'D=')  a file containing predefined
       symbols and memory block types before commencing disassembly. Careful
       use of these  features  can  greatly  increase  the  readability  and
       accuracy of the output file.

          When a predefinition file is loaded,  each line must have  one  of
       the following formats:

          Symbol names must occur in column 1,  and must not begin with  '!'
       or '*'. Following the symbol must be 1 or more whitespace characters,
       and the address to be assigned to the symbol (in hex):

                                 eg: BEGIN E000

          Note  that  symbols  defined  in  this  manner  may  contain   any
       characters other than  SPACE  or  TAB.  This  can  be  used  to  your
       advantage to create symbols which are actually expressions  (See also
       the '!=' block type).

          Lines beginning with  '*'  are ignored by the  disassembler.  This
       provides a convienient way to make notes about your definitions:

                       eg: * Parser command table follows

          Lines beginning with '!' are block type records. Following the '!'
       is a block type identifier:

            !<  - Byte data
            ![  - Byte data - Possible symbol   *1
            !>  - Word data
            !]  - Word data - Possible symbol   *1
            !'  - Character data                *2
            !"  - String data                   *2
            !=  - Special symbol definition

       *1: '[' and ']' define data items which may be included in the symbol
       table ('-B', '-D', or 'D=').  The '<', '>',  ''',  and '"' data types
       are NEVER associated with the symbol table.

       *2: Character data is encoded as single characters within ''.  String
       data is encoded as multiple characters within  "".  In  either  case,
       unprintable data is encoded as single HEX bytes.
    DISASSEMBLER                                                     Page: 6


          Following  the  block  type  identifier  is  the  first  and  last
       addresses of the block (in HEX),  the address  (hex)  followed by '#'
       and a block size (decimal),  or just '#' and a block size  (decimal).
       Blocks defined with just '#'  will start at the address following the
       block or symbol defined immediately above  it  in  the  predefinition
       file.

                eg: BYTE1   45A3    <- Symbol at 45A3
                    !<45A3  45B6    <- Byte data: 45A3 to 45B6
                    WORD1   55A3    <- Symbol at 55A3
                    !>#20           <- 20 bytes (10 words: 55A3 to 55B6)
                    !"#10           <- 10 bytes (string: 55B7 to 55C0)
                    !<5000 #10      <- 10 bytes starting at 5000

          The lead in sequence '!='  denotes a  "special"  symbol,  which is
       treated as if it is defined in the module,  but is not.  This has two
       effects.  1)  The symbol will NOT be output in the label field of any
       instruction,  and 2)  The symbol will be output to the 'W=' file even
       though no label was generated from it. This is most useful for making
       pseudonyms for addresses which  contain  expressions  (usually  using
       other symbols):

                    eg: SYMBOL      1000
                        !=SYMBOL+1  1001

          The above  sequence  will  output  "SYMBOL+1"  for  references  to
       address $1001,  but will not output the string "SYMBOL+1"  as a label
       for that address.
    DISASSEMBLER                                                     Page: 7



          Note that block type records can be overlapped in which  case  the
       disassembler will use  the  first  defined  type  which  matches  the
       current address:

                    eg: !<1000 1FFF     <- Byte data here
                        !>0000 FFFF     <- Word data everywhere else

          In  the  above  example,  if  the  records   were   swapped,   the
       disassembler would treat ALL addresses as word data (The first record
       matches all addresses, so the second one is never processed).

          When definition file is written  (with  'W='),  any address blocks
       are output first (absolute form only), and then the symbol names,  in
       the above formats. This file could later be loaded (with 'D=').

          Generally,  you would not want to  overwrite  a  manually  created
       symbol table file  (with  "W="),  because the new file would not have
       any comments, or relative block types. When using the disassembler to
       update an existing symbol file,  it is  usually  best  to  write  the
       output to a new file,  and manually merge the required data with  the
       existing symbol table file.

          By default,  the disassembler formats byte  data  blocks  with  10
       bytes entries per source line,  and word blocks with 4  word  entries
       per source line. This formatting can be overridden for a single block
       type by using the special form:

                        !n <BlockType>...

       Where  'n'  is the maximum number of data entries that  you  wish  to
       occur on a single source line.  NOTE:  The  space  following  'n'  is
       REQUIRED!

                eg: !2 <4500 450F   <- Byte data: 4500 to 450F, 2 bytes/line
                    !1 >4510 451F   <- Word data: 4510 to 451F, 1 word/line
    DISASSEMBLER                                                     Page: 8


    4. ADDING COMMENTS

          The disassembler can be given a  file  containing  comments  (with
       'C='),  which will be inserted sequentially in the disassembly.  Each
       line from the comment file is added as a comment field  (at the  end)
       to each line  of  code  produced  by  the  disassembler.  Adding  the
       comments this way  (instead of editing  them  into  the  disassembler
       output)  is very useful,  as it allows you to re-generate the  output
       (to correct symbol errors etc.) without losing the comments.

          The following special control lines may be included in the comment
       file:

       @<address>

          Lines beginning with  '@',  followed  by  a  hexidecimal  address,
       signal the disassembler  to  wait  until  the  specified  address  is
       encountered before inserting any more comments.  This  is  useful  to
       comment various sections of the output without entering comments  for
       all previous lines.

          NOTE: The disassembler processes the comment file only once, while
       generating the listing, and will not "backup" to find addresses.  Ie:
       The '@' addresses must be in ascending order in the comment file.  If
       an  '@'  address is found which is lower that the current disassembly
       address, the disassembler treats it as a match,  and begins/continues
       inserting comments.

       #<value>

          Lines beginning with  '#',  followed by a decimal value signal the
       disassembler to skip a number of lines equal to <value> in the output
       file before inserting any more comments.  It provides a convient  way
       to skip over short sequences of uncommented lines.

       *<comment>

          Lines  beginning  with  '*'  signal  the  disassembler  that   the
       remainder of the line is a  "line"  comment,  which will be  inserted
       into the output listing  as  a  separate  line.  Multiple  '*'  lines
       occuring together in the comment file will be inserted in the listing
       as a single block.
