The UNIX 68020/68881/68851 cross assembler


GENERAL
        The assembler resides in /usr/local under the name asm20.  Command
        line arguments specify the filenames to assemble.

        The `S1' formatted object file is placed on file `m.out', the
        listing and error messages are written to the standard output.

        The listing file contains the address and bytes assembled for each
        line of input followed by the original input line (unchanged, but
        moved over to the right some).  If an input line causes more than 6
        bytes to be output (e.g. a long DC.B directive), additional bytes
        (up to 64) are listed on succeding lines with no address preceding
        them.

        Equates cause the value of the expression to replace the address
        field in the listing.

        It is unwise to have more than one assembly in progress per
        directory since the object file would be the same for all
        assemblies running.

        Equates that have forward references cause Phasing Errors in Pass
        2.

        Expressions may consist of symbols, constants or the character '*'
        (denoting the current value of the program counter) joined together
        by one of the operators: +-*/%&|^.  The operators are the same as
        in C:

		+       add
		-       subtract
		*       multiply
		/       divide
		%       remainder after division
		&       bitwise and
		|       bitwise or
		^       bitwise exclusive-or

        Expressions are evaluated left to right and there is no provision
        for parenthesized expressions.  Arithmetic is carried out in signed
        32-bit twos-complement integer precision.

        Constants are constructed with the same syntax as the Motorola
        Microsystems assembler:

		$       followed by hexadecimal constant
		@       followed by octal constant
		%       followed by binary constant
		digit   decimal constant

        String constants are specified by enclosing the string in single
        quotes.  Strings are only recognized by the DC pseudo-op.

ERRORS

        Error diagnostics are placed in the listing file just before the
        line containing the error.  Format of the error line is:

		Line_number: Description of error
			or
		Line_number: Warning --- Description of error

        Errors of the first type in pass one cause cancellation of pass
        two.  Warnings do not cause cancellation of pass two but should
        cause you to wonder where they came from.

	Error messages are meant to be self-explanatory.

        If more than one file is being assembled, the file name precedes
        the error:

		File_name,Line_number: Description of error

        Finally, some errors are classed as fatal and cause an immediate
        termination of the assembly.  Generally these errors occur when a
        temporary file cannot be created or is lost during the assembly.
        Consult your local guru if this happens.

        The exit status of the assembler ($status for csh users) is equal
        to the number of errors detected during the assembly.


DIFFERENCES

        Even byte alignment on instructions is not checked.  If you're
        worried about this, try the 'align' pseudo-op (e.g. 'align 2' in
        front of every code section).

	Macros are not supported.  (try M4 or M6)

	Structured assembler constructs are not supported. (try C)

        Microsystems assemblers require parentheses when specifying word or
        long addressing modes.  This assembler assumes that no symbol will
        end with .w or .l

        The mnemonics used in this assembler follow the 68020/68881/68851
        User's Manuals.  The Microsystems assembler does not.  The main
        difference is in the name of the TRAPcc class of instructions.  A
        complete list of mnemonics can be obtained with the debug option:
        'asm20 -x64'.

        Floating point control register names are FPCR, FPSR and FPIAR
	instead of CONTROL, STATUS and IADDR.

	The pseudo-ops are:

		org
		equ
		dc              Define constant(s)
		ds              Define storage
		opt
		fequ            Floating point equ
		fopt            Floating point option
		align           align to 'N' byte boundary (.even == align 2)
		include         Filename argument is included

	The OPT pseudo-op allows the following operands:

		list    Turn on output listing (default)
		nolist  Turn off output listing
		brl     Force forward refs long (default is word)

	The FOPT pseudo-op allows the following operands:

		id      Set co-processor id for floating point instructions
		round   Rounding mode for constants (Not implemented)
		prec    Precision for constants (Not implemented)

	Some of the more common pseudo-ops are not present:

		spc     Use blank lines instead
		pag[e]  Use a comment with cntrl-L imbeded
		end     The assembly ends when there is no more input
		ttl     use `pr' to get headings and page numbers
		nam[e]  Did you ever use this one anyway?
		xref
		xdef
		idnt
		section
		p=68xxx If you don't want 68020 stuff, use another assembler

	The above pseudo-ops are recognized, but ignored.

DETAILS
        Symbol:  A string of  characters  with  a  non-initial  digit.  The
                string of characters may be from the set:

			   [a-z][A-Z]_[0-9]$

                ( _ count as a non-digit).  The `$' counts as a digit to
                avoid confusion with hexadecimal constants.  All characters
                of a symbol are significant, with upper and lower case
                characters being distinct.  The maximum number of
                characters in a symbol is currently set at 30.

                The symbol table can grow until the assembler runs out of
                memory.

        Label:  A symbol starting in the first column is a  label  and  may
                optionally  be  ended  with a ':'.  A label may appear on a
                line by itself and is then interpreted as:

			Label   EQU     *

        Mnemonic:  A symbol preceded by at least one whitespace  character.
                Upper  case characters in this field are converted to lower
                case before being checked as a legal mnemonic.  Thus `nop',
                `NOP' and even `NoP' are recognized as the same mnemonic.

        Operand:  Follows mnemonic, separated by at  least  one  whitespace
                character.   The   contents   of   the   operand  field  is
                interpreted by each instruction.

	Whitespace: A blank or a tab

        Comment:  Any text after all operands for  a  given  mnemonic  have
                been  processed or, a line beginning with '*' up to the end
                of line or, an empty line.

        Continuations:  If a line ends with a backslash (\) then  the  next
                line  is  fetched  and  added to the end of the first line.
                This continues until a line is seen which doesn't end in  \
                or  until  MAXBUF characters have been collected (MAXBUF >=
                256 ).

FILES
	m.out           object file output
	STDOUT          listing and errors

IMPLEMENTATION NOTES
        This is a classic 2-pass assembler.  Pass 1 establishes the  symbol
        table and pass 2 generates the code.

        Most limits are #defined in as.h.  After  changing  the  assembler,
	rerun the Makefile to rebuild the assembler.

	The mnemonic table is build from template descriptions.  Currently
	there are 5 template files: GEN, FLOAT, PMMU, COPROC and PSEUDO.
	To add new instructions to the assembler, you must:

		create a new template file and add it to the
			Makefile list of TFILES.
		add any new opcode classes to table.h
		add any new effective address classes to table.h, new
			composite types may require adding entries to
			eatab[] in match.c
		add case labels to match the new opcode classes to do.c
		add any new register names to iregs[] in regs.h

	This assembler is derived from the 8-bit cross assemblers
	for the 6809/5/4/1 family.

	The debug option (-x) uses a weighted number to turn on
	one or more print statements:

		1       Parser
		2       Template matches
		4       Expression Evaluation
		8       Symbol table lookup/install
	       16       Forward references
	       32       Indexed Indirect information
	       64       Dump all important tables

	e.g. -x10 displays template match operation and symbol table info.

BUGS
	This assembler is still under development.

	There is no way to specify immediate values greater than
	32-bits.  This makes it inconvenient to use immediate
	values in double,extended or packed floating point instructions.

	Floating point format constants (e.g. 1.234E-5) are not recognized.

	Matching mnemonics is expensive.  The assembler should be
	converted to 1-pass operation to speed things up.