This document describes the usage and input syntax of the UNIX PDP-11 assembler as. The details of the PDP-11 are not described.
The input syntax of the UNIX assembler is generally similar to that of the DEC assembler PAL-11R, although its internal workings and output format are unrelated. It may be useful to read the publication DEC-11-ASDB-D, which describes PAL-11R, although naturally one must use care in assuming that its rules apply to as.
As is a rather ordinary assembler without macro capabilities. It produces an output file that contains relocation information and a complete symbol table; thus the output is acceptable to the UNIX link-editor ld, which may be used to combine the outputs of several assembler runs and to obtain object programs from libraries. The output format has been designed so that if a program contains no unresolved ref%er%ences to external symbols, it is executable without further processing.
as is used as follows:
The other arguments name files which are concatenated and assembled. Thus programs may be written in several pieces and assembled together.
The output of the assembler is by default placed on the file a.out in the current directory; the ``-o'' flag causes the output to be placed on the named file. If there were no unresolved external ref%er%ences, and no errors detected, the output file is marked executable; otherwise, if it is produced at all, it is made non-executable.
Assembler tokens include identifiers (alternatively, ``symbols'' or ``names''), temporary symbols, constants, and operators.
An identifier consists of a sequence of alphanumeric characters (including period ``.'', underscore ``_'', and tilde ``~'' as alphanumeric) of which the first may not be numeric. Only the first eight characters are significant. When a name begins with a tilde, the tilde is discarded and that occurrence of the identifier generates a unique entry in the symbol table which can match no other occurrence of the identifier. This feature is used by the C compiler to place names of local variables in the output symbol table without having to worry about making them unique.
A temporary symbol consists of a digit followed by ``f'' or ``b''. Temporary symbols are discussed fully in §5.1.
An octal constant consists of a sequence of digits; ``8'' and ``9'' are taken to have octal value 10 and 11. The constant is truncated to 16 bits and interpreted in two's complement notation.
A decimal constant consists of a sequence of digits terminated by a decimal point ``.''. The magnitude of the constant should be representable in 15 bits; i.e., be less than 32,768.
A single-character constant consists of a single quote ``''' followed by an ASCII character not a new-line. Certain dual-character escape sequences are acceptable in place of the ASCII character to represent new-line and other non-graphics (see String state%ments, §5.5). The constant's value has the code for the given character in the least significant byte of the word and is null-padded on the left.
A double-character constant consists of a double quote ``"'' followed by a pair of ASCII characters not including new-line. Certain dual-character escape sequences are acceptable in place of either of the ASCII characters to represent new-line and other non-graphics (see String state%ments, §5.5). The constant's value has the code for the first given character in the least significant byte and that for the second character in the most significant byte.
There are several single- and double-character operators; see §6.
Blank and tab characters may be interspersed freely between tokens, but may not be used within tokens (except character constants). A blank or tab is required to separate adjacent identifiers or constants not otherwise separated.
The character ``/'' introduces a comment, which extends through the end of the line on which it appears. Comments are ignored by the assembler.
Assembled code and data fall into three segments: the text segment, the data segment, and the bss segment. The text segment is the one in which the assembler begins, and it is the one into which instructions are typically placed. The UNIX system will, if desired, enforce the purity of the text segment of programs by trapping write operations into it. Object programs produced by the assembler must be processed by the link-editor ld (using its ``-n'' flag) if the text segment is to be write-protected. A single copy of the text segment is shared among all processes executing such a program.
The data segment is available for placing data or instructions which will be modified during execution. Anything which may go in the text segment may be put into the data segment. In programs with write-protected, sharable text segments, data segment contains the initialized but variable parts of a program. If the text segment is not pure, the data segment begins immediately after the text segment; if the text segment is pure, the data segment begins at the lowest 8K byte boundary after the text segment.
The bss segment may not contain any explicitly initialized code or data. The length of the bss segment (like that of text or data) is determined by the high-water mark of the location counter within it. The bss segment is actually an extension of the data segment and begins immediately after it. At the start of execution of a program, the bss segment is set to 0. Typically the bss segment is set up by state%ments exemplified by
One special symbol, ``.'', is the location counter. Its value at any time is the offset within the appropriate segment of the start of the state%ment in which it appears. The location counter may be assigned to, with the restriction that the current segment may not change; furthermore, the value of ``.'' may not decrease. If the effect of the assignment is to increase the value of ``.'', the required number of null bytes are generated (but see Segments above).
A source program is composed of a sequence of state%ments. Statements are separated either by new-lines or by semicolons. There are five kinds of state%ments: null state%ments, expression state%ments, assignment state%ments, string state%ments, and keyword state%ments.
Any kind of state%ment may be preceded by one or more labels.
There are two kinds of label: name labels and numeric labels. A name label consists of a name followed by a colon (:). The effect of a name label is to assign the current value and type of the location counter ``.'' to the name. An error is indicated in pass 1 if the name is already defined; an error is indicated in pass 2 if the ``.'' value assigned changes the definition of the label.
A numeric label consists of a digit 0 to 9 followed by a colon (:). Such a label serves to define temporary symbols of the form ``nb'' and ``nf'', where n is the digit of the label. As in the case of name labels, a numeric label assigns the current value and type of ``.'' to the temporary symbol. However, several numeric labels with the same digit may be used within the same assembly. Ref%er%ences of the form ``nf'' refer to the first numeric label ``n:'' forward from the ref%er%ence; ``nb'' symbols refer to the first ``n:'' label backward from the ref%er%ence. This sort of temporary label was introduced by Knuth [The Art of Computer Programming, Vol I: Fundamental Algorithms]. Such labels tend to conserve both the symbol table space of the assembler and the inventive powers of the programmer.
A null state%ment is an empty state%ment (which may, however, have labels). A null state%ment is ignored by the assembler. Common examples of null state%ments are empty lines or lines containing only a label.
An expression state%ment consists of an arithmetic expression not beginning with a keyword. The assembler computes its (16-bit) value and places it in the output stream, together with the appropriate relocation bits.
An assignment state%ment consists of an identifier, an equals sign (=), and an expression. The value and type of the expression are assigned to the identifier. It is not required that the type or value be the same in pass 2 as in pass 1, nor is it an error to redefine any symbol by assignment.
Any external attribute of the expression is lost across an assignment. This means that it is not possible to declare a global symbol by assigning to it, and that it is impossible to define a symbol to be offset from a non-locally defined global symbol.
As mentioned, it is permissible to assign to the location counter ``.''. It is required, however, that the type of the expression assigned be of the same type as ``.'', and it is forbidden to decrease the value of ``.''. In practice, the most common assignment to ``.'' has the form ``.=.+n'' for some number n; this has the effect of generating n null bytes.
A string state%ment generates a sequence of bytes containing ASCII characters.
A string state%ment consists of a left string quote ``<''
followed by a sequence of ASCII characters not including newline,
followed by a right string quote ``>''.
Any of the ASCII characters may
be replaced by a two-character escape sequence to represent
certain non-graphic characters, as follows:
Keyword state%ments are numerically the most common type, since most machine instructions are of this sort. A keyword state%ment begins with one of the many predefined keywords of the assembler; the syntax of the remainder depends on the keyword. All the keywords are listed below with the syntax they require.
An expression is a sequence of symbols representing a value. Its constituents are identifiers, constants, temporary symbols, operators, and brackets. Each expression has a type.
All operators in expressions are fundamentally binary in nature; if an operand is missing on the left, a 0 of absolute type is assumed. Arithmetic is two's complement and has 16 bits of precision. All operators have equal precedence, and expressions are evaluated strictly left to right except for the effect of brackets.
The operators are:
Expressions may be grouped by use of square brackets ``[]''. (Round parentheses are reserved for address modes.)
The assembler deals with a number of types of expressions. Most types are attached to keywords and used to select the routine which treats that keyword. The types likely to be met explicitly are:
When operands are combined by expression operators, the result has a type which depends on the types of the operands and on the operator. The rules involved are complex to state but were intended to be sensible and predictable. For purposes of expression evaluation the important types are
Further rules applying to particular operators are:
The keywords listed below introduce state%ments that generate data in unusual forms or influence the later operations of the assembler. The metanotation
The expressions in the comma-separated list are truncated to 8 bits and assembled in successive bytes. The expressions must be absolute. This state%ment and the string state%ment above are the only ones that assemble data one byte at at time.
If the location counter ``.'' is odd, it is advanced by one so the next state%ment will be assembled at a word boundary.
The expression must be absolute and defined in pass 1. If its value is nonzero, the .if is ignored; if zero, the state%ments between the .if and the matching .endif (below) are ignored. .if may be nested. The effect of .if cannot extend beyond the end of the input file in which it appears. (The state%ments are not totally ignored, in the following sense: .ifs and .endifs are scanned for, and moreover all names are entered in the symbol table. Thus names occurring only inside an .if will show up as undefined if the symbol table is listed.)
This state%ment marks the end of a conditionally-assembled section of code. See .if above.
This state%ment makes the names external. If they are otherwise defined (by assignment or appearance as a label) they act within the assembly exactly as if the .globl state%ment were not given; however, the link editor ld may be used to combine this routine with other routines that refer these symbols.
Conversely, if the given symbols are not defined within the current assembly, the link editor can combine the output of this assembly with that of others which define the symbols. As discussed in §1, it is possible to force the assembler to make all otherwise undefined symbols external.
These three pseudo-operations cause the assembler to begin assembling into the text, data, or bss segment respectively. Assembly starts in the text segment. It is forbidden to assemble any code or data into the bss segment, but symbols may be defined and ``.'' moved about by assignment.
Provided the name is not defined elsewhere, this state%ment is equivalent to
Because of the rather complicated instruction and addressing structure of the PDP-11, the syntax of machine instruction state%ments is varied. Although the following sections give the syntax in detail, the machine handbooks should be consulted on the semantics.
The syntax of general source and destination
addresses is the same.
Each must have one of the following forms,
where reg is a register symbol, and expr
is any sort of expression:
Notice that mode ``*reg'' is identical to ``(reg)''; that ``*(reg)'' generates an index word (namely, 0); and that addresses consisting of an unadorned expression are assembled as pc-relative ref%er%ences independent of the type of the expression. To force a non-relative ref%er%ence, the form ``*$expr'' can be used, but notice that further indirection is impossible.
The following instructions are defined as absolute symbols:
The following instructions take an expression as operand. The expression must lie in the same segment as the ref%er%ence, cannot be undefined-external, and its value cannot differ from the current location of ``.'' by more than 254 bytes:
The following symbols are followed by an expression representing an address in the same segment as ``.''. If the target address is close enough, a branch-type instruction is generated; if the address is too far away, a jmp will be used.
The following symbols are names of single-operand machine instructions. The form of address expected is discussed in §8.1 above.
The following instructions take a general source and destination (§8.1), separated by a comma, as operands.
The following instructions have more specialized syntax. Here reg is a register name, src and dst a general source or destination (§8.1), and expr is an expression:
The following floating-point operations are defined, with syntax as indicated:
The names of several of the operations have been changed to bring out an analogy with certain fixed-point instructions. The only strange case is movf, which turns into either stf or ldf depending respectively on whether its first operand is or is not a register. Warning: ldf sets the floating condition codes, stf does not.
The symbol ``..'' is the relocation counter. Just before each assembled word is placed in the output stream, the current value of this symbol is added to the word if the word refers to a text, data or bss segment location. If the output word is a pc-relative address word that refers to an absolute location, the value of ``..'' is subtracted.
Thus the value of ``..'' can be taken to mean the starting memory location of the program. The initial value of ``..'' is 0.
The value of ``..'' may be changed by assignment. Such a course of action is sometimes necessary, but the consequences should be carefully thought out. It is particularly ticklish to change ``..'' midway in an assembly or to do so in a program which will be treated by the loader, which has its own notions of ``..''.
System call names are not predefined. They may be found in the file /usr/include/sys.s
When an input file cannot be read, its name followed by a question mark is typed and assembly ceases. When syntactic or semantic errors occur, a single-character diagnostic is typed out together with the line number and the file name in which it occurred. Errors in pass 1 cause cancellation of pass 2. The possible errors are: