Introduction to XASM09.COM
Running the Cross-Assembler
Source file syntax
Pseudo-Operations
Errors
Listing format
Error messages
Object file format
:XASM0¹  ió  á  cross-assembleò designeä tï ruî oî  anù  CP/Í  8° �
machine®     Iô    generateó   codå   foò   thå   Motorolá   680¹ �
microprocessor¬  iô  acceptó  standarä  Motorolá  mnemonicó   anä �
syntax.

XASM09 accepts its input from a CP/M text file,  and generates as 
output  an  object  code  file,   an  assembly  listing,  and  an 
alphabetized listing of all symbols defined in the assembly.  The 
object  file may be in Intel HEX format or Motorola S1 format  or 
may be omitted altogether, at the user's discretion. The listings 
are  normally  sent  to  the system's LIST  device,  but  may  be 
directed to the console or to a disk file.


:Invoking the 6809 cross-assembler.

     XASM09 {d:}filename{.ext} {d:} {switches}

Where  the  d:'s  are optional  drive  specifiers,  the  filename
extension is optional and if omitted defaults to .ASM. The second
drive  name  specifies  the destination of any  output  from  the
cross-assembler if omitted the output files will be placed on the
default  drive.  The  switches are (optional)  single  characters
which control the output of the assmbler, as described below.
XASM09 Switches

The switches following the filename, if supplied, control various
options as follows:

C    Send listing, if any,  to console instead of LST:
D    Send listing, if any,  to disk file with same name as source
     file but with an extension of `.PRN'.
K    Generate object code in Motorola S1 format rather than Intel
     heø  format¬  thå  objecô  filå  thaô ió  generateä  haó  aî �
     extension of `.MIK'.
L    Listing only; i.e. no object file.
O    Object only; equivalent to XY
X    No assembly listing.
Y    No symbol-table listing

Anù  combinatioî oæ thå switcheó maù bå useä tï achivå á  desireä �
output.
Clarification
-------------
Whilå thió maù bå misseä oî á cursorù readinç oæ thå manual¬  thå �
defaulô destinatioî foò thå assemblù listinç ió thå PRINTER®   Iæ �
thå printeò ió noô ready¬ oò nï printeò ió present¬ thå assembleò �
wilì appeaò tï "hanç up"®   Notå thaô lineó containinç erroró arå �
alwayó  listed¬  eveî  iæ  thå  "O¢ oò  "X¢  switcheó  havå  beeî �
specified.

Listing output can be diverted to the console or to a PRN file by
using the "C" and "D" switches, respectively, in the command line.

:Syntax of Assembler Source Files

Statements

Source  files  consist of a sequence of statements of one of  the
forms:

     {label:}  operator  {arguments}    {;comment}

     symbol    operator  {arguments}    {;comment}

     {;comment}

If  a  label or a leading symbol is present,  it  must  begin  in
column  1.  Labels must be followed by a colon.  Blank lines  are
treated as comments.  Elements of a statement may be separated by
blanks or tabs.
Symbols

Symbols may be up to 8 characters in length,  and may include any
of the following characters:

    A..Z      0..9      $    .

The first character of a symbol must be a letter or a period.
Numeric Constants

Numeric  constants  consist of a sequence of  digits,  optionally
preceeded or followed by a radix specifier.  The first  character
must  be  either a leading radix specifier or  a  decimal  number
(0..9). The default radix is ten. For compatibility with existing
assemblers,  other  bases may be denoted by either a leading or a
trailing specifier. The radix specifiers are:

     % (binary)     @ (octal)      $ (hex)

The trailing specifiers are:

     B (binary)     Q (octal)      H (hex)
Character Constants

