123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262 |
- .\" $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 ".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.
|