



















                                      UASM

                           Universal Cross Assembler

                                  Users Guide





                                  Release 2.0

                               Revised 29-Jan-01





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

                            http://www.dunfield.com


                       ?COPY.TXT 1983-2005 Dave Dunfield
                              **See COPY.TXT**



                              UASM Cross Assembler

                               TABLE OF CONTENTS


                                                                         Page

     1. INTRODUCTION                                                        1


     2. CREATING A NEW ASSEMBLER                                            2

        2.1 UAC source file format                                          2

     3. USING THE ASSEMBLER                                                 7

        3.1 Command Syntax                                                  7
        3.2 Redirecting the listing file                                    8
        3.3 Source file format                                              9
        3.4 Expressions                                                     9
        3.5 Assembler directives                                           11
        3.6 Error Messages                                                 13
        3.7 Error message summary                                          14

     4. MACRO PREPROCESSOR                                                 15

        4.1 Substitution macros                                            15
        4.2 Instruction macros                                             16
        4.3 Macro directives                                               17
        4.4 Source File Synchronization                                    20

     5. APPENDICES                                                         21

        5.1 Object file formats                                            21
        5.2 ASCII code chart                                               22
    UASM Cross Assembler                                             Page: 1


    1. INTRODUCTION

          UASM  (Universal ASseMbler)  is an assembler development  package,
       which enables you to quickly develop an assembler for  virtually  any
       8/16 bit CPU. The following files are included in this package:

          UAC.exe - Universal Assembler Compiler
          UASM_L.obj - UASM core module (little endian)
          UASM_B.obj - UASM core module (big endian)
          MAKEASM.bat - Command file to build and assembler
          *.UAC - Sample UAC source files

          MACRO.exe - Macro pre-processor
          HEXFMT.com - HEX file manipulator
          CREF.exe - Cross reference utility
          PSOURCE.com - Porting source generator
          RETAB.com - Source file (re)tabulator
          INT2XASM.com- Convert "Intel" style source to XASM style
          XASM2UNT.com- Convert XASM style source in "Intel" style

          Dunfield  Development  Systems  offers   complete   low   cost   C
       development packages  for  many  different  8  and  16  bit  embedded
       processors, as well as other related development software tools.  For
       more information, please contact:

                          Dunfield Development Systems
         115 Manion Heights Cres.   RR#2 Carp, Ontario Canada   K0A 1L0
         http://wwww.dunfield.com                     FAX: 613-256-5821

          UASM is provided on an  "as is"  basis,  with no warranty  of  any
       kind.  In no event shall the author be liable for any damages arising
       from its use or distribution.

          Throughout this document, angle braces ('<>') are used to indicate
       operands for which a value must  be  supplied  by  the  user.  Square
       braces ('[]') are used to identify operands which are optional.
    UASM Cross Assembler                                             Page: 2


    2. CREATING A NEW ASSEMBLER

       The Universal Assembler is designed to make it very easy to  generate
       a new assembler for virtually any possible  instruction  set.  To  do
       this, you would perform the following steps:

            1 - Write instruction definition in a file called: asm_name.UAC
                                EDT asm_name.UAC
            2 - Invoke the Universal Assembler Compiler to translate the
                instruction definition into an asm_name.C source program:
                                  UAC asm_name
            3 - Compile the asm_name.C program to produce asm_name.OBJ
                using the Micro-C/PC compiler:
                                CC asm_name -FMO
            3 - Link the asm_name.OBJ file with the appropriate UASM_x.OBJ
                file to create the asm_name.EXE program.
                    LC -s asm_name UASM_L <== Little-Endian
                    LC -s asm_name UASM_B <== ...Big-Endian

       NOTE:  Use "Little-Endian" for processors having a native word format
       where  the  low  byte  occurs  first  (LSB  at  lower  address),  and
       "Big-Endian" for processors having a native word format where the low
       byte occurs last (LSB at higher address).

       2.1 UAC source file format

          The Universal Assembler Compiler  (UAC)  source file  is  used  to
          inform the assembler of the  exact  translation  between  assembly
          source and binary machine language. Creating this file is the most
          demanding task in generating a new assembler, however it is fairly
          straightforward, and not difficult to master.

          This  file  should  be  given  the  name   "asm_name.UAC",   where
          "asm_name"  is  the  name  you  ultimately  want  your  executable
          assembler  (.EXE)  to have.  The .UAC extension is manditory.  The
          file can be created and edited with any editor  which  works  with
          standard ASCII text files.

          The UAC file can  be  divided  into  two  parts:  Directives,  and
          Translation definitions.

          Blank lines,  and any lines beginning with ';'  are ignored in the
          UAC file.  These can be used  to  provide  visual  formatting  and
          comments.

          It is recommended that you consult the  sample  UAC  source  files
          provided for working examples of the material discussed below.

          2.1.1 UAC directives

             All UAC directive lines begin with the '~' character:

             ~$<text> <== Define CPU name

                   The ~$ directive defines the name of  the  CPU  which  is
                shown in the assembler command help output,  and at the  top
                of each listing page.
    UASM Cross Assembler                                             Page: 3


             ~+c... <== Define extra symbol characters

                   The  ~+  directive  identifies  to  the   assembler   any
                characters which you would like to be  available  in  symbol
                names.  The characters a-z, A-Z and 0-9 are ALWAYS available
                in symbol names,  however this directive allows you  to  use
                additional characters in your assembly language symbols.

                NOTE:  Any characters which you define here can NOT be  used
                to identify instruction operand types.  In other words,  you
                should not define any additional symbol characters which can
                occur in any operands in anything but symbols.

             ~=<keyword> ... <== Define keywords

                The ~=  directive  is  used  to  identify  keywords  to  the
                assembler.  These would normally be register names or  other
                reserved  words  which  could  occur  in   the   instruction
                operands.

                Multiple keywords can be specified to each ~= directive, and
                multiple ~= directives can be used. Each keyword is assigned
                an index number beginning with 0,  and increasing by one for
                each keyword defined in order.

             ~%<lo> <hi> <== Define a keyword range

                The ~% directive allows you to specify a keyword range.  The
                <lo>  and  <hi>  values are the index  numbers  assigned  to
                lowest and highest  keyword  which  will  be  recognized  as
                belonging to this range.

                When a keyword range is matched in an  instruction  operand,
                the value returned by that  operand  is  the  keyword  index
                number for the actual keyword which  occurs  in  the  source
                file.  Keyword ranges are most often used to identify groups
                of registers which must be encoded  into  the  opcode  in  a
                binary field,  careful ordering of the keywords  and  ranges
                can often simplify this operation.

             ~<n> <C code> <== Define a code function

                This directive defines a "function"  which can be applied to
                operand values  in  the  generation  of  opcode  bytes.  The
                remainder  of  the  line  is  code  in  the  "C  programming
                language"  which will be called when this  function  <n>  is
                requested.  This code  should  always  end  with  a  "return
                <value>;"  where  <value>  is the numeric value to be passed
                back from the function.

                Multiple lines functions can be created simply by using more
                than one ~<n> with the same <n> value.  The last line with a
                given <n> value should return the value as described above.

                The following predefined variables are available for use  in
                the C code functions. All are unsigned:
    UASM Cross Assembler                                             Page: 4


                    x       - Input value to the function
                    Address - PC address of beginning of instruction.
                    Length  - Length of opcode (to current position)
                    Fn      - Function number (0-255)

                An error may be  flagged  by  calling  "error(error_number)"
                with one of the following values:

                    1-  "Unknown instruction"
                    2-  "Undefined symbol"
                    3-  "Invalid argument format"
                    4-  "Invalid addressing mode"
                    5-  "Expression syntax error"
                    6-  "Out or range"
                    7-  "Improperly delimited string"

             ~. <C statements> <== Lead in for function

                The ~. directive is used to define any lead-in code required
                in the ~<n>  functions.  It's main purpose is to  allow  the
                declaration of additional temporary  variables,  however  it
                can be used to insert any C code which must be  executed  at
                the beginning of ALL ~<n> functions.

                The ~.  directive must occur in the UAC source  file  BEFORE
                any ~<n> directives.

          2.1.2 UAC Translation Definitions

             The  "Translation Definitions"  are used  to  describe  to  the
             assembler exactly how each  possible  instruction  and  operand
             combination is to be translated into binary opcode values.

             The general form of a translation definition is:

                        INST <operands> |<opcode bytes>

             INST is the name of the instruction memonic.

             <operands> are any operands which occur to the instruction. The
             string given will be pattern-matched  against  the  operand  to
             identify the instruction/operand combination occuring.

             The following special characters can be used within an  operand
             specification:

                $           <== Any expression value
                %n          <== Keyword range
                <alnum>     <== Single keyword

             Any other  characters  occuring  in  the  operand  string  must
             exactly  match  the  source  instruction  operand.  Note   that
             characters which are valid  symbol  names  can  occur  only  in
             identified keywords,  and characters  which  occur  in  numeric
             expressions are not allowed within the operand specification.
    UASM Cross Assembler                                             Page: 5


             The following characters are reserved by the assembler:

                *   - Comment when start of line
                    + Multiplication operator
                    + Current PC address
                +   - Addition
                -   - Subtraction
                /   - Division
                \   - Modulus (remainder after division)
                &   - Bitwise AND
                |   - Bitwise OR
                ^   - Bitwise XOR
                >   - Shift right
                <   - Shift left
                =   - Swap High/Low bytes
                ~   - Unary compliment operator
                $   - Indicates HEX number (nH also accepted).
                    + Current PC address
                @   - Indicates OCTAL number (nO and nQ also excepted)
                %   - Indicates BINARY number (nB also accepted)
                ,   - Separates elements in DB/DW/DRW/FCB/FDB/RDB
                ;   - Indicates beginning of line comment comment
                :   - Optional label delimiter
                '   - Indicates beginning/ending of character value
                ()  - Indicates a nested sub-expression
                0-9 - Decimal number (nT also accepted)
                    + Allowed as non-first character in any symbol/keyword.
                A-Z - Allowed as any character of any symbol/keyword.

             <opcode bytes>  are the actual  hex  values  which  are  to  be
             written to the output file.  The following  special  characters
             can be used:

                +       = OR value into previous byte (otherwise new byte)
                >       = Specify word output (otherwise byte output)
                =       = Specify high byte or reversed word
                [n]     = Load operand 'n'
                [n:f]   = Load operand 'n', apply function 'f'
                nn      = OR with value (hex)

             When processing the opcode byte definitions, the assembler will
             work in this order:

                - Assume 0 if no operand encoded
                - Load operand (if specified)
                - Call function (if specified)
                - OR with value (if specified)
                - Reverse/High (if specified)
                - Write/Or byte/word
    UASM Cross Assembler                                             Page: 6


             Here are some examples of opcode byte encodings:

                12      = Simple Hex byte 12
                [0]     = Value of operand 0
                [1:2]   = Value of operand 1, apply function 2
                [0]34   = Value of operand 0, OR with 34
                [1:2]34 = Value of operand 1, function 2, OR with 34
                =[2]    = Value of operand 2, high byte only
                >1234   = Word value 1234
                >=[1]   = Word value of operand1, reversed
                +[0:3]  = Value of operand 0, Apply function 3,
                          OR into previous byte

             Operand values are assigned  to  each  of  the  '$',  '%n'  and
             <alnum>  specifiers in order.  Operand  0  is  the  first  such
             occurance in the operand field etc.

             The value of a  '$'  (expression)  operand is the actual  value
             determined by evaluating the expression.

             The value of a  '%n'  or  <alnum>  operand is the keyword index
             number assigned to the actual keyword which was  found  in  the
             operand field.
    UASM Cross Assembler                                             Page: 7


    3. USING THE ASSEMBLER

          The UASM cross assembler read a source file (.ASM),  and produce a
       code file (.HEX) containing either MOTOROLA or INTEL format ASCII-HEX
       download  records.  A  optional  listing  file  (.LST)  may  also  be
       produced.

       3.1 Command Syntax

             An assembler is invoked by entering its  name  at  the  command
          prompt, in the following format:

                          ASM... <filename> [options]

             The <filename> operand is the name of the file to be assembled,
          it is assumed to have the extension ".ASM" if none is supplied.

             Unless otherwise specified,  the code produced by the assembler
          is written to a file  with  the  name  '<filename>.HEX',  and  the
          listing is written to a file with the name '<filename>.LST'.

          3.1.1 Command line options

                The following options may be specified on the command  line,
             following the <filename> operand:

             -C - [C]ase sensitive

                     Causes the assembler  to  make  a  distinction  between
                  upper and lower case characters in symbol names.  If  this
                  option  is  not  used,  the  assembler  will  ignore  case
                  differences,  and assume that the symbols  are  the  same.
                  NOTE: When using this option,  you must enter any register
                  names in UPPER case.

             C=<filename> - Specify [C]ode file

                     This option allows you to specify the file to which the
                  output code is written.  If no extension  is  supplied  as
                  part of <filename>, it defaults to ".HEX".

             -F - Generate [F]ull listing

                     Causes the assembler to output a full source listing to
                  the '.LST' file.  By default, only lines containing errors
                  are written to the listing file.

             -I - Generate [I]ntel format HEX file

                     Causes the assembler to output the code to  the  '.HEX'
                  file in INTEL hex format.  By default the code is  written
                  to the file in MOTOROLA hex format.
    UASM Cross Assembler                                             Page: 8


             L=<filename> - Specify [L]isting file

                     This option allows you to specify the file to which the
                  listing is written. If no extension is supplied as part of
                  <filename>, it defaults to ".LST".

             P=<length> - Set page length

                     This option specifies the number of lines which will be
                  printed on each page. The default number of lines per page
                  is 60.

             -Q - [Q]uiet mode

                     Causes  the  assembler  to  be  quiet,  inhibiting  the
                  display of the progress messages.

             -S - Generate [S]ymbol table

                     Causes the assembler to sort  and  display  the  symbol
                  table at the end of the  listing  file.  By  default,  the
                  symbol table is not displayed.

             -T - Output to [T]erminal

                     Causes the assembler  to  output  the  listing  to  the
                  terminal, (via stdout) instead of the usual '.LST' file.

             W=<width> - Set page width

                     This option control the number of columns which will be
                  used for the printing of page titles and the symbol  table
                  listing. Default page width is 80 columns.

       3.2 Redirecting the listing file

             When the listing file is directed to the terminal with the '-t'
          option on the command line,  it is displayed through the  standard
          output file,  allowing it to be redirected to a printer  etc.  via
          the shell  '>'  redirection operator  (EG:  ASMxx filename  -f  -t
          >LPT1:).  The progress messages  ('First pass...' etc)  are output
          through stderr,  and will therefore not  be  redirected  with  the
          listing.  NOTE that the listing may be more efficently re-directed
          with the 'L=' option.
    UASM Cross Assembler                                             Page: 9


       3.3 Source file format

             The assembly source input lines are in the following format:

              '<label>[:]  <instruction>  <operands>  [;comment]'

             Labels must begin in column one, and must be separated from the
          instruction field by at least one blank or tab  character.  Labels
          may be followed by a ':' if desired,  however this is not required
          by the assembler.

             The instruction field must be indented by at least one space or
          tab (ie: the instruction name cannot begin in column 1).

             If the an instruction or directive requires operands,  then the
          operand field is required,  and is separated from the  instruction
          by at least one blank or tab.

             The optional comment field is delimited from the operand  field
          by a semicolon  (';').  This field is for  documentation  purposes
          only, and is ignored by the assembler.

             Any lines beginning with a '*'  or ';'  character in column one
          are considered to be  comments,  and  are  not  processed  by  the
          assembler.

       3.4 Expressions

             When an 8 or 16 bit value is  required  as  an  operand  to  an
          assembler directive or an instruction,  either a simple value,  or
          an expression consisting of simple values  and  operators  may  be
          used.

             All expressions are evaluated using  16  bit  values.  When  an
          expression is evaluated in an instruction requiring an  eight  bit
          value,  the lower eight bits are used.  Expressions are  evaluated
          from left to right,  as  each  operator  is  encountered,  without
          precedence.  Precedence can be forced with the  use  of  brackets.
          Spaces or tabs are not allowed within an expression,  unless  they
          are contained within a character string.
    UASM Cross Assembler                                             Page: 10


             The following operators may be used in an expression:

       3.4.1 Unary (one operand) operators:

               -   - Negation, returns the negative of the next value.
               ~   - Complement, returns one's complement of the value.
               =   - Swaps the high and low bytes of the next value.

       3.4.2 Binary (two operand) operators:

               +   - Addition.
               -   - Subtraction.
               *   - Multiplication.
               /   - Division (unsigned).
               \   - Modulus, returns remainder after division.
               &   - Bitwise AND.
               |   - Bitwise OR.
               ^   - Bitwise EXCLUSIVE OR.
               <   - Shift left
               >   - Shift right


       3.4.3 Values in expressions

               The following forms of simple values may be used.

               nnn     - Decimal number, eg: 21
               nnnD    - "" "": 21d
               nnnT    - "" "": 21t
               $nnn    - Hexidecimal number, eg: $15
               nnnH    - "" "": 15h  (Must begin with 0-9, eg: 0FFh)
               %nnn    - Binary number, eg: %10101
               nnnB    - "" "": 10101b
               @nnn    - Octal number, eg: @177
               nnnO    - "" "": 177o
               nnnQ    - "" "": 177q
               'cc'    - ASCII characters, eg: 'A'
               <label> - Value of a label from symbol table.
               *       - Value of current program counter.
               $       - "" ""
    UASM Cross Assembler                                             Page: 11


       3.5 Assembler directives

             The following directives (pseudo instructions) are supported by
          the assembler:

          <label> EQU <expression>

             This directive sets the label on it's line to have the value of
          the operand expression.

          ORG <expression>

             This directive sets the internal program counter to  the  value
          of the operand expression,  such  that  subsequent  code  will  be
          generated at that address.

          TITLE <string value>

             This directive sets the title of the program to the text on the
          remainder of the line.  The title is displayed at the top of  each
          page in the listing, and by default is set to the name of the file
          being assembled.  Lines containing this directive will not  appear
          in the listing.

          PAGE

             This directive forces  a  page  eject  in  the  listing.  Lines
          containing this directive will not appear in the listing.

          SPACE

             This directive causes a blank line to appear  in  the  listing.
          Lines containing this directive will not appear in the listing.

          NOLIST

             This directive turns off the  source  listing,  preventing  any
          further lines from being displayed,  until  a  LIST  directive  in
          encountered.  NOLIST and LIST may be nested,  listing  is  resumed
          only when all levels of NOLIST have  been  turned  off.  Lines  in
          which errors occur are listed regardless of the NOLIST directive.

          LIST

             Re-enables output listing, following a NOLIST directive.

          LINE <expression>

             Re-sets the assemblers internal line counter to  the  specified
          value.  Lines containing this directive will  not  appear  in  the
          listing.

          END

             Causes  the  assembler  to  stop  processing,  and  ignore  the
          remainder of the source file.  Note that an END directive  is  NOT
          required.
    UASM Cross Assembler                                             Page: 12


          DB <expr1>[,<expr2>,<expr3>,...]
          FCB <expr1>[,<expr2>,<expr3>,...]

             These directives code the values  of  the  operand  expressions
          into memory as single byte constants.

          DW <expr1>[,<expr2>,<expr3>,...]
          FDB <expr1>[,<expr2>,<expr3>,...]

             These directives code the values  of  the  operand  expressions
          into memory as double byte constants.

          DRW <expr1>[,<expr2>,<expr3>,...]
          RDB <expr1>[,<expr2>,<expr2>,...]

             These directives are similar to DW/FDB,  except that  the  high
          and low bytes of the coded values are exchanged.

          DS <expression>
          RMB <expression>

             These directives reserve a number of bytes of memory  equal  to
          the value of the operand expression.  The contents of the reserved
          storage is undefined.

          STR 'text string'
          FCC 'text string'

             These directive code the  string  into  memory  as  ASCII  byte
          values.  The string may be delimited by any character which is not
          part of the string text.

          STRH 'text string'
          FCCH 'text string'

             These directives perform exactly  as  the  STR/FCC  directives,
          except that the high bit is set  on  the  last  character  in  the
          string.

          STRZ 'text string'
          FCCZ 'text string'

             These directives perform exactly  as  the  STR/FCC  directives,
          except that the string has a zero byte ($00) appended.
    UASM Cross Assembler                                             Page: 13


       3.6 Error Messages

             When the assembler detects an error  in  the  source  code,  it
          displays a message indicating a possible cause of  the  error,  in
          the source listing on the  line  immediately  following  the  line
          containing the error.  Errors which are encountered in  the  first
          pass,  are displayed at the top of the  listing,  along  with  the
          number of the line in which the error was detected.

             Forward  references  in  any  of  the  (EQU,  ORG,  or  RMB/DS)
          directives are not allowed,  and will cause an  'Undefined symbol'
          error in the first pass only, displayed at the top of the listing.
    UASM Cross Assembler                                             Page: 14


       3.7 Error message summary

          3.7.1 Duplicate symbol: <symbol name>

             The indicated symbol is defined  more  that  once  within  this
             assembly.

          3.7.2 Symbol table overflow.

             There are too many symbols  (labels)  in the program,  and  the
             assemblers symbol table has become full.

          3.7.3 Unknown instruction

             The instruction field on the indicated line does not contain  a
             valid instruction or assembler directive.

          3.7.4 Undefined symbol

             A symbol referenced  in  the  indicated  line  is  not  defined
             anywhere within this assembly, and has no value.

          3.7.5 Out of range

             The operand is not the range of values which can be  used  with
             the instruction.  eg:  A short branch to an  address  which  is
             farther than +127 or -128 bytes from the program counter.

          3.7.6 Invalid addressing mode

             The addressing mode indicated  by  the  operand  field  of  the
             indicated line does not apply to the instruction on that line.

          3.7.7 Expression syntax error

             The expression on the indicated line contains a character which
             is not recognized as a valid operator.

          3.7.8 Invalid argument format

             The indicated line has an operand which is not in proper format
             for the instruction.

          3.7.9 Improperly delimited string

             A character string constant on the indicated line does not have
             a proper closing delimiter.  This is normally the single  quote
             character, but may be another character in conjunction with the
             FCC, FCCH, FCCZ, STR, STRH or STRZ directives.
    UASM Cross Assembler                                             Page: 15


    4. MACRO PREPROCESSOR

          MACRO is an assembly  source  code  pre-processor  which  provides
       macro substitution and conditional assembly facilities at the  source
       code level to virtually any assembler or cross assembler.

          MACRO reads the raw  assembler  source  from  one  or  more  files
       specified as its arguments,  and the processed assembler source  file
       is written to standard output where it  can  be  re-directed  into  a
       temporary file for later assembly.  All files specified as  arguments
       are  effectivly  concatinated  into  the  output  file  as  they  are
       processed,  providing a convenient way of  maintaining  large  single
       source programs as more managable separate files.

          MACRO provides two types of macro definitions,  substitution,  and
       instruction.

       4.1 Substitution macros

             Substitution macros may be used  anywhere  in  any  non-comment
          line of the source file  (lines not beginning with '*'),  and when
          encountered,  are simply replaced by the  text  specified  in  the
          macro definition.

             Substitution macro's are defined using the 'SET' directive.  If
          the macro definition text contains spaces,  tabs,  or  commas,  it
          must be enclosed in double quote's.

             The following are examples of substitution macro definitions:

             sub1 set this_gets_substituted
             sub2 set "this gets substituted"

             Substitution macros are only recognized of they are  surrounded
          by non-alphanumeric characters.  This prevents substitutions  from
          occuring within other words which may contain the pattern. It does
          however require the restriction that the macro names contain  only
          alphanumeric characters.

          4.1.1 Command line substitutions

                Substitution macros may also be defined on the command  line
             with arguments of the form "<symbol>=<string>".

          eg: macro source_file1 source_file2 mode=debug >output_file
    UASM Cross Assembler                                             Page: 16


       4.2 Instruction macros

             Instruction macros may only be used in the instruction field of
          the source file, and when encountered, are replaced by one or more
          lines of assembly source code.

             Instruction macros may be passed operands in the operand  field
          of the assembly source  code.  If  multiple  operands  are  to  be
          passed, they should be separated from one another by commas.  If a
          single operand must contain spaces, tabs, or commas,  it should be
          enclosed in double quotes.

          4.2.1 Backslash commands

                The backslash character  '\'  has special meaning within  an
             instruction macro definition as follows:

        \n  - Substitute the <n>'th parameter from  the  macro  invocation
              line. <n> may range from zero to  nine,  parameter  zero  is
              considered to be the LABEL from that line, actual parameters
              from the operand field begin with parameter one.

        \#  - Substitute the number of parameters passed.

        \$  - Substitute a unique number which the total number  of  macro
              invocations to occur in this assembly so far. This is  often
              used to create unique labels within the macro.

        \.  - Substitute the current source file line number.

        \@n - Substitute a portion of the current date based on the digit
              'n', as follows:

              \@1 - Day of month, 1 or 2 digits.
              \@2 - Day of month, 2 digits.
              \@3 - Month of year, 2 digits.
              \@4 - Month of year in string form.
              \@5 - Month of year in three character string form.
              \@6 - Current year, 2 digits.
              \@7 - Current hour, 2 digits.
              \@8 - Current minite, 2 digits.
              \@9 - Current second, 2 digits.

        NOTE: The time is recorded when MACRO is first invoked.

        \\  - Place a backslash character in the macro definition.

                Instruction macros are defined with the MACRO directive, and
             are ended with the ENDMAC directive.
    UASM Cross Assembler                                             Page: 17


          4.2.2 Example instruction macro

                The following is an example  of  a  instruction  type  macro
             using 6809 assembly language:

            * MACRO TO PRINT A CHARACTER STRING
            PRINT   MACRO
            \0      PSHS    A,X         SAVE REGISTERS
                    LDX     #LAB2\$     STRING TO PRINT
             LAB1\$ LDA     ,X+         GET CHAR FROM STRING
                    BEQ     LAB3\$      END, QUIT
                    JSR     PRINTCHR    DISPLAY THE CHARACTER
                    BRA     LAB1\$      GO BACK FOR NEXT
             LAB2\$ FCCZ    "\1"        STRING TO PRINT
             LAB3\$ PULS    A,X         RESTORE REGISTERS
                    ENDMAC

       4.3 Macro directives

             MACRO suports the following directives,  which may be placed in
          the instruction field of an assembler source file.  Note that only
          substitution type macros may be used  as  values  in  operands  to
          MACRO directives,  as MACRO has no  knowlege  of  the  labels  and
          symbols used by the assembler.

             <name> SET <string>

                The SET defines the substitution type macro  with  the  name
             specified by  <name>  to have the text specified  by  <string>.
             Double quotes may be used  if  <string>  is  to  contain  tabs,
             spaces,  or commas.  If the macro being defined already exists,
             it is re-defined with the new value.  <name>  should  begin  in
             column one.

             <name> ESET <format>,<expression>

                The ESET directive sets a symbol to the numeric value of  an
             expression,  as processed through a format string.  The content
             of the format string is copied to the symbol,  with  the  value
             substituted where one of these special sequences is found:

                %u      - Unsigned value of expression
                %d      - Signed value of expression
                %x      - Hexidecimal value of expression
                %o      - Octal value of expression
                %b      - Binary value of expression
                %c      - ASCII character value of expression
                %%      - A '%' sign

                A width value may be specified  between  the  '%',  and  the
             output type denoted above,  in which case the  number  will  be
             output right justfied in a field  padded  with  spaces  to  the
             defined width.  If the number contains a leading '0', the field
             will be padded with '0's.  If the number if negative, the field
             will be left justified.
    UASM Cross Assembler                                             Page: 18


            Examples:
                A SET 10
                B SET 1
                C ESET %x,A+B           ; 'B'  (11 in HEX)
                C ESET %3u,A+B          ; ' 11'
                C ESET %03u,A+B         ; '011'
                C ESET %-3u,A+B         ; '11 '

             <name> MACRO

                The MACRO directive begins the definition of  a  instruction
             type macro.  All subsequent lines up to a ENDMAC directive  are
             included in the macro definition.  These lines are not  written
             to the output file.

             ENDMAC

                This  directive  terminates  an   instruction   type   macro
             definition.

             IF <expression>

                The IF directive causes MACRO  to  process  and  output  all
             subsequent lines up to an ELSE of ENDIF directive,  only of the
             result of the expression is non-zero.

             IFEQ <string>,<string>

                The IFEQ directive causes MACRO to process  and  output  all
             subsequent lines up to an ELSE or ENDIF directive,  only if the
             two argument strings match.

             IFNE <string>,<string>

                The IFNE directive causes MACRO to process  and  output  all
             subsequent lines up to an ELSE or ENDIF directive only  if  the
             two argument strings do not match.

             ELSE

                The ELSE directive causes MACRO to process  and  output  all
             subsequent lines up to an ENDIF directive only of the preceding
             IFEQ or IFNE directive failed.

             ENDIF

                This directive marks the end of  a  section  of  conditional
             assembly statements following a IFEQ, IFNE, or ELSE directive.

             INCLUDE "<filename>"

                The contents of the  specified  file  are  included  in  the
             output file at the point where the  INCLUDE  directive  occurs.
             Macro processing is performed on the included file.
    UASM Cross Assembler                                             Page: 19


             ABORT "<text>"

                Causes MACRO  to  terminate,  displaying  an  error  message
             containing the specified text.

             PREFIX <char>

                Sets a prefix character which must be applied to  any  MACRO
             directive in order  for  it  to  be  recognized.  For  example:
             "PREFIX %"  causes MACRO to only recognize it's directives when
             '%' is prepended. (ie: "SET" becomes "%SET").  This can be used
             to  avoid  conflicts  with  processors  instructions  in   some
             assemblers. Also note that the prefix can be set on the command
             line with a "-P<char>" syntax.

                   eg: macro source_file(s) -P% >output_file

          4.3.1 Expressions

                The  numeric  expressions  accepted  for  the  IF  and  ESET
             directives consist of values and operators.  The values may  be
             of any of these forms:

                n, nT, nD   - Decimal number
                $n, nH      - Hexidecimal number
                @n, nO, nQ  - Octal number
                %n, nB      - Binary number
                'cc'        - ASCII character(s)

             The following operators are supported:

                +   - Addition
                -   - Subtraction and unary negation
                *   - Multiplication
                /   - Division
                %   - Modulus (remainder)
                &   - Bitwise AND
                &&  - Logical AND
                |   - Bitwise OR
                ||  - Logocal OR
                ^   - Bitwise exclusive OR
                >   - Test for greater than (True=1, False=0)
                >=  - Test for greater than or equal to
                >>  - Shift right
                <   - Test for less than
                <=  - Test for less than or equal to
                <<  - Shift left 
                ==  - Test for equal to
                !=  - Test for NOT equal to
                !   - Unary logical NOT
                ~   - Unary bitwise compliment

                There are no precedence rules. Operations are performed left
             to right,  in the order that they they are encountered  in  the
             expression.  Brackets () can be used to force a different order
             of evaluation.
    UASM Cross Assembler                                             Page: 20


       4.4 Source File Synchronization

             MACRO removes it's own commands,  and adds macro expansions  to
          the source file as it is processed. A result of this is that lines
          in the output file will usually NOT have the same  number  as  the
          corresponding line in the input file.  This can be a problem  when
          tracking down error messages produced by the assembler,  since the
          line numbers displayed do not correspond  to  the  original  input
          file.  To overcome this problem when  using  the  DDS  UASM  cross
          assemblers, MACRO has a command line -L option, which causes it to
          generate  "LINE"  directives whenever it determines that the input
          and output line numbers could be out  of  sync.  These  directives
          will reset the assemblers line counter to match the lines  of  the
          original source file.
    UASM Cross Assembler                                             Page: 21


    5. APPENDICES

       5.1 Object file formats

             Object files are produced by the assemblers in  either  of  two
          standard formats,  both of which  represent  the  binary  data  as
          two-digit printable ASCII hex numbers.  The exact contents of  the
          two standard format object files is as follows:

    5.1.1 Motorola hex format

    Data Record: 'Stnnaaaadddddddddddddddddddddddddddddddd...cc'
          Where:  S = 'S', indicates start of data record
                  t = Record type, '1'=data, '9'=end of file.
                  n = Count of number of bytes in record.   (in ASCII/HEX)
                  a = Load address of data record.          (in ASCII/HEX)
                  d = Actual data bytes in record.          (in ASCII/HEX)
                  c = Checksum of count, address, and data. (in ASCII/HEX)

                Note1: Checksum is computed as one's complement of eight
                       bit sum of all values fron 'nn' to end of data.

                Note2: Count 'nn' is three greater then the number of data
                       bytes in the record.

    5.1.2 Intel hex format

    Data Record: ':nnaaaattdddddddddddddddddddddddddddddd...cc'
          Where:  : = Indicates start of data record
                  n = Count of number of bytes in record.   (in ASCII/HEX)
                  a = Load address of data record.          (in ASCII/HEX)
                  t = Record type                (00=Data, 01=End of file)
                  d = Actual data bytes in record           (in ASCII/HEX)
                  c = Checksum of count, address, and data. (in ASCII/HEX)

                Note1: Checksum is computed as two's complement of eight
                       bit sum of all values fron 'nn' to end of data.

                Note2: End of file record contains count of 00.
    UASM Cross Assembler                                             Page: 22


    5.2 ASCII code chart





                             Most Significant Figure

              HEX||  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |
              ===++=====+=====+=====+=====+=====+=====+=====+=====+
               0 || NUL | DLE |     |  0  |  @  |  P  |  `  |  p  |
              ---++-----+-----+-----+-----+-----+-----+-----+-----+
               1 || SOH | DC1 |  !  |  1  |  A  |  Q  |  a  |  q  |
          L   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          e    2 || STX | DC2 |  "  |  2  |  B  |  R  |  b  |  r  |
          a   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          s    3 || ETX | DC3 |  #  |  3  |  C  |  S  |  c  |  s  |
          t   ---++-----+-----+-----+-----+-----+-----+-----+-----+
               4 || EOT | DC4 |  $  |  4  |  D  |  T  |  d  |  t  |
          S   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          i    5 || ENQ | NAK |  %  |  5  |  E  |  U  |  e  |  u  |
          g   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          n    6 || ACK | SYN |  &  |  6  |  F  |  V  |  f  |  v  |
          i   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          f    7 || BEL | ETB |  '  |  7  |  G  |  W  |  g  |  w  |
          i   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          c    8 || BS  | CAN |  (  |  8  |  H  |  X  |  h  |  x  |
          a   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          n    9 || HT  | EM  |  )  |  9  |  I  |  Y  |  i  |  y  |
          t   ---++-----+-----+-----+-----+-----+-----+-----+-----+
               A || LF  | SUB |  *  |  :  |  J  |  Z  |  j  |  z  |
          F   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          i    B || VT  | ESC |  +  |  ;  |  K  |  [  |  k  |  {  |
          g   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          u    C || FF  | FS  |  ,  |  <  |  L  |  \  |  l  |  |  |
          r   ---++-----+-----+-----+-----+-----+-----+-----+-----+
          e    D || CR  | GS  |  -  |  =  |  M  |  ]  |  m  |  }  |
              ---++-----+-----+-----+-----+-----+-----+-----+-----+
               E || SO  | RS  |  .  |  >  |  N  |  ^  |  n  |  ~  |
              ---++-----+-----+-----+-----+-----+-----+-----+-----+
               F || SI  | US  |  /  |  ?  |  O  |  _  |  o  | DEL |
              ---++-----+-----+-----+-----+-----+-----+-----+-----+
