4.1cBSD/usr/doc/as/asdocs3.me

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

.\"
.\"	Copyright (c) 1982 Regents of the University of California
.\"	@(#)asdocs3.me 1.6 2/11/83
.\"
.EQ
delim $$
.EN
.SH 1 "Pseudo-operations (Directives)"
.pp
The keywords listed below introduce directives or instructions,
and influence the later behavior of the assembler for this statement.
The metanotation
.ce 1
[ stuff ]
.ce 0
means that 0 or more instances of the given
.q stuff
may appear.
.pp
.b Boldface
tokens must appear literally;
words in
.i italic
words are substitutable.
.pp
The pseudo\-operations listed below
are grouped into functional categories.
.SH 2 "Interface to a Previous Pass"
.(b
.in -2n
.TS
lb l.
\&.ABORT
.TE
.in +2n
.)b
.pp
As soon as the assembler sees this directive,
it ignores all further input
(but it does read to the end of file),
and aborts the assembly.
No files are created.
It is anticipated that this would be used in a pipe interconnected
version of a compiler,
where the first major syntax error would
cause the compiler to issue this directive,
saving unnecessary work in assembling code
that would have to be discarded anyway.
.(b
.in -2n
.TS
lb l.
\&.file	$string$
.TE
.in +2n
.)b
.pp
This directive causes the assembler to think it is in file
.i string ,
so error messages reflect the proper source file.
.(b
.in -2n
.TS
lb l.
\&.line	$expression$
.TE
.in +2n
.)b
.pp
This directive causes the assembler to think it is on line
.i expression
so error messages reflect the proper source file.
.pp
The only effect of assembling multiple files specified in the command string
is to insert the
.i file
and
.i line
directives,
with the appropriate values,
at the beginning of the source from each file.
.(b
.in -2n
.TS
lb l.
#	$expression$ $string$
#	$expression$
.TE
.in +2n
.)b
.pp
This is the only instance where a comment is meaningful to the assembler.
The
.q "#"
.ul 1
must
be in the first column.
This meta comment causes the assembler
to believe it is on line
.i expression .
The second argument,
if included,
causes the assembler to believe it is in file
.i string ,
otherwise the current file name does not change.
.SH 2 "Location Counter Control"
.(b
.in -2n
.TS
lb l.
\&.data	[ $expression$ ]
\&.text	[ $expression$ ]
.TE
.in +2n
.)b
.pp
These two pseudo-operations cause the
assembler to begin assembling into the indicated text or data
subsegment.
If specified,
the
.i expression
must be defined and absolute;
an omitted
.i expression
is treated as zero.
The effect of a
.b .data
directive is treated
as a
.b .text
directive if the
.b \-R
assembly flag is set.
Assembly starts in the
.b ".text"
0 subsegment.
.pp
The directives
.b .align
and
.b .org
also control the placement of the location counter.
.sh 2 "Filled Data"
.(b
.in -2n
.TS
lb l.
\&.align	$align\*(USexpr$ [ \fB,\fP $fill\*(USexpr$ ]
.TE
.in +2n
.)b
.pp
The location counter is adjusted
so that the
.i expression
lowest bits of the location counter become zero.
This is done by
assembling from 0 to $2 sup align\*(USexpr$ bytes,
taken from the low order byte of $fill\*(USexpr$.
If present,
$fill\*(USexpr$ must be absolute;
otherwise it defaults to 0.
Thus
.q ".align 2"
pads by null bytes to make the location counter
evenly divisible by 4.
The
.i align_expr
must be defined,
absolute, nonnegative,
and less than 16.
.pp
Warning:
the subsegment concatenation convention
and the current loader conventions
may not preserve attempts at aligning
to more than 2 low-order zero bits.
.(b
.in -2n
.TS
lb l.
\&.org	$org\*(USexpr$ [ \fB,\fP $fill\*(USexpr$ ]
.TE
.in +2n
.)b
.pp
The location counter is set equal to the value of $org\*(USexpr$,
which must be defined and absolute.
The value of the $org\*(USexpr$
must be greater than the current value
of the location counter.
Space between the current value of the location counter
and the desired value are filled with bytes taken from the
low order byte of $fill\*(USexpr$,
which must be absolute and defaults to 0.
.(b
.in -2n
.TS
lb l.
\&.space	$space\*(USexpr$ [ \fB,\fP $fill\*(USexpr$ ]
.TE
.in +2n
.)b
.pp
The location counter is advanced by
$space\*(USexpr$ bytes.
$Space\*(USexpr$ must be defined and absolute.
The space is filled in with bytes taken from the low order
byte of $fill\*(USexpr$,
which must be defined and absolute.
$Fill\*(USexpr$ defaults to 0.
The
.b .fill
directive is a more general way to accomplish the
.b .space
directive.
.(b
.in -2n
.TS
lb l.
\&.fill	$rep\*(USexpr$\fB,\fP $size\*(USexpr$\fB,\fP $fill\*(USexpr$
.TE
.in +2n
.)b
.pp
All three expressions must be absolute.
.i fill\*(USexpr ,
treated as an expression of size
.i size\*(USexpr
bytes,
is assembled and replicated
.i rep\*(USexpr
times.
The effect is to advance the current location counter
.i rep\*(USexpr
\(**
.i size\*(USexpr
bytes.
.i size\*(USexpr
must be between 1 and 8.
.SH 2 "Symbol Definitions"
.SH 2 "Initialized Data"
.(b
.in -2n
.TS
lb l.
\&.byte	$expr$ [ \fB,\fP $expr$ ]
\&.word	$expr$ [ \fB,\fP $expr$ ]
\&.int	$expr$ [ \fB,\fP $expr$ ]
\&.long	$expr$ [ \fB,\fP $expr$ ]
.TE
.in +2n
.)b
.pp
The
.i expression s
in the comma-separated
list are truncated to the size indicated by the key word:
.(b
.in -2n
.TS
center;
c l
cb n.
keyword	length (bits)
_
\&.byte	8
\&.word	16
\&.int	32
\&.long	32
.TE
.in +2n
.)b
and assembled in successive locations.
The
.i expression s
must be absolute.
.pp
Each
.i expression
may optionally be of the form:
.(b
.TS
center;
l.
$expression sub 1$ : $expression sub 2$
.TE
.)b
In this case,
the value of $expression sub 2$ is truncated
to $expression sub 1$ bits,
and assembled in the next $expression sub 1$ bit field
which fits in the natural data size being assembled.
Bits which are skipped because a field does not fit are filled with zeros.
Thus,
.q "\fB.byte\fP 123"
is equivalent to
.q "\fB.byte\fP 8:123" ,
and
.q "\fB.byte\fP 3:1,2:1,5:1"
assembles two bytes, containing the values 9 and 1.
.pp
.b NB:
Bit field initialization with the colon operator is likely
to disappear in future releases of the assembler.
.(b
.in -2n
.TS
lb l.
\&.quad	$number$ [ , $number$ ]
\&.octa	$number$ [ , $number$ ]
\&.float	$number$ [ , $number$ ]
\&.double	$number$ [ , $number$ ]
\&.ffloat	$number$ [ , $number$ ]
\&.dfloat	$number$ [ , $number$ ]
\&.gfloat	$number$ [ , $number$ ]
\&.hfloat	$number$ [ , $number$ ]
.TE
.in +2n
.)b
.pp
These initialize Bignums (see \(sc3.2.2)
in successive locations whose size is a function on the key word.
The type of the Bignums
(determined by the exponent field, or lack thereof)
may not agree with type implied by the key word.
The following table shows the key words,
their size,
and the data types for the Bignums they expect.
.(b
.in -2n
.TS
center;
c  l l l
rb n l l.
keyword	format	length (bits)	valid $number$(s)
_
\&.quad	quad scalar	64	scalar
\&.octa	octal scalar	128	scalar
\&.float	F float	32	F, D and scalar
\&.ffloat	F float	32	F, D and scalar
\&.double	D float	64	F, D and scalar
\&.dfloat	D float	64	F, D and scalar
\&.gfloat	G float	64	G scalar
\&.hfloat	H float	128	H scalar
.TE
.in +2n
.)b
.pp
.i As
will correctly perform other floating point conversions while initializing,
but issues a warning message.
.i As
performs all floating point initializations and conversions
using only the facilities defined
in the original (native) architecture.
.(b
.in -2n
.TS
lb l.
\&.ascii	$string$ [ , $string$]
\&.asciz	$string$ [ , $string$]
.TE
.in +2n
.)b
.pp
Each
.i string
in the list is assembled into successive locations,
with the first letter in the string being placed
into the first location, etc.
The
.b .ascii
directive will not null pad the string;
the
.b .asciz
directive will null pad the string.
(Recall that strings are known by their length,
and need not be terminated with a null,
and that the \*(CL conventions for escaping are understood.)
The
.b .ascii
directive is identical to:
.br
.b .byte
$string sub 0$
.b ,
$string sub 1$
.b ,
$...$
.br
.(b
.in -2n
.TS
lb l.
\&.comm	$name$\fB,\fP $expression$
.TE
.in +2n
.)b
.pp
Provided the
.i name
is not defined elsewhere,
its type is made
.q "undefined external" ,
and its value is
.i expression .
In fact the
.i name
behaves
in the current assembly just like an
undefined external.
However,
the link editor
.i ld
has been special-cased
so that all external symbols which are not otherwise defined,
and which have a non-zero value,
are defined to lie in the bss segment,
and enough space is left after the symbol to hold
.i expression
bytes.
.(b
.in -2n
.TS
lb l.
\&.lcomm	$name$\fB,\fP $expression$
.TE
.in +2n
.)b
.pp
.i expression
bytes will be allocated in the bss segment and
.i name
assigned the location of the first byte,
but the
.i name
is not declared
as global and hence will be unknown to the link editor.
.(b
.in -2n
.TS
lb l.
\&.globl	$name$
.TE
.in +2n
.)b
.pp
This statement makes the
.i name
external.
If it is otherwise defined (by
.b .set
or by
appearance as a label)
it acts within the assembly exactly as if
the
.b .globl
statement were not given;
however,
the link editor may be used
to combine this object module with other modules referring to this symbol.
.pp
Conversely,
if the given symbol is not defined
within the current assembly,
the link editor can combine the output of this assembly
with that of others which define the symbol.
The assembler makes all otherwise
undefined symbols external.
.(b
.in -2n
.TS
lb l.
\&.set	$name$\fB,\fP $expression$
.TE
.in +2n
.)b
.pp
The ($name$, $expression$)
pair is entered into the symbol table.
Multiple
.b .set
statements with the same name are legal;
the most recent value replaces all previous values.
.(b
.in -2n
.TS
lb l.
\&.lsym\&	$name$\fB,\fP $expression$
.TE
.in +2n
.)b
.pp
A unique and otherwise unreferencable instance of the
($name$, $expression$)
pair is created in the symbol table.
The Fortran 77 compiler uses this mechanism to pass local symbol definitions
to the link editor and debugger.
.(b
.in -2n
.TS
lb l.
\&.stabs	$string$, $expr sub 1$, $expr sub 2$, $expr sub 3$, $expr sub 4$
\&.stabn	$expr sub 1$, $expr sub 2$, $expr sub 3$, $expr sub 4$
\&.stabd	$expr sub 1$, $expr sub 2$, $expr sub 3$
.TE
.in +2n
.)b
.pp
The
.i stab
directives place symbols in the symbol table for the symbolic
debugger,
.i sdb \**.
.(f
\**Katseff, H.P.
.i "Sdb: A Symbol Debugger."
Bell Laboratories, Holmdel,
NJ.  April 12, 1979.
.br
Katseff, H.P.
.i "Symbol Table Format for Sdb",
File 39394,
Bell Laboratories, Holmdel, NJ. March 14, 1979.
.)f
A
.q stab
is a 
.i s ymbol
.i tab le
entry.
The
.b .stabs
is a string stab, the
.b .stabn
is a stab not having a string,
and the
.b .stabd
is a 
.q dot
stab that implicitly references
.q dot ,
the current location counter.
.pp
The
.i string
in the
.b .stabs
directive is the name of a symbol.
If the symbol name is zero,
the
.b .stabn
directive may be used instead.
.pp
The other expressions are stored
in the name list structure
of the symbol table
and preserved by the loader for reference by
.i sdb ;
the value of the expressions are peculiar to formats required by
.i sdb .
.nr ii \w'$expr sub 1$\ \ 'u
.ip $expr sub 1$
is used as a symbol table tag
(nlist field
.i n\*(UStype ).
.ip $expr sub 2$
seems to always be zero
(nlist field
.i n\*(USother ).
.ip $expr sub 3$
is used for either the
source line number,
or for a nesting level
(nlist field
.i n\*(USdesc ).
.ip $expr sub 4$
is used as tag specific information
(nlist field
.i n\*(USvalue ).
In the
case of the
.b .stabd
directive, this expression is nonexistent, and
is taken to be the value of the location counter
at the following instruction.
Since there is no associated name for a
.b .stabd
directive,
it can
only be used in circumstances where the name is zero.
The effect of a
.b .stabd
directive can be achieved by one of the other
.b .stab x
directives in the following manner:
.br
$bold .stabn$ $expr sub 1$, $expr sub 2$, $expr sub 3$, $roman LL n$
.br
$roman LL n bold :$
.pp
The
.b .stabd
directive is preferred,
because it does not clog the symbol
table with labels used only for the stab symbol entries.