.\"
.\"	Copyright (c) 1982 Regents of the University of California
.\"	@(#)asdocs4.me 1.9 7/1/83
.\"
.EQ
delim $$
.EN
.SH 1 "Machine instructions"
.pp
The syntax of machine instruction statements accepted by
.i as
is generally similar to the syntax of \*(DM.
There are differences,
however.
.SH 2 "Character set"
.pp
.i As
uses the character
.q \*(DL
instead of
.q # 
for immediate constants,
and the character
.q *
instead of
.q @ 
for indirection.
Opcodes and register names
are spelled with lower-case rather than upper-case letters.
.SH 2 "Specifying Displacement Lengths"
.pp
Under certain circumstances,
the following constructs are (optionally) recognized by
.i as
to indicate the number of bytes to allocate for
the displacement used when constructing
displacement and displacement deferred addressing modes:
.(b
.TS
center;
c c l
cb cb l.
primary	alternate	length
_
B\`	B^	byte (1 byte)
W\`	W^	word (2 bytes)
L\`	L^	long word (4 bytes)
.TE
.)b
.pp
One can also use lower case
.b b ,
.b w
or
.b l
instead of the upper
case letters.
There must be no space between the size specifier letter and the
.q "^"
or
.q "\`" .
The constructs
.b "S^"
and
.b "G^"
are not recognized
by
.i as ,
as they are by the \*(DM assembler.
It is preferred to use the 
.q "\`" displacement specifier,
so that the
.q "^"
is not
misinterpreted as the
.b xor
operator.
.pp
Literal values
(including floating-point literals used where the
hardware expects a floating-point operand)
are assembled as short
literals if possible,
hence not needing the
.b "S^"
\*(DM directive.
.pp
If the displacement length modifier is present,
then the displacement is 
.b always
assembled with that displacement,
even if it will fit into a smaller field,
or if significance is lost.
If the length modifier is not present,
and if the value of the displacement is known exactly in
.i as 's
first pass,
then
.i as
determines the length automatically,
assembling it in the shortest possible way,
Otherwise,
.i  as
will use the value specified by the
.b \-d
argument,
which defaults to 4 bytes.
.SH 2 "case\fIx\fP Instructions"
.pp
.i As
considers the instructions
.b caseb ,
.b casel ,
.b casew
to have three operands.
The displacements must be explicitly computed by 
.i as ,
using one or more
.b .word
statements.
.SH 2 "Extended branch instructions"
.pp
These opcodes (formed in general
by substituting a
.q j
for the initial
.q b
of the standard opcodes)
take as branch destinations
the name of a label in the current subsegment.
It is an error if the destination is known to be in a different subsegment,
and it is a warning if the destination is not defined within
the object module being assembled.
.pp
If the branch destination is close enough,
then the corresponding
short branch
.q b
instruction is assembled.
Otherwise the assembler choses a sequence
of one or more instructions which together have the same effect as if the
.q b
instruction had a larger span.
In general,
.i as
chooses the inverse branch followed by a
.b brw ,
but a
.b brw
is sometimes pooled among several
.q j
instructions with the same destination.
.pp
.i As
is unable to perform the same long/short branch generation
for other instructions with a fixed byte displacement,
such as the
.b sob ,
.b aob 
families,
or for the
.b acbx
family of instructions which has a fixed word displacement.
This would be desirable,
but is prohibitive because of the complexity of these instructions.
.pp
If the
.b \-J
assembler option is given,
a
.b jmp
instruction is used instead of a
.b brw
instruction
for
.b ALL
.q j
instructions with distant destinations.
This makes assembly of large (>32K bytes)
programs (inefficiently)
possible.
.i As
does not try to use clever combinations of
.b brb ,
.b brw
and
.b jmp
instructions.
The
.b jmp
instructions use PC relative addressing,
with the length of the offset given by the
.b \-d
assembler
option.
.pp
These are the extended branch instructions
.i as
recognizes:
.(b
.TS
center;
lb lb lb.
jeql	jeqlu	jneq	jnequ
jgeq	jgequ	jgtr	jgtru
jleq	jlequ	jlss	jlssu
jbcc	jbsc	jbcs	jbss

jlbc	jlbs
jcc	jcs	
jvc	jvs
jbc	jbs
jbr
.TE
.)b
.pp
Note that
.b jbr
turns into
.b brb
if its target is close enough;
otherwise a
.b brw
is used.
.SH 1 "Diagnostics"
.pp
Diagnostics are intended to be self explanatory and appear on
the standard output.
Diagnostics either report an
.i error
or a
.i warning.
Error diagnostics complain about lexical, syntactic and some
semantic errors, and abort the assembly.
.pp
The majority of the warnings complain about the use of \*(VX
features not supported by all implementations of the architecture.
.i As
will warn if new opcodes are used,
if
.q G
or
.q H
floating point numbers are used
and will complain about mixed floating conversions.
.SH 1 "Limits"
.(b
.TS
center;
l l.
limit	what
_
Arbitrary\**	Files to assemble
BUFSIZ	Significant characters per name
Arbitrary	Characters per input line
Arbitrary	Characters per string
Arbitrary	Symbols
4	Text segments
4	Data segments
.TE
.)b
.(f
\**Although the number of characters available to the \fIargv\fP line
is restricted by \*(UX to 10240.
.)f
.SH 1 "Annoyances and Future Work"
.pp
Most of the annoyances deal with restrictions on the extended
branch instructions.
.pp
.i As
only uses a two level algorithm for resolving extended branch
instructions into short or long displacements.
What is really needed is a general mechanism
to turn a short conditional jump into a 
reverse conditional jump over one of
.b two
possible unconditional branches,
either a
.b brw
or a 
.b jmp
instruction.
Currently, the 
.b \-J
forces the
.b jmp
instruction to
.i always
be used,
instead of the
shorter
.b brw
instruction when needed.
.pp
The assembler should also recognize extended branch instructions for
.b sob ,
.b aob ,
and
.b acbx
instructions.
.b Sob
instructions will be easy,
.b aob
will be harder because the synthesized instruction
uses the index operand twice,
so one must be careful of side effects,
and the
.b acbx
family will be much harder (in the general case)
because the comparison depends on the sign of the addend operand,
and two operands are used more than once.
Augmenting
.i as
with these extended loop instructions
will allow the peephole optimizer to produce much better
loop optimizations,
since it currently assumes the worst
case about the size of the loop body.
.pp
The string temporary file is not put in memory when the -V flag is set.
The string table in the generated a.out contains some strings
and names that are never referenced from the symbol table;
the loader removes these unreferenced strings, however.
