                                 PCCHASM v2.1

ACKNOWLEDGEMENTS

This assembler is based upon CHASM, the symbolic assembler produced by Colin
Hinson for native execution on 9900 based systems. Many thanks to colin for
access to his source code and for compatability testing.


DOS COMMAND LINE

PCCHASM file [-options...]

where options are:  B     compressed object output
                    C     case-sensitive symbols
                    J     allow far jumps
                    K     use K tag for idt
                    Lnn   max label length nn, default=6
                    M     MDEX compatabitity mode
                    S     local symbols in object
                    Tnnnn symbol table size, default=2000
                    X     symbol cross-reference

multiple options may seperated by blanks, each option string must be preceeded
by either a '-' or '/' character. The options are case insensitive.
the enviroment variable 'PCCHASM', if it exists, will be processed as though
it were an option string on the command line.

The assembler processes the source file 'file.ASM' and produces a tagged
object file in 'file.OBJ' and a listing file in 'file.LST'.


OPTION B
  The tagged object output file is in compressed format, the K option
  is ineffective if the B option is used. No checksum characters will be
  generated for commpressed object.

OPTION C
  This option causes the assembler to be case sensitive with regards to user
  symbols. Pre-defined mnemonics, directives and symbols are always case
  insensitive.

OPTION J
  This option allows the use of jumps to locations beyond the normal
  -128 .. +127 words. Far jumps are coded as an inverse jump followed
  by a branch to the desired location eg:


         FRED   JNE   THERE        ; very long way for a jump
                BSS   4000
         THERE  A     R6,R4

   would be assembled as though the source code was

         FRED   JEQ   $+4          ; very long way for a jump
                JMP   THERE
                BSS   4000
         THERE  A     R6,R4

OPTION K
  This option causes the tagged object to have the 'K' tag for the IDT rather
  than the standard '0' tag. This option is not available if the 'B' option is
  used.

OPTION L
  This option is immediately followed by a one or two digit decimal number in
  the range 6..32. This option sets the maximum symbol length that may be used
  by the assembler. The default maximum symbol length is 6 characters. The
  symbol length will be truncated to 6 characters when output in the tagged
  object file.

OPTION M
  This option causes the assembler to accept MDEX compatible source, the main
  differences are:
    a. Numeric values with a leading '0' are assumed hex.
    b. labels followed by a '*' are DEF'd.
    c. UDEF is automatically in effect.

OPTION S
  This option caused the local symbols to be output in the object file
  using the 'G' and 'H' tags.

OPTION T
  This option is immediately followed by a decimal number.
  This option sets the maximum number of symbols (memory permitting) that
  may appear in one assembly. The default is 2000 symbols.

OPTION X
  This option causes the assembler to produce a symbol cross-reference at the
  end of the listing if sufficient memory is available. Pre-defined symbols
  will not be included in the cross-reference. The symbol table listing will
  be suppressed if the cross-reference is produced.





                                SOURCE FORMAT

SPECIAL CHARACTERS
  The special treatment of control characters in the source file is as
  follows:
    TAB - expanded to one or more spaces (8 character tab stops).
    ^Z  - End of file.
    CR  - End of line.
    LF  - End of line.
    NUL - End of line.

  All characters with the msb set and un-listed control characters will be
  ignored.

COMMENT LINES
  A line starting with a '*',';' or '.' is treated as a comment line.

LABELS
  A label may optionally be followed by a ':', this is simply ignored.

NUMBERS
  numbers are assumed to be decimal unless preceeded by one of the
  following:
     '>'  - Hex
     '#'  - Hex
     '%'  - Binary

  In mdex compatibilty mode a number is assumed to be hex if it begins with
  a zero character.

OPERATORS
  .+  OR
  .*  AND
  .-  NOT
  ./  MOD
  +   ADD
  -   SUBTRACT
  *   MULTIPLY
  /   DIVIDE

DIRECTIVES
  Directives may optionally be preceeded by a '.' character, this is simply
  ignored.