Character  constants  may  be used whenever a  numeric  value  is
allowed.  A character constant consists of one or two  characters
enclosed  in single or double quotes (' or ").  The single  quote
may be used as a character between double quotes, and vice-versa.

Thus, the following are equivalent:

          'A'  "A"  and  41H

          'AB' "AB" and  4142H

Location-Counter Reference

The  character "$" may be usd as an element in  expressions.  Its
value  is the value of the location counter at the  beginning  of
the current statement.
Expressions

Arithmetic   expressions   are  composed  of   symbols,   numeric
constants,  character  constants,  and operators.  All  operators
execpt +, -, *, and / must be separated from thier operands by at
least one space.  Symbols which are operators are  reserved,  and
may not be redefined as user symbols.
Arithmetic Operators

These  treat  their operands as 16-bit unsigned  quantities,  and
return 16-bit results. No overflow checking is performed.

+ and -        Sum and Difference. Operands and results may be
               thought of  as  unsigned or  as twos-complement
               quantities.

unary +        +x is defined as 0+x

unary -        -x is defined as 0-x

* /            Product and Quotient (unsigned)

MOD            Remainder;
               x MOD y gives the remainder of x/y
Shift Operators

SHL            Binary left shift.  x SHL y yields x shifted left
               y places (ie. x multiplied by 2**y).

SHR            Binary right shift,  logical.  x  SHR  y yields x
               shifted right y places (ie. x multiplied by 2**y).

The direction of shift is reversed if the argument is negative.

Byte-Extraction Operators

HIGH           Returns the value of the most significant byte  of
               its argument.

LOW            Returns the value of the least significant byte of
               its argument.

These are unary operators,  taking an argument on the right.  For
example:  HIGH 1122H is 11H, and LOW 1122H is 22H.
Boolean Operators

NOT            Unary logical negation.  Complements all the  bits
               in its argument.

AND            Logical product;   ie.  each bit of the result  is
               obtained by ANDing together the corresponding  bit
               in the arguments.

OR             Logical sum.

XOR            Exclusive-OR.
These are all bitwise operators;  that is,  the same operation is
performed  on each operand bit position,  with no carry from  one
bit position to the next.

For example:   NOT 0 is 0FFFFH
               101B AND 010B is  
               101B OR  010B is 111B
               101B XOR 010B is 111B
               101B XOR 100B is 001B
Relational Operators

These  perform  unsigned  16-bit comparison  of  their  operands,
returning 1 for TRUE and 0 for FALSE.

For  comparison  x R y,  where R is a  relational  operator,  the
results are as follows:

EQ        TRUE iff x and y are equal
NE        TRUE iff x and y are not equal
LE        TRUE iff x is less than or equal to y
LT        TRUE iff x is strictly less than y
GE        TRUE iff x is greater than or equal to y
GT        TRUE iff x is strictly greater than y
Evaluation of Expressions

Parentheses  may  be used to specify the order of  evaluation  of
subexpressions.  In  the  absence of parentheses,  this order  is
determined  by operator precedence;  higher-precedence  operators
are  evaluated  first.  In  the  case  of  operators  with  equal
precedence, evaluation proceeds from left to right. The operators
are lited below in groups according to precedence.  Operators  in
the same horizontal group have the same precedence:

     unary +, unary -                   (Highest precedence)
     HIGH  LOW
     * / MOD SHR SHL
     + -
     EQ NE LT LE GT GE
     NOT
     AND
     OR XOR                             (Lowest precedence)
:Pseudo-Operations

Storage Definition

DB   arg{,arg...}

     Define  bytes.  Each  arg may be either an expression  or  a 
     string. Expressions must evaluate to 8-bit values (high byte 
     either  0  or 255).  Strings may be delimited by  single  or 
     double quotes, as for character constants.
          Foò  eacè  expression¬   á  singlå bytå oæ  storagå  ió  �
     reserved¬  initializeä  tï thå lo÷ bytå oæ thå  expression'ó �
     value®  Foò eacè  string¬  thå  characteró oæ thå strinç arå  �
     storeä  iî sequentiaì reserveä bytes.
     If a compound expression beginning with a character constant
     is  used in a DB,  then the expression must be  enclosed  in 
     parentheses  to  keep it from being incorrectly parsed as  a 
     string. For example,

          DB ('A'+1)     will give the expected result, while

          DB 'A'+1       would be in error.

DW   expression{,expression}

     Each expression reserves one word (2 bytes),  initialized to 
     the  value of the expression.  The value is placed in memory 
     with the high-order byte first.

DS   expression

     Reserves  n bytes,  where n is the value of the  expression. 
     The bytes are not initialized.
ORG and END

ORG expression

     Set  program  origin.  This should precede the  first  code-
     generating statement in the souce file.  It sets the program 
     counter initial value to the value of the  expression,  thus 
     setting  the location of code which follows.  Additional ORG 
     statements which will load at different locations.

END {expression}

     The  last  statement  of  the source file  must  be  an  END 
     statement.  An  optional  argument is allowed;  if  this  is 
     supplied,  its value becomes the start address specified  in 
     the last record of the HEX object file.
Symbol Definition

EQU and SET

     These take the form:

          symbol    EQU  expression
          symbol    SET  expression

     They  cause the symbol to be defined and given the value  of 
     the  argument expresson.  Symbols defined with EQU serve  as 
     symbolic  constants,  and may not have their values changed. 
     Symbols  defined with SET are treated  as  variables;  their 
     values may be changed by additional SET's
Conditional Assembly

IF, ELSE, and ENDIF

The construct

     IF expression
     statement
     .
     .
     .
     ENDIF

causes  the  first sequence of statements to be processed if  the 
expression  is  TRUE (non-zero),  and the second sequence  to  be 
processed otherwise.

Conditionals  may be nested to a depth of 10.  The value  of  the 
expression if the IF statement must be known in Pass 1.
Listing Control

PAGE {expression}

     If  the argument is omitted,  then this causes an  immediate 
     page eject (ie.  a skip to the top of the next page).  If an 
     argument  is supplied occurs only if there are less  than  n 
     lines remaining on the current page.

WIDTH expression

     Sets the assumed width of the listing page. The value of the 
     argument may be between 32 and 132, and defaults to 132.

PGLEN expression

     Sets  the number of lines which will be printed on each page 
     of  the listing.  Note that the page heading takes up  7  of 
     these lines.  The value of the argument may be between 8 and 
     255, and defaults to 58.
TITLE dtextd

     Cause  the specified text to become the listing page  title, 
     beginning with the next page header printed. The delimiter d 
     may be any printing character.

     If  no  TITLE  statement is used,  then  XASM09  supplies  a 
     default  title consisting of the text "SOURCE FILE  NAME:  " 
     followed by the name and extension of the input file.

SBTTL dtextd

     Just like TITLE,  but sets the listing page subtitle,  which 
     is printed on the line after the title line.

LIST and NOLIST

     These  allowselective  listing  of portions  of  a  program. 
     NOLIST  turns  off the assembly listing,  and LIST turns  it 
     back on. If listing has bee turned off with NOLIST, then the 
     next  LIST encountered will begin a  new  page.  Commnd-line 
     switches  which  disable  listing (ie.  X and O)  will  take 
     precedence  over LIST.  NOLIST does not turn off listing  of 
     the symbol table.
External Source File

INCLUD d:name.ext

     This  pseudo-op causes the specified file to be included  as 
     if  it  were  present  at this point  in  the  source  file. 
     INCLUD's  may  not  be nested;  that is,  the file  read  by 
     INCLUD  may not contain another INCLUD statement.  The  file 
     must end with an END statement.
Operator Synonyms

The Statement

     symbol    OPSYN     operator

causes  the  given  symbol to be defined as  a  synonym  for  the 
operator or pseudo-op specified as argument. This is particularly 
useful when assembling source file written for another assembler. 
For example,  if a program uses .BYTE instead of DB,  it could be 
correctly assembled by including the statement

     .BYTE     OPSYN     DB
:Errors

Fatal  errors  result in the printing of an error message on  the
console and immediate return to CP/M.  Fatal errors may be caused
by missing source files,  inadequate disk space for output files,
or overflow of the symbol table or various stacks.

Non-fatal errors are flagged with a character in the first column
of  the  assembly listing.  Lines containing  errors  are  always
listed,  even if listing is turned off.  A count is maintained of
lines  containing errors;  if the count is non-zero at the end of
the assembly, it is printed on the console in the message:

     ***** nnn LINES CONTAINED ERRORS *****

Only  one error is listed per line;  hence,  if a  line  contains
multiple errors some may not be caught until successive assembler
runs®  Thå   fataì erroò messageó anä non-fataì erroò  flagó  arå �
describeä later.
:Format of Listings

Page Headings

All listings begin with a heading consisting of seven lines:

                          (blank line)
     (blank line)
     (assembler name and version)
     (blank line)
     (title and page number)
     (subtitle)
     (blank line)
If no title is supplied in the source program, then the assembler
provides a default title consisting of the message

     SOURCE FILE NAME:

followed by the name of the input file in the form name.ext. The
page  number  is listed at the right-hand end of this same  line,
always within the specified page width.

If no subtitle is supplied, the subtitle line is left blank. Both
title and subtitle will be truncated,  if necessary,  to  satisfy
page width constraints.
Line Headings

Each  code-generating  line of the listin begins with  the  error
flag (blank if no error) and the 4-digit hexadecimal value of the
location counter as of the start of the line. This is followed by
up to four bytes of generated code,  also in hexadecimal with two
digits per byte. Statements which generate more than 4 bytes will
be  assembled  correctly,  but only the first four bytes will  be
listed.  Lines  which do not generate code but which evaluate  an
operand  (such as EQU or WIDTH) list the operand value  in  their
headers, in place of the location counter.
Symbol-Table Listing

The symbol-table listing shows all symbols defined in the current
assembly,   with  their  hexadecimal  values.  Only  user-defined
symbols  are  listed.  Symbols are in  vertical  columns,  sorted
alphabetically  according  to the ASCII collating  sequence.  The
number  of  columns  is  adjusted automatically  to  fit  in  the
specified page width.  All pages of the symbol-table listing  are
automatically subtitled.

     ---- SYMBOL TABLE ----

Because  the sorting scheme used is strictly  lexicographic,  the
way it orders numbers may be counterintuitive. A typical sequence
of labels might be listed as follows:

     SYM19, SYM2, SYM21, SYM3, SYM4
:Error Messages and Flags

Non-Fatal Error Flags

     C    Conditional Err     Unmatched IF, ELSE, or, ENDIF; or
                              conditionals nested too deeply.

     I    Includ Err          File not found, or nested INCLUD's.

     L    Label Err           Label too long. (>8 characters)

     M    Multipule Defn      Symbol already defined.

     O    Operator Err        Undefined or illegal operator

     P    Phase Err           Symbol has different value on pass
                              2 than on pass 1

     R    Range Err           Argument out of bounds, branch out
                              out of range, or illegal register

     S    Syntax Err          Ill-formed argument or expression

Fatal Error Messages


SOURCE FILE NOT FOUND              The specified source file
                                   doesn't exist.

UNABLE TO CREATE OUTPUT FILE       The directory is full on the
                                   disk specified for output

OUTPUT FILE WRITE ERROR            The output disk is full

EVALUATION STACK IS FULL           An arithmetic expression was
                                   encountered which had too many
                                   levels of parentheses or of
                                   precedence nesting

SYMBOL TABLE FULL                  Not enough memory remains to
                                   to create a table entry for a
                                   symbol being defined.
Non-Fatal Error Messages

NO ROOM FOR SYMBOL-TABLE SORT      Not enough memory is available
                                   to sort the symbol table.
                                   Symbol-table listing is
                                   therefore omitted.
:Object File Format

Objecô fileó caî bå iî onå oæ twï formats® Theså arå eitheò Inteì �
HEØ formaô oò Motorolá S± format®  Thå extensioî foò aî Inteì HEØ �
formaô  filå  ió  `.HEX§ anä thå extensioî foò  thå  Motorolá  S± �
format file is `.MIK'. (See option switch K in section B)
     Inteì HEØ format¬ whicè representó binarù datá byteó aó two-�
digiô  ASCIÉ  hexadecimaì numbers®  Aî objecô filå consistó oæ  á �
sequencå oæ datá records¬ followeä bù á singlå enä record.
     Thå   checksuí  ió thå two'Ó complemenô oæ thå  8-biô   sum¬  �
withouô  carry¬   oæ alì thå datá bytes¬  thå twï byteó  oæ  loaä �
address¬ anä thå bytå count.
The record formats are:

     Data Record:

     Byte 1         Colon (:)
          2..3      Number of binary data bytes in this record.
          4..5      Load address for this record, high byte.
          6..7      Load address  "   "     "     low byte
          8..9      Unused, should be "00".
          10..X     Data bytes, two characters each.
          X+1..X+2  Checksum  (2 characters).
          X+3..X+4  CR/LF
     End Record:

     Like data record,  but number of data bytes is zero and the
     load address field contains the program starting address.
Motorolá  S± format¬  whicè representó binarù datá byteó aó  two-�
digiô  ASCIÉ hexadecimaì numbers®  Aî objecô filå consistó  oæ  á �
sequencå oæ datá records¬ followeä bù 'S9§ tï indicatå thå enä oæ �
the data block.

The record formats are:

     Data Record:

     Byte 1         'S'
          2         '1'
          3..4      Number of binary data bytes in this record.
          5..6      Load address for this record, high byte.
          7..8      Load address  "   "     "     low byte
          9..X      Data bytes, two characters each.
          X+1..X+2  Checksum  (2 characters).
          X+3..X+4  CR/LF

The  checksum is the two'S complement of the 8-bit  sum,  without
carry,  of all the data bytes, the two bytes of load address, and
the byte count.