V3/man/manx/as.1

Compare this file to the similar file:
Show the results in this format: 

.pa 1
.he '1/15/73''AS (I)'
.ti 0
NAME		as -- assembler
.sp
.ti 0
SYNOPSIS	as__ [ -_ ] name918 ...
.sp
.ti 0
DESCRIPTION	as__
assembles the concatenation of name\d1\u, ....  as__
is based on the DEC-provided assembler PAL-11R [1], although
it was coded locally.
Therefore, only the differences will be recorded.
.sp
If the optional first argument
-_ is used,
all undefined symbols in the assembly
are treated as global.
.sp
Character changes are:
.sp
     for    use
      @      *
      #      $
      ;      /
.sp
In as__, the character ";" is a logical new line; several operations
may appear on one line if separated by ";".
Several new expression operators have been provided:
.sp
     \\>     right shift (logical)
     \\<     left shift
     *      multiplication
     \\/     division
.nf
     %      remainder (no longer means "register")
     |      inclusive or
.fi
     !      one's complement
     []     parentheses for grouping
.nf
     ^      result has value of left, type of right
.sp
.fi
For example location 0 (relocatable) can be written "0^.";
another way to denote register 2 is "2^r0".

All of the preceding operators are binary; if
a left operand is missing, it is taken
to be 0.
The "!" operator adds its left operand to the one's
complement of its right operand.

All operators evaluate left-to-right except for
the effect of brackets; all operators have the
same priority.

There is a conditional assembly operation code different
from that of PAL-11R (whose conditionals are not provided):
.sp
     .if expression
     ...
     .endif
.sp
If the expression__________ evaluates to non-zero, the section of
code between the ".if" and the ".endif" is assembled; otherwise
it is ignored.  ".if"s may be nested.
.sp
Temporary labels like those introduced by Knuth [2] may
be employed.
A temporary label is defined as follows:
.sp
     n:
.sp
where n_ is a digit 0 ... 9.  Symbols of the form "n_f" refer to the
first label "n_:" following the use of the symbol; those
of the form "n_b" refer to the last "n_:".  The same "n_" may
be used many times.
Labels of this form are less taxing both on the
imagination of the programmer and on the symbol table space
of the assembler.
.sp
The PAL-11R opcodes ".word", ".eot" and ".end" are redundant and are omitted.
.sp
The symbols
.sp
     r0 ... r5
     fr0 ... fr5 (floating-point registers)
     sp
     pc
     ..
.sp
are predefined with appropriate values.
".." is the relocation constant and is added to
each relocatable reference.
On a PDP-11 with relocation hardware, its value is
0; on most systems without protection,
its value is 40000(8).
.sp
The new opcode "sys" is used to specify system
calls.
Names for system calls are predefined.
See section (II).
.sp
The opcodes "bes" (branch on error set)
and "bec" (branch on error clear)
are defined to test the error status bit
set on return from system calls.
.sp
Strings of characters may be assembled in a way more
convenient than PAL-11's ".ascii" operation (which is,
therefore, omitted).  Strings are included between the
string quotes "<" and ">":
.sp
     <here is a string>
