

		         The as11 cross assembler


GENERAL

	Command line arguments specify the filenames to assemble.

	The assemblers accept options from the command line to be
	included in the assembly.  These options are the following:

		l 	enable output listing (to stdout)
		lo	create output listing (to file source.lst)
		nol 	disable output listing (default).
		cre 	generate cross reference table.
		s  	generate a symbol table.
		c  	enable cycle count.
		noc 	disable cycle count.
		erl 	generate error listing

	The command line looks like this :

		as11 [ -option1 -option2 ...] file1 file2 ... 

	If this method of passing commands to the assembler is
	used rather than the OPT pseudo op code, each option should
	be preceeded by a minus sign.  

	Example 1:

	   as11 -l -cre program

	This command assembles file 'program' with an output
	listing to stdout and a cross reference table. 
	If 'program' is a file name without extension, '.asm' is assumed.

	Example 2:

	   as11 -lo program

	This command assembles file 'program' with an output 
	listing to a file named 'program.lst'. If the file already exists,
	it is overwritten.

	In both examples, the `S1' formatted object file is placed in 
	file `filename.s19', the listing and error messages are
	written to  the standard output.  If multiple files are
	assembled, the 'S1' file will be placed under the first
	file's name.s19.

	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 FCC 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.

	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
		{    bitwise shift left
		}    bitwise shift right

	Expressions are evaluated left to right and there is no provision
	for parenthesized expressions.  Arithmetic is carried out in signed
	twos-complement integer precision (16 bits on the IBM PC under DOS, 
	32 bits under Linux)

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

	'   		followed by ASCII character
	$   		followed by hexadecimal constant  
			(trailing 'H' also works)
	@   		followed by octal constant        
			(trailing 'Q' also works)
	%   		followed by binary constant       
			(trailing 'B' also works)
	digit 		decimal constant
	/string/ 	string constant


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

	In the error listing (when option ERL is used), the error line is 
	followed by the source code line which caused the error.

	Errors of the first type in pass one cause cancellation of pass
	two, and no .s19 file is created.  
	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.


FEATURES

	For indexed addressing, the comma is required before the  register;
	`inc x' and `inc ,x' are not the same.

	Macros are not supported.  

	The force size operators ('>' and  '<')  are  implemented.

	The only pseudo-ops supported are:

		ORG, FCC, FDB, FCB, EQU, RMB, BSZ, ZMB, FILL
		PAGE, DB,DW, DS and OPT.

	The OPT pseudo-op allows the following operands:

		nol     Turn off output listing
		l       Turn on output listing (default)
		noc     Disable cycle counts in listing (default)
		c       Enable cycle counts in listing (clear total cycles)
		contc   Re-enable cycle counts (don't clear total cycles)
		cre     Enable printing of a cross reference table
		s       generate a symbol table


	ZMB (Zero Memory Bytes) is equivalent to BSZ (Block Store  Zeroes).
	FILL can be used to initialize memory to something other than zero:
	FILL val,nbytes.

        Bit manipulation operands are separated by blanks instead of commas.


DEFINITIONS

	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]$

		( . and _ count as non-digits ).  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 15.

		The symbol table has room for  at  least  2000  symbols  of
		length 8 characters or less.

	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.

		Note that register names that sometimes appear at  the  end
		of  a  mnemonic (e.g. nega or stu) must not be separated by
		any  whitespace  characters.   Thus  `clra'   means   clear
		accumulator A, but that `clr a' means clear memory location
		`a'.

	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.

		Now comments may begin with either a '*' or a ';' character and
		if a ';' is used they may begin in any column.  Not just the first.

	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
	filename.s19    S-record output file
	STDOUT          listing and errors (default)
	filename.lst	listing file (when option lo used)
	filename.erl	error listing (when option cre is used)
	Fwd_refs        Temporary file for forward references.

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

							12/11/84 E.J.Rupp

	This version of the cross assembler ported to the IBM PC 4/13/87

  						        03/29/90 B.L.Olney

	 The following fixes/enhancements have been made during 1988 and 1989.

	 - Version number displayed.  Current version at this writing is 1.03.
	 - Fixed lost cluster problem.
	 - Semicolon allowed as comment character.
	 - Comments may begin on any column if prefixed with a semicolon.
	 - db is a synonymn for fcb.
	 - dw is a synonymn for fdb.
	 - ds is a synonymn for rmb.
	 - New operators for shift left '{' and shift right '}'.  The left operand
	   is the word to be shifted and the right operand is the number of bit
	   positions to shift.
	 - Trailing radix specifiers are now allowed.  
		Trailing 'H' or 'h' is same as leading $ for hexadecimal constants.
		Trailing 'Q' or 'q' is same as leading @ for octal constants.
		Trailing 'B' or 'b' is same as leading % for binary constants.
	 - Error reporting for constants improved.
	 - Line number of errors now is relative to beginning of file.
	 - Formatting of symbol table enhanced.
	 - Number of errors found is reported at end of assembly.

	The following enhancements have been made in 1994:

	- Input files are assumed to have '.asm' extension, unless otherwise
	  specified.
	- Command line option ERL generates a separate 'filename.erl' error
	  listing.
	- Version number is now 2.1.

	The following enhancements have been made in 1999:

	- source tree and makefile are now optimized for Linux, may not work 
	under another OS
	- command line option format now follows Unix practice (options then 
	filenames)
	- fixed bug which prevented from specifying the constant ';'
	  (the assembler recognized the ; as a comment character, even
	  when placed between quotes) -> Release TER_2.1
	- version number is now 2.15

