bson@wheat-chex.ai.mit.edu (Jan Brittenson) (12/31/90)
Alright, so I finally get around to announcing STAR 1.03.1. It has
not yet been verified on MS-DOS/MSC5.0, but hopefully will be so soon,
when the holidays are over; more on this later.
So what's new. Not that much, actually.
* Local symbols, Macro-11 fashion. (Although the vary hacker
recognizes that the $ sign goes in up front, instead of
after the integer.) Local symbols alleviates you from having
to invent symbol names ad naseam. Unlike Macro-11, they are
not local to macros, so use `gensym' for symbols in macros.
foo: ; Global symbol introduces new local context
data.a $1-., $2-.
$1: ascii `howdy doo'
$2: ascii `hi world'
bar: ; Global symbol introduces new local context
data.a $1-foo, $2-foo
$1: ascii `pickle'
$2: ascii `berry'
* Shared literal pool. The single-quote character (') appends
a piece of code to the literal pool. Literals are considered
read-only, unless superceded on the command line, and STAR is
considered left to do whatever sharing optimizations are
possible. For instance, in the following fragment,
move.5 '`ascii `ABCDEF'', d0
move.5 '`ascii `ABC'', d1
the first literal will be reused in the second instance. In
fact, STAR may theoretically reuse a literal whenever it's
a subset of a previous one (although the matching engine
is more like a rubber band right now). Currently, a pooled
literal (not "literals," really, but the name comes in handy)
may consist only of one statement. If you need more than
one statement in a literal, define a macro for it, e.g.,
macro mul_c_5
move.a c, a
slb.a c
slb.a c
add.a a, c
ret
endmacro
call '`mul_c_5'
Literal sharing, of course, is done on the binary level, so
different statements resulting in the same code are shared.
The reason for specifying pooled literals as R/O is that
they will go into ROM. (More on ROM coding in STAR 1.04
which will incorporate program/data sectioning and more.)
* Jumpification. A branch to a destination outside its range
is converted to a branch with the inverse condition over a
suitably sized jump. This of course means you cannot depend
on the status of the carry bit after a branch unless you
disable jumpification. If you _have_ to depend on the carry
status following a branch, disable jumpification.
* A few "ghost instructions" ("-->" is read "translates to")
SLB.f d --> ADD.f d, d
CLR P --> MOVE.1 0, P
CLR.f Dn --> MOVE.f 0, Dn
DEC/INC Dn --> ADD/SUB 1, Dn
These were added mainly for orthogonality's sake. Examples:
slb.x a
clr.4 d0
inc d1
dec.a d0
clr.1 p
* Library support via the `LIBCALL' and `USED symbol'
constructs. For instance, assume library IO.star defines
the functions PUTCHAR and GETCHAR. Then, to use PUTCHAR
you could write, in your program:
libcall putchar
; ...
move.b `>', c ; Write prompt
call putchar
Whereas IO.star would use:
if used putchar
putchar:
; ...
ret
endif
Simple, and easy to use.
I guess that's about it for this time. I've included the new README
below. Happy holidays, everyone!
-- Jan Brittenson
bson@ai.mit.edu
(I add again, that it may not work on MS-DOS yet. MS-DOS users
should wait for 1.03.2.)
O /
\/
/\ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
O \
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 to
include #define MSDOS) with Microsoft C 5.0.
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.
[In 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". -- bson]
* * *
STAR 1.03 README
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.
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.
[ Note: STAR is based on an assembler I wrote in 1986 for National
Semiconductor's Series 32000. NS32k heavily (read: almost always) uses
displacements to address data, esp. in code generated by an HLL
compiler. The optimizer pass(es) would in some cases cut down the code
size by 30% or more. The technical reason for not optimizing
references during pass 1, is that forward references are yet
unresolvable, and so the worst case must be assumed - 24 bits on the
32k. Very little code hasn't actually been rewritten for the Saturn
version, though.]
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, 1.02 (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
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: ; ...
Some 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
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.edubson@wheat-chex.ai.mit.edu (Jan Brittenson) (12/31/90)
I forgot to mention that STAR 1.03.1 is available from trix.ai.mit.edu with anonymous FTP, in ~/pub/star-1.03.tar.Z -- Jan Brittenson bson@ai.mit.edu