.\" $Id$
.TH UNI_ASS 6 "$Revision$"
.ad
.SH NAME
uni_ass \- universal assembler, assembler\-loader
.SH SYNOPSIS
~em/lib.bin/\fImach\fP/as [options] argument ...
.SH DESCRIPTION
The universal assembler is a framework allowing easy
generation of an assembler for any byte oriented machine.
The framework includes common pseudo instructions for name
definition, label usage, storage allocation and initialization
and expression evaluation.
The resulting program assembles assembly modules.
For some machines, it also does the link-editing (loading).
Arguments may be flags, assembly language modules, or,
in the case of an assembler\-loader, 
.IR arch (1)
libraries.
.br
Flags are:
.IP \-d\fIonum\fP
This option controls the listing.  Default is no listing.
.I Onum
is interpreted as an octal number.
Each bit controls part of the listing as follows:
.RS
.nf
0001: addresses in pass 1
0002: generated code in pass 1
0004: not used
0010: addresses in pass 2
0020: generated code in pass 2
0040: source lines in pass 2
0100: addresses in pass 3
0200: generated code in pass 3
0400: source lines in pass 3
1000: force .list and ignore .nolist
.fi
.RE
Thus bits in 0 to 8 control the listing format and
bit 9 forces a complete listing.
If
.I onum
is omitted or is 000 it is interpreted as 0700.
If
.I onum
is 1000 it is interpreted as 1700.
.br
Note that '-d' alone (unless it contains bit 9)
is not enough to get a listing.
A .list pseudo is also needed in each module to be listed.
Assemblers may be compiled with the listing facilities disabled.
.IP -s[\fIonum\fP]
This option controls the
amount of symbolic debug information generated.
.I Onum
is interpreted as an octal number.
The bits have the following meaning:
.RS
.nf
001: external symbols
002: local symbols
004: local, compiler generated labels
010: symbols defined in
.I .symb
pseudo instruction
020: records for
.I .line
and
.I .file
statements
040: section names
.fi
.RE
Default is 073: all except local compiler labels.
.IP -r
Generate relocation information, for assemblers\-loaders that can.
Assemblers always produce relocation information.
.IP -b
Turn off branch optimization.
.IP -o\fIname\fP
.IP -"o \fIname\fP"
.I name
is taken as the name of the
resulting load file.
The default name is \fBa.out\fP.
.PP
The assembler\-loaders assemble
and link together assembly language modules
machine
from files and libraries,
producing an \fIack.out\fP(5) format file, without relocation information.
The assemblers produce a relocatable \fIack.out\fP(5) format file.
.PP
Two different types of arguments are allowed:
.IP "1-"
Assembly language modules
.PD 0
.IP "2-"
UNIX archives, as maintained by arch(1). These archives must
only contain
assembly language modules with \fI.define\fP as their first
statement.
These are only accepted by assembler\-loaders.
.PD
.PP
Note that assembler\-loaders cannot do a partial load;
loading starts from assembly language and produces binary
machine code. No relocation bits are produced.
On the other hand, assemblers produce a relocatable file, to be handled
by \fIled\fP(1).
.SH "SECTIONS and TYPES"
The statements allocating and initializing space,
like instructions and
some pseudo-instruction reserve that space in the current
section.
The currently reigning type of section is determined by
the pseudo-instruction \fI.sect\fP.
Actually, the assembler knows nothing about section types. Sections have
numbers. The first section met gets number 0, the second gets number 1, etc.
Therefore, every assembly files should start with a line just mentioning the
sections used in the right order, so that no confusion can arise for \fIled\fP(1).
.SH SYNTAX
.PP
The syntax of expressions is identical to the C expression syntax,
except that square brackets are used for grouping.
Labels are followed by a colon, and are identifiers or
numbers between 0 and 9.
Numeric labels can be referenced using the label followed by 'b' of 'f'
determining the direction of search, backwards or forwards.
.IP letters
Both upper and lower case may be used and are seen as
different.
The underscore '_' is considered to be a letter.
.IP identifiers
Identifiers are a sequence of letters and digits, starting with
a letter or a period '.'.
Identifiers can, only once, receive a value through assignment or a
label definition.
.IP strings
Strings are enclosed in single "'" or double """ quotes.
The use of \eddd where ddd is an octal number and \en, \er,
\et, \eb and \ef is allowed and has the same meaning as in the
C language.
.IP numbers
Numbers are a sequence of letters and digits, starting with a
digit.
No difference is made between small and capital letters.
.br
The base of the number is determined in the following way:
.nf
if the number starts with '0x' it is hexadecimal else
    if the number starts with '0' it is octal else
        it's decimal.
.fi
The range of numbers depends on the machine.
A rule of the thumb is that the width of the machine's registers
the same is as the number of bits allowed in numbers.
.IP comment
The character '!' denotes the start of comment, every character
up to the next newline is skipped.
Exclamation marks in strings are not recognized as the start of
comment.
.IP statements
Statements are separated by newlines and ';' and can be
preceded by label definitions.
Label definitions have the form "\fIidentifier\fP:" or
"\fIdigit\fP:".
Statements can be: empty, an assignment, an instruction or a
pseudo-instruction.
.IP assignment
An assignment has the form:
.br
        \fIidentifier\fP = \fIexpression\fP
.br
The identifier receives the value and type of the expression.
.IP instruction
The syntax of an instruction depends on the type of the target
machine.
.IP pseudo-instruction
.de Pu
.sp 1
.ti +5
\&\\$1
.sp 1
..
.Pu ".extern \fIidentifier\fP [, \fIidentifier\fP]*"
The identifiers mentioned in the list are exported and can be
used in other modules.
.Pu ".define \fIidentifier\fP [, \fIidentifier\fP]*"
Used for modules that are to be part of a libary.
The .define pseudo's should be the first in such modules.
When scanning a module in a library the assembler\-loader
checks whether any of its unsatified external references is
mentioned in a .define list. If so, it includes that module in
the program.
The identifiers mentioned in the list are exported and can be
used in other modules.
.Pu ".data1 \fIexpression\fP [, \fIexpression\fP]*"
Initialize a sequence of bytes.
This is not followed by automatic alignment.
.Pu ".data2 \fIexpression\fP [, \fIexpression\fP]*"
Initialize a sequence of shorts (2-byte values).
This is not followed by automatic alignment.
.Pu ".data4 \fIexpression\fP [, \fIexpression\fP]*"
Initialize a sequence of longs (4-byte values).
This is not followed by automatic alignment.
.Pu ".data8 \fIliteralint\fP [, \fIliteralint\fP]*"
Initialize a sequence of long longs (8-byte values).
This accepts only literal integers, not symbols nor expressions; but
a \fIliteralint\fP may be any signed or unsigned 8-byte integer, even
if it is outside the usual range for the machine.
This is not followed by automatic alignment.
.Pu ".dataf4 \fIliteralfloat\fP [, \fIliteralfloat\fP]*"
Initialize a sequence of floats (4-byte values).
The values must be literal floating point constants containing
a dot character.
This is not followed by automatic alignment.
.Pu ".dataf8 \fIliteralfloat\fP [, \fIliteralfloat\fP]*"
Initialize a sequence of doubles (8-byte values).
The values must be literal floating point constants containing
a dot character.
This is not followed by automatic alignment.
.Pu ".ascii \fIstring\fP"
Initialize a sequence of bytes with the value of the bytes in
the string.
This is not followed by automatic alignment.
.Pu ".asciz \fIstring\fP"
Initialize a sequence of bytes with the value of the bytes in
the string and terminate this with an extra zero byte.
This is not followed by automatic alignment.
.Pu ".align [\fIexpression\fP]"
Adjust the current position to a multiple of the value of the
expression.
The default is the word-size of the target machine.
.Pu ".space \fIexpression\fP"
Allocate the indicated amount of bytes.
The expression must be absolute.
.Pu ".comm \fIname\fP,\fIexpression\fP"
Allocate the indicated amount of bytes and assign the location of the first
byte allocated to
.IR name ,
unless
.I name 
is defined elsewhere.
If the scope of
.I name
is extern, then assemblers leave definition of
.I name 
to the linkeditor \fIled\fP(1).
.Pu .sect \fIname\fP
section name definition.
.Pu ".base \fIexpresssion\fP"
Set the starting address of the first of the consecutive segments 
(text) to the value of the expression.
The expression must be absolute.
.Pu .assert \fIexpression\fP
assembly-time assertion checking. Stop with a fatal error message when
the value of the expression is zero.
.Pu .symb, .line, .file
symbolic debug
.Pu .nolist, .list
.br
listing control
.SH "SEE ALSO"
ack(1), arch(1), ack.out(5)
.SH DIAGNOSTICS
Various diagnostics may be produced.
The most likely errors, however, are unresolved references,
probably caused by the omission of a library argument.
.SH BUGS
The alignment might give rise to internal assertion errors when
the alignment requestes is larger than the machine dependent
segment alignment.
.br
Identifiers declared as externals cannot be used as locals in
any following module. This only is a problem for assembler\-loaders.