STAR Release 1.04.4


INSTALLATION NOTES FOR AMIGA USERS

   Bill Gribble reports that STAR compiles and - apparently - runs
with minimal effort on Amigas. Included in the distribution is a file
`amiga.zoo' which contains Amiga-specific files, as provided by Bill.

Here is a set of notes I received from Bill:


Date:     Sun, 10 Mar 91 16:26:27 PST
From: Bill Gribble <bgribble@jarthur.claremont.edu>

I didn't include a modified star.h; defining the system as SysV works
  fine, although star -? says it's running on a unix clone.  I'd
  rather think the Amiga is running UNIX, so I can live with that.  I
  also didn't include the header file varargs.h, which the Amiga
  doesn't have.  I just downloaded the one from our DYNIX machine and
  it worked fine, but I think Sequent might not be thrilled about it
  being distributed.

[I have nevertheless included a #define AMIGA in star.h for
  consistency.  --bson]


Star passes the set of tests you distributed, except for a few errors
  where you didn't say there should be any (t24.star, I think, and a
  few others) but they looked like real errors so I'm not worried.
  The file dotests works ok, but I'm running SKsh, a unix shell clone,
  so it might not work on some other Amigas.

[T24 should not result in any errors, it's all correct code as long as
  it's assembled with hp48.star  --bson]


As for Amiga-specific things: I think you'll be hapy to hear that
  there really aren't any.  AmigaDOS is pretty much a minix, and most
  software uses unix command-line and filename conventions.  You might
  change star.h to reflect the right system name, and perhaps work it
  so that the Amiga loses the AT&T filename length restrictions and
  case sensitivity.  If you want to, merge my lmkfile with your
  Makefile and comment out the appropriate bits; the Lattice make
  recognizes makefiles called 'lmkfile' or 'Makefile' equally well.
  Please do *not* try to make the Amiga version like the msdos
  version; Amiga owners get highly incensed at the slightest
  intimation that their machine resembles anything msdos in the least.

[I just included lmkfile as provided by Bill.  --bson]


Installation, with the makefile I enclosed, consists of typing 'lmk'
  to run the Lattice make utility.  With a floppy-only system,
  though... Hmm...  The executable is over 100k, and running it from
  floppies would definitely be slow.  Anyone with a C compiler and a
  floppy-only system will have long since discovered the best way to
  deal with this hellishly painful situation, and I really can't offer
  good advice, except to distribute the executable so they don't have
  to compile it.  The various flavors of Amiga are all binary
  compatible.


				* * *


INSTALLATION NOTES FOR MS-DOS USERS

   Many thanks to Gadiel for locating the MS-DOS-related problems. Due
to his efforts, STAR should compile effortlessly (just edit star.h)
with Microsoft C 5.0 or later. Darryl Okahata has provided the
necessary adjustments to accomodate Turbo C. MSC and TC make files can
be found in `MAKEFILE.MSC' and `MAKEFILE.TCC' respectively. Notice
that you must change the definition of `XLIBDIR' in `MAKEFILE.TCC'.
Gadiel's MS-DOS notes below are applicable regardless of choice of
compiler.


 From: Gadiel Seroussi <gadiel@hplgser.hpl.hp.com>
 Date: Tue, 18 Dec 90 09:00:05 pst
     
     
   One warning for MSDOS users that you may want to include in the 1.03 
   documentation: *.star source files MUST have all lines properly
   terminated with a CR-LF combination. LF alone (as UNIX files would
   have) is not enough, it makes the macro processor fail miserably.
   This is due to the fact that MSDOS ftell() and fseek() are pretty flaky
   on text files. If you don't have the CR-LF combination, 
   fseek(file, ftell(file), 0) doesn't leave you in the same place.
   So, for instance, if you get your "hp48.sta" file by unpacking a 
   UNIX-generated tar file, you better "fix" the line terminations before 
   attempting to use it.


 [Since 1.03, under MS-DOS, the source file type is set to ".STR". So Unix-
  formatted .star files will not be used unless STAR is explicitly told
  to. Apply the above suggestions to *.star, and rename them *.STR for
  MS-DOS use. Perhaps they in a future release will be included as
  both "*.star" and "*.STR" with different carriage controls. -- bson]

				* * *


   There is no documentation yet, but I have included the files I have
