UNI_ASS(6ACK)

NAME
uni_ass - universal assembler, assembler-loader

SYNOPSIS
~em/lib/mach/as [options] argument ...

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, arch(1) libraries.
Flags are:

-donum
    This option controls the listing. Default is no listing. Onum is interpreted as an octal number. Each bit controls part of the listing as follows:
    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
Thus bits in 0 to 8 control the listing format and bit 9 forces a complete listing. If onum is omitted or is 000 it is interpreted as 0700. If onum is 1000 it is interpreted as 1700.
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.

-s[onum]
    This option controls the amount of symbolic debug information generated. Onum is interpreted as an octal number. The bits have the following meaning:
    001: external symbols
    002: local symbols
    004: local, compiler generated labels
    010: symbols defined in
    .symb
    pseudo instruction
    020: records for
    .line
    and
    .file
    statements
    040: section names
Default is 073: all except local compiler labels.

-r  Generate relocation information, for assemblers-loaders that can. Assemblers always produce relocation information.

-b  Turn off branch optimization.

-oname

-"o name is taken as the name of the resulting load file. The default name is a.out.

The assembler-loaders assemble and link together assembly language modules machine from files and libraries, producing an ack.out(5) format file, without relocation information. The assemblers produce a relocatable ack.out(5) format file.

Two different types of arguments are allowed:

1-  Assembly language modules
2-  UNIX archives, as maintained by arch(1). These archives must only contain assembly language modules with .define as their first statement. These are only accepted by assembler-loaders.

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 led(1).

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 .sect. 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 led(1).

SYNTAX

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.

letters
    Both upper and lower case may be used and are seen as different. The underscore '_' is considered to be a letter.

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.

strings
    Strings are enclosed in single "'" or double """ quotes. The use of \ddd where ddd is an octal number and \n, \r, \t, \b and \f is allowed and has the same meaning as in the C language.

numbers
    Numbers are a sequence of letters and digits, starting with a digit. No difference is made between small and capital letters.
    The base of the number is determined in the following way:
    if the number starts with '0x' it is hexadecimal else
        if the number starts with '0' it is octal else
            it's decimal.
    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.

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.

statements
    Statements are separated by newlines and ';' and can be preceded by label definitions. Label definitions have the form "identifier:" or "digit:". Statements can be: empty, an assignment, an instruction or a pseudo-instruction.

assignment
    An assignment has the form:
            identifier = expression
    The identifier receives the value and type of the expression.

instruction
    The syntax of an instruction depends on the type of the target machine.

pseudo-instruction
    The identifiers mentioned in the list are exported and can be used in other modules. 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. Initialize a sequence of bytes. This is not followed by automatic alignment. Initialize a sequence of shorts (2-byte values). This is not followed by automatic alignment. Initialize a sequence of longs (4-byte values). This is not followed by automatic alignment. Initialize a sequence of bytes with the value of the bytes in the string. This is not followed by automatic alignment. 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. Adjust the current position to a multiple of the value of the expression. The default is the word-size of the target machine. Allocate the indicated amount of bytes. The expression must be absolute. Allocate the indicated amount of bytes and assign the location of the first byte allocated to name, unless name is defined elsewhere. If the scope of name is extern, then assemblers leave definition of name to the linkeditor led(1). section name definition. Set the starting address of the first of the consecutive segments (text) to the value of the expression. The expression must be absolute. assembly-time assertion checking. Stop with a fatal error message when the value of the expression is zero. symbolic debug
    listing control

SEE ALSO
ack(1), arch(1), ack.out(5)

DIAGNOSTICS
Various diagnostics may be produced. The most likely errors, however, are unresolved references, probably caused by the omission of a library argument.

BUGS
The alignment might give rise to internal assertion errors when the alignment requestes is larger than the machine dependent segment alignment.
Identifiers declared as externals cannot be used as locals in any following module. This only is a problem for assembler-loaders.