273 lines
8.8 KiB
Groff
273 lines
8.8 KiB
Groff
.\" $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 [, identifier]*\fP"
|
|
The identifiers mentioned in the list are exported and can be
|
|
used in other modules.
|
|
.Pu ".define \fIidentifier [, identifier]*\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 [, expression]*\fP"
|
|
Initialize a sequence of bytes.
|
|
This is not followed by automatic alignment.
|
|
.Pu ".data2 \fIexpression [, expression]*\fP"
|
|
Initialize a sequence of shorts (2-byte values).
|
|
This is not followed by automatic alignment.
|
|
.Pu ".data4 \fIexpression [, expression]*\fP"
|
|
Initialize a sequence of longs (4-byte values).
|
|
This is not followed by automatic alignment.
|
|
.Pu ".dataf4 \fIliteralfloat [, literalfloat]*\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 [, literalfloat]*\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.
|