ASAP

                    A Saturn Assembler in Perl

                           Version 1.01


ASAP is an assembler for the Saturn processor used in HP's HP28 and
HP48SX calculators.  ASAP is written in Perl (Practical Extraction
and Report Language).

ASAP is kind of a quick hack (took about two days to write, and one more
to test), but it does work (famous last words...).  You could consider it
a prototype for a future C version.

To run ASAP, you need Perl 3.0 and a fast Unix machine.  On a 25 MHz
'386, it takes Perl about 30 seconds to load ASAP and compile it into
Perl's internal virtual machine code, taking about a megabyte of memory,
but after that ASAP assembles at an almost usable speed of about 1000
lines a minute.

The assembly language format accepted by ASAP is that described by
Alonzo Gariepy in his "HP28S Processor Notes", with the following
differences, restrictions, and enhancements:

     ** Field suffixes

     There are no default field suffixes. You have to say, e.g.,
     "jump.a foo", not "jump foo".

     ** Case sensitivity
 
     ASAP is case sensitive.  All built-in keywords like instruction
     names, field suffixes, and register names must be entered in 
     lower case.

     ** Comments

     Comments start with a ";" and extend to the end of the line.

     ** Identifiers

     Identifiers are used for labels and symbolic constants.  An
     identifier can consist of alphanumeric characters and
     underscores, but the first character may not be a number.
     Register names and names of instructions or assembler
     metacommands may not be used as identifiers.

     ** Labels

     A label may be written before an instruction or on a line of its
     own.  A label consists of an identifier and a colon:

     foo:  nop3
	   jump foo

     ** Constant literals

     ASAP allows constant literals that are decimal numbers ("123") and
     hexadecimal numbers prefixed by "#" ("#FF").

     ** Symbolic constants

     Symbolic constants may be declared using "=", as in

	     ones=#FFFF
	     move.p4  ones,c

     ** Constant expressions

     Constant expressions may be constant literals as described above,
     symbolic constants, or calculated as the difference of two labels
     ("foo-bar")  There are no other forms of constant arithmetic.

     ** Branch operands

     The operand of a relative branch instruction can be either a label
     or a constant expression specifying an absolute address.

     ** Starting address specification

     A starting address may be specified as a hexadecimal label:

	     #08000: nop3

     Don't use this; write position-independent code.

     ** Assembler metacommands

     Constant data may be generated using the following metacommands:

	     data.1	3
	     data.2	12			
	     data.3	#FFF
	     ...
	     data.16    #FFFFFFFFFFFFFFFF
     or
	     data.b	#FF			; constant byte
	     data.a	#55555			; constant address
	     data.w	#FFFFFFFFFFFFFFFF	; constant word

     The directive

	     even

     generates a zero nibble if the current address is odd.  This is
     useful for padding the object file to a whole number of bytes.

     ** Other restrictions

     Constants are limited to 28 bits because of word size
     limits in Perl.  However, hexadecimal constants are handled
     specially and can be up to 64 bits.


ASAP itself is a Perl script "asap" that is generated by another
Perl script called "gen-asap".  "gen-asap" reads the file
"instr.tab", which defines the Saturn instructions and their
operands.  To generate ASAP, just say "make".

ASAP takes three arguments: the assembly language file, the object
file, and the listing file.  The two latter arguments are optional.

The file "dropit.asap" contains a simple example program for the
HP48SX that simply drops the top of the stack.  It can be
assembled by entering

	perl asap dropit.asap dropit dropit.lst

or just "make demo".  The resulting file "dropit" will contain a
"Code" object that can be directly uploaded to the HP48SX using
Kermit.  "dropit.lst" will contain an assembly listing with object
code and symbol tables.

ASAP is in the public domain.  Please report any bugs to the address
below.

Have fun!

-- 
Andreas Gustafsson
Internet: gson@niksula.hut.fi
Voice: +358 0 563 5592