.sp
Escape sequences exist to enter non graphic
and other difficult characters.  These sequences are
also effective in single and double character constants introduced
by single (') and double (") quotes respectively.
.sp
     use___  for___
     \\n   newline (012)
     \\0   NULL (000)
     \\>   >
     \\t   TAB (011)
     \\a   ACK (006)
     \\r   CR (015)
     \\p   ESC (033)
     \\\\   \\ (134)
.sp
as__ provides a primitive segmentation facility.
There are three segments: text____, data____ and
bss___.
The text segment is ordinarily used for
code.  The data segment is provided
for initialized but variable data.
The bss segment cannot be initialized, but
symbols may be defined to lie within this 
segment.
In the future, it is expected that the
text segment will be write-protected and sharable.
Assembly begins in the text segment.
The pseudo-operations

	.text
	.data
	.bss

cause the assembler
to switch to the text, data, or bss segment respectively.
Segmentation is useful at present
for two reasons:
Non-initialized
tables and variables, if placed
in the bss segment, occupy no space in the
output file.
Also, alternative use of the
text and data segments provides a primitive
dual location-counter feature.

In the output file, all text-segment information comes
first, followed by all data-segment information,
and finally bss information.
Within each segment, information appears in
the order written.

Note:
since nothing explicit can be assembled
into the bss segment, the usual appearance
of this segment is in the following style:

	.bss
	var1:	.=.+2
	tab1:	.=.+100.
	...

That is, space is reserved but nothing explicit
is placed in it.

As is evident from the example, it is legal to
assign to the location counter ".".
It is also permissible in segments other than ".bss".
The restriction is made, however,
that the value so assigned must be defined
in the first pass and it must be a value
associated with the same segment as ".".

The pseudo-op

	.comm	symbol,expression

makes symbol______ an undefined global symbol,
and places the value of the expression in
the value field of the symbol's definition.
Thus the above declaration is equivalent to

	.globl	symbol
	symbol = expression ^ symbol

The treatment of such a symbol by the loader ld(I)
is as follows:
If another routine in the same load defines the symbol to be an ordinary
text, data, bss, or absolute symbol,
that definition takes precedence and the symbol
acts like a normal undefined external.
If however no other routine defines the symbol, the loader
defines it as an external bss-segment symbol
and reserves n_ bytes after its location,
where n_ is the value of the expression in the .comm
operation.
Thus ".comm x,100"
effectively declares x to be a common region 100
bytes long.
Note: all such declarations for the same symbol
in various routines should request the same amount
of space.
.sp
The binary output of the assembler is placed on the file "a.out" in the
current directory.
a.out_____ also contains the symbol table from the assembly
and relocation bits.
The output of the assembler is executable immediately
if the assembly was error-free and if there were no
unresolved external references.
The link editor ld__ may be used to combine several
assembly outputs and resolve global symbols.
.sp
The assembler does not produce a listing of the source program.
This is not a serious drawback; the debugger db__ discussed
below is sufficiently powerful to render a printed
octal translation of the source unnecessary.

On the last pages of this section is a list of all the assembler's
built-in symbols.
In the case of instructions, the addressing modes
are as follows:

.nf
	src, dst	source, destination
	r		general register
	fsrc,fdst	floating source, destination
	fr		floating register
	exp		expression

.fi
The names of certain 11/45 opcodes are different
from those in the 11/45 manual
to draw analogies with existing 11/20 instructions.
..pa +2

.ti 0
FILES		/etc/as2	pass 2 of the assembler
.br
/tmp/atm1?	temporary
.br
/tmp/atm2?	temporary
.br
/tmp/atm3?	temporary
.br
a.out		object
.sp
.ti 0
SEE ALSO	ld(I),
nm(I),
sh(I),
un(I),
db(I),
a.out(V),
[1] PAL-11R Assembler;
DEC-11-ASDB-D,
[2] Knuth,
.ul
The Art of Computer Programming,
Vol. I; Fundamental Algorithms.,
"UNIX Assembler Manual" (in preparation).
.sp
.ti 0
DIAGNOSTICS	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:
.sp
.in +6
.ti -6
)  parentheses error
.ti -6
]  parentheses error
.ti -6
<  String not terminated properly
.ti -6
*  Indirection ("*_") used illegally
.ti -6
.li
.  Illegal assignment to "."
.ti -6
A  error in A_ddress
.ti -6
B  B_ranch instruction is odd or too remote
.ti -6
E  error in E_xpression
.ti -6
F  error in local ("F_" or "b") type symbol
.ti -6
G  G_arbage (unknown) character
.ti -6
I  End of file inside an If__
.ti -6
M  M_ultiply defined symbol as label
.ti -6
O  O_dd-- word quantity assembled at odd address
.ti -6
P  P_hase error-- "." different in pass 1 and 2
.ti -6
R  R_elocation error
.ti -6
U  U_ndefined symbol
.ti -6
X  syntaX_ error
.in -6
.sp
.ti 0
BUGS		Symbol table overflow is not checked.
.sp
If "." is moved backwards by an odd number of bytes,
relocation bits are corrupted.