used for testing STAR this far. They can be found as *.star, and
exercise most features of the assembler.

   There are a few instructions that differ syntactically from ASAP,
SASS, and Alonzo's Processor Notes. This is so, because I found no way
to lexically cope with a different numbers of arguments, depending on
what these arguments are. (The classical Fortran/lex problem.) The
instructions are:


	move.1	c,i,p	-->   move.1  c.i, p
	move.1  p,c,i   -->   move.1  p, c.i
	swap.1  p,c,i   -->   swap.1  p, c.i   (or c.i, p)


   Also, STAR implements the special register HST. To clear (or
similarly, to test) HST bits, use (for example):

	clrb	5, hst			; Three identical constructs
	clrb	(1<<xm)|(1<<sr), hst	; XM = 0, SR = 2
	clrb	[xm,sr], hst		; [] = bit mask


   Default suffixes are as per Alonzo's Processor Notes with the
following additions:

	rln		-->  rln.w
	rrn		-->  rrn.w

	move  id,a	-->  move.a  id,a


   For improved orthogonality, a few ghost instructions are recognized
as well:

	clr	p	-->  move.1  0, p
	clr.f	Dn	-->  move.f  0, Dn
	inc.a	Dn	-->  add.a   1, Dn
	dec.a	Dn	-->  sub.a   1, Dn
	slb.f	d	-->  add.f   d, d


STAR also can't lexically cope with Alonzo's notation

	brcc	pc+17

since PC is a register, and as such can't be used in expressions.
Instead, use "." (the dot) to refer to the address of the current
instruction. The above would in STAR be written as:

	brcc	.+17


   JUMP and CALL instructions default to relative (.3 or .4) when the
address is in RAM, to absolute (.A) when the address is in ROM, and
signal an error when the address is in neither. (See the STATIC and
FLOATING directives below.) Relative addresses are by default the
smallest possible.

   STAR supports a feature called `jumpification.' Jumpification means
that all branches out of range are converted to a short branch over a
jump large enough to address the destination. So you should not
normally depend on the carry having any specific value following a
branch. If you really need to do so, jumpification can be disabled
with the -j option.

   This is where the optimizer pass comes in. In the first pass all
relative offsets are 4 nibbles, but during the remaining passes
offsets are cut down to 3 nibbles when feasible. Reducing the size of
offsets will reduce the code size, perhaps resulting in further
possible reductions if run through further passes. The optimizer pass
is repeated until no further reductions are possible. The idea is that
in the future nonreferenced code will be ditched. [Note - there are
certainly less CPU-intensive algorithms for accomplishing this;
unfortunately they do not work too well with man-written code. I'm
working on it, though.]

   You are recommended to use the memory configuration
(STATIC/FLOATING partitioning) set up by the HP-48SX Standard Macro
Library (hp48.star), and totally ignore suffixes with JUMP and CALL
instructions. Use suffixes only for very special purposes, like
generating ROMable code. Let STAR handle the offset sizes.


   Here follows a list of recognized operators. Note that &&, ||, and
^^ always evaluate both arguments, unlike in C. They are logically the
same, though, i.e.:

	(1 & 2)  -->  0			1 and 2
	(1 && 2) -->  1			Both nonzero

   Like any assembler worth the media it's stored on, STAR ignores
operator arities.

	# ^x x' 0x 16'		Hex number
	^d d' 10'		Decimal (base 10) number
	^o o' 8'		Octal number
	^b b' 2'		Binary number
	r^ r'			Real (double) number - default
				for any number containing a decimal
				point or `e' character
	'	('str)		Literal. The argument string is
				


	~			Binary NOT
	!			Logical NOT (is zero)
	&			Binary AND
	&&			Logical AND (both nonzero)
	|			Binary OR
	||			Logical OR  (either nonzero)
	^			Binary XOR
	^^			Logical XOR (either, but not both nonzero)
	
	<<			Left shift
	>>			Right shift

	[i1,i2,i3...]		Integer with bits i1, i2, i3... set
				and all other bits clear.

	rm^	(rm^i)		Right mask, yields an int with `n'
				right-adjusted 1s. 

	wd^	(wd^real)	Real as 64-bit quantity, as stored in a
				"real" object.

	* / -			Standard arithmetic, no arity
	+			Add numbers or concatenate strings
	%			Modulo (same as `fmod' for reals)
	-			Unary minus
	**			Power (coerced to real)

	`str'			String

	r%	(str r% n)	Right, all characters from pos n to
				end of string
	l%	(str l% n)	Left, all characters up to n
	sz^	(sz^ str)	Length of string in bytes
	ch^	(ch^i)		Integer ASCII value to string
	tl^	(tl^ str)	Trim leading blanks
	tt^	(tt^ str)	Trim trailing blanks
	ev^	(ev^str)	Evaluate expression
	uc^	(uc^str)	Convert to uppercase
	i^	(i^str)		Machine code of string
				(e.g. i^`add.a a,b')
	ni^	(ni^str)	Length of i^ for string.

	def name   -or-		Nonzero if "name" is a defined
	df name			symbol.

	used name		Nonzero if "name" has been libcalled.

	()			Parenthesis, subexpression.

	> < >= <= == !=		C-style relational operators

    Real operators:

	cos, sin, tan, acos,	Trig
	asin, atan, sinh,
	cosh, tanh

	log, log10		e and 10 logs

	ceil, floor		Rounding (from 0, towards 0)

	exp			e**x

	fabs			Absolute value
	
	fmod			Modulo, same as %

	sqrt			Square root


Predefined symbols:

	saturn			48; default memory model
	version			Current version, real
	list			Nonzero if listings enabled
	bits			Number of bits in an integer

	xm			0; HST XM bit #
	sb			1; HST SB bit #
	sr			2; HST SR bit #
	mp			3; HST MP bit #

	pass			Current pass, 1, 2, or 3
	.			Current location
	sect			Current section

	pi, e
	ln2			log(2)
	sqrt2			sqrt(2)
	log2e			log10(2*e)
	log10e			log10(10*e)
	ln10			log(10)


Examples of operator usage:

	s=`add.a a,a'
	data.$(ni^s)  i^s	; Create code for ADD.A A,A

	s=1.5
	data.w	wd^s		; Identical...
	double	s		; ...with this

	move.p16  wd^s, c	; C=1.5e0


	call	'`jump.a #6657+5'


Preexpansion:

	$name		Expands to value of name. \$ escapes expansion.
				
	$(expr)		Expands to result of expr.

	$$		Expands to $

    Example:

	lseq=1
	...
	m=`move'
	foo=5
	dreg=1
	lseq=lseq+1

L_$(lseq+1): $m.$foo	addr, d$dreg

    Will expand to:

L_3:	move.5	addr, d1


Notice that expansion can not be nested, i.e. the following won't work:

	foo=``1+2''
	data.a	$($foo)		; WILL NOT WORK AS INTENDED


Conditional assembly, nesting up to 16 levels:

	if expr
	  ...
	else
	  ...
	endif


   Local symbols are of the form $nn where `nn' is a 16-bit decimal
integer. Local symbols are defined between two global labels. Only
labels (i.e. name followed by colon) count. Example:

$1:	call	$2
	bar=.
$2:	ret

foo:	; New local symbol scope

$1:	jump	$2
$2:	; ...



Pseudo instructions:

	radix i				Set default radix
					Supported radixes are 2, 8, 10, 16,
					and 0 for real.

	origin expr			.=expr

	name=value			Assign value to symbol
	define name value		name=value

	libcall n1, n2, n3...		Announce that code refered to by
					names is to be included.

	save n1, n2, n3...		Reinstantiate names (save values).
	restore n1, n2, n3...		Deinstantiate names (restore values).
	hide n1, n2, n3...		Hide names from symbol table.

	odd				Align for odd address
	even				Align for even address
	align n				Align for even n-nibble word

	byte  i1, i2, i3...		Byte data (same as data.b)
	data.f i1, i2, i3...		Data of size 'f' (.1-.16, .B, .X, .A,
							  and .W)

	ascii  s1, s2, s3...		Ascii data. S1...Sn are either:
					parenthesized expressions, in which
					case the value is used as a byte,
					or delimited strings. The delimiter
					is chosen to be the first character
					of the string. Escapes \n, \r, \b,
					\e, \ooo, \xhh work.

	asciz  s1, s2, s3,...		Same as ascii, but terminate with
					NUL (\000) character.

	double	r1, r2, r3...		16-nibble real data

	error message			Display error message

	end				End of file
	exit				End of assembly pass

	psect name			Switch to r/w (RAM) program section.
	csect name			Switch to r/o (ROM) program section.
	dsect name			Switch to r/w (RAM) data section.
	lsect name			Switch to r/o (ROM) literal data
					section.
	asect name			Begin/continue address section.

	doblock	m, blockterm		Read block of input and apply macro
					m to it (see hp48.star for examples)
					DO NOT NEST

Macros.

Macro definitions are of the form:

label:	macro	name	arg1, arg2..., argn
	... macro body ...
	endmacro


where n is 0 or up, and `argi' is of the form:

	name		-or-

	name=default

where `name' is the symbol to be instantiated to the argument value
(passed at the macro call as a string, use ev^ to evaluate an
expression). If no value is given for the argument in the macro call,
the optional default value is used instead. If no default value is
defined, an error is signal and the macro call ignored.

   Here is a sample macro. It implements the HP-48 `global name' data
type. A similar macro can be found in the STAR HP-48SX Standard Macro
Library (file hp48.star). When called with no argument, it defaults to
a null string name.


	macro	global  name=``''
	data.a	x'2e48
	data.b	sz^$name
	ascii	$name
	endmacro


	global	`ABC'		; Global name `ABC'

	global			; Header template
	ascii	`XXXXXXXXX'	; Filled in later


HP-48SX Standard Macro Library definitions:

	false	0
	true	1
	warnings		Symbol - nonzero value means warnings enabled

	warning msg		Generate warning (msg is string).

	sym: equ value		EQU-style assignment

	listblock		Enable listings
	nlistblock		Disable listings
	endlist			Revert back to previous enable/disable

	rpl			Implicit RPL/data.a body
	  ...rpl body...	DO NOT NEST
	endrpl
	
	header	rev		Kermit preamble HPHP48- followed by revision

	string	str		RPL string object
	global	name		RPL global name object
	local	name		RPL local name object
	binary	value,digits	RPL binary integer object
	short	i		RPL system binary object
	address	i		RPL system binary object
	character c		RPL character object

	code			RPL code object
	  ...ml code...		DO NOT NEST
	endcode


   Note: Do not nest macros where so indiciated. It won't work as
intended - in fact, the results are unpredictable - they may not
even contain references to each other.

   To `unquote' from within an RPL body, prefix the line with
underscore (_). Example:

Drop = x'3244

	RPL
	  Drop
	  _ascii `foo'
	  Drop
	ENDRPL


The above example is identical to:

	data.a	Drop
	ascii	`foo'
	data.a	Drop


Symbols can be defined within both RPL and CODE constructs.

						-- Jan Brittenson
						   bson@ai.mit.edu