SYMBOLS
  A symbol may contain the characters '0..9','A..Z','a..z','$' and '_' except
  that the first character must not be numeric. The maximum symbol size is
  6 characters, this may be increased to a maximum of 32 by the use of the L
  option. If the C option is not used all symbols will be converted to upper
  case.


                              UNSUPPORTED ITEMS
  The assembler does not support the following:
    a. expressions using brackets.
    b. macros.
    c. PSEG/PEND,DSEG/DEND,CSEG/CEND segment directives.

 
                             PSEUDO INSTRUCTIONS

  BKPT   : behaves as though a 'DXOP BKPT,15' has been processed.
  CMSG   : behaves as though a 'DXOP CMSG,6' has been processed.
  EKO    : behaves as though a 'DXOP EKO,11' has been processed.
  FLOP   : behaves as though a 'DXOP FLOP,2' has been processed.
  ISTK   : behaves as a 'LI SP,<expression>' where SP is the stack pointer
           register as defined by the DSTK directive.
  JSYS   : behaves as though a 'DXOP JSYS,1' has been processed.
  MSG    : behaves as though a 'DXOP MSG,14' has been processed.
  NOP    : equivalent to a 'JMP $+2' instruction.
  POP    : the word at the top of the stack is pop and stored at the
           address specified by the operand. The stack pointer is defined
           by the DSTK directive.
  POPJ   : the value at the top of stack is poped int R11 and then a branch
           to the address in R11 is performed. The stack pointer is defined
           by the DSTK directive.
  POPR   : alternative mnemonic for POPR.
  PSHR   : the word operand is pushed onto the stack and the stack pointer
           incremented by two. The stack pointer is defined by the DSTK
           directive.
  PUSH   : alternative mnemonic for PSHR.
  READ   : behaves as though a 'DXOP READ,13' has been processed.
  RHXW   : behaves as though a 'DXOP RHXW,9' has been processed.
  RT     : equivalent to a 'B *R11' instruction.
  SPIN   : equivalent to a 'JMP $' instruction.
  TOUT   : behaves as though a 'DXOP TOUT,7' has been processed.
  WHXW   : behaves as though a 'DXOP WHXW,10' has been processed.
  WNBL   : behaves as though a 'DXOP WNBL,8' has been processed.
  WRIT   : behaves as though a 'DXOP WRIT,12' has been processed.



                                  DIRECTIVES

 AORG
       <label> AORG           resume absolute code
       <label> AORG *         resume absolute code
       <label> AORG value     start absolute code at PC=value


 ASMELSE
       'ELSE' part of conditional assembly, see 'ASMIF' directive.

 ASMEND
       End of conditional assembly section, see 'ASMIF' directive.

 ASMIF
               ASMIF value

       If value is non-zero the following code will be assembled upto a
       matching 'ASMELSE' or 'ASMEND' directive.
       If value is zero the following code will be skipped until a matching
       'ASMELSE' or 'ASMEND' is encountered. If a matching 'ASMELSE' is
       encountered the code following it upto the matching 'ASMEND' will
       be assembled. There must be a matching 'ASMEND' for each 'ASMIF'
       directive. The 'ASMELSE' directive may ony occur between an 'ASMIF' and a
       'ASMEND' and may only occur once.
       Conditional assembly sections may be nested to a maximum of 20 deep.


 BSS
               BSS value
       The program counter is advanced by value. No data is generated for
       the skipped bytes.


 BUN
       This option causes the listing of byte directives to be truncated to
       a single line.


 BYTE
               BYTE value<,value> .. <,value>

       Successive bytes are initialised to the values given.
       The bytes generated are modified if the MASK directive has
       been processed.


 COPY
               COPY "filename"
      The specified filename is copied into the source file at the point of the
      'COPY' directive. 'COPY' files may be nested to a maximum of 20 deep.
      There is no limit to the number of copy files that may be used within a
      single assembly but the file 'tag' characters used in the listing file may
      repeat if an excessive number of files are used.

 DATA
               DATA value<,value> .. <,value>

       The program counter is aligned to an even boundary and then Successive
       words are initialised to the values given.


 DEF
               DEF  symbol<,symbol> .. <,symbol>

       The symbols listed are defined as public and are made available in
       the tagged object.


 DREG
       This directive is ignored. Register names are always defined.

 DSTK
       This directive specifies the register to use as the stack pointer
       for any stack pseudo instructions that follow. The default stack
       pointer is R10.

 DUN
       This option causes the listing of data directives to be truncated to
       a single line.
 
 DXOP
       symbol DXOP value
              DXOP symbol,value

       This directive creates a pseudo-instruction using the XOP number
       specified by value. The new instruction takes the form
       'symbol operand'.

 END
               END
               END  value
       This directive terminates the source file, if the end of file is reached
       an assumed 'END' directive is processed.

 ENDC
       This is an alternative mnemonic for 'ASMEND'

 EQU
       symbol EQU  value
       The specified symbol is set to the value given. The symbol
       must not already be defined.

 EVEN
       The program counter is forced to be on an even boundary.

 IDT
        symbol IDT
               IDT 'name'
       The object module will be given the specified name. The name will also
       appear on the top line of each page of listing. The default idt will
       be the file name being assembled.

 IFC
       This is an alternative mnemonic for 'ASMIF'

 LIST
       This directive resumes the generation of the listing file.

 MASK
             MASK value
       Any following TEXT or BYTE directive output is encrypted by
       excluseive-or'ing each byte with the ms byte of the mask value.
       Normal operation of the directives can be resumed by seting
       value to zero.

 OPTION
              OPTION option<,option> .. <,option>
       This directive sets the specified assembler options.
          XREF   - same as specifying the -X option on the command line
          OBJ    - ignored
          SYMT   - same as specifying the -S option on the command line
          NOLIST - same as UNL directive.
          TUNLST - same as TUN directive.
          DUNLST - same as DUN directive.
          BUNLST - same as BUN directive.
          MUNLST - ignored.
          LIST   - same as LIST directive.

 PAGE
       Causes a page break in the listing file if not already at a page
       boundary.

 REF
               REF  symbol<,symbol> .. <,symbol>

       The symbols listed are defined as external.

 RORG
       <label> RORG           resume relocatable code
       <label> RORG *         resume relocatable code
       <label> RORG value     start relocatable code at PC=value

 SET
       symbol SET  value
       The specified symbol is set to the value given. If the symbol
       is already defined the old value is over-written. Similar to
       'EQU' directive but may be used to create local symbols.

 TEXT
       <label> TEXT operand<,operand> .. <,operand>
         where operand is any byte value or text string.

      This directive causes successive bytes to be initialised with the
      characters of the given string. If the string is preceeded by a '-' then
      the last byte of the string will be negated. The bytes generated are
      modified if the MASK directive has been processed.

 TITL
               TITL 'string'
      The title at the top of each page of listing will be set to the
      specified string.

 TUN
       This option causes the listing of text directives to be truncated to
       a single line.

 UDEF
       This option causes all un-defined symbols to be REF'd.

 UNL
      Disable generation of the list file.

                                 ERROR CODES
  O    Invalid opcode
  S    Syntax error
  R    Range error
  D    DXOP error
  C    Conditional assembly error
  T    Type error
  L    Label definition error
  G    Unable to get number
  E    Expression error
  U    Undefined symbol
  M    Multiply defined symbol
  F    Copy file / nesting error
  X    Internal/External/System symbol conflict

