Copyright (c) 1982 The Regents of the University of California.
All rights reserved.

%sccs.include.redist.roff%

@(#)asdocs3.me 5.1 (Berkeley) 04/17/91

delim $$ .EN .pp The keywords listed below introduce directives or instructions, and influence the later behavior of the assembler for this statement. The metanotation

1 [ stuff ]

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.

.(b

.ABORT

.)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

.file $string$

.)b .pp This directive causes the assembler to think it is in file .i string , so error messages reflect the proper source file. .(b

.line $expression$

.)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

# $expression$ $string$

# $expression$

.)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. .(b

.data [ $expression$ ]

.text [ $expression$ ]

.)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

.align $align\*(USexpr$ [ , $fill\*(USexpr$ ]

.)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

.org $org\*(USexpr$ [ , $fill\*(USexpr$ ]

.)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

.space $space\*(USexpr$ [ , $fill\*(USexpr$ ]

.)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

.fill $rep\*(USexpr$, $size\*(USexpr$, $fill\*(USexpr$

.)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. .(b

.byte $expr$ [ , $expr$ ]

.word $expr$ [ , $expr$ ]

.int $expr$ [ , $expr$ ]

.long $expr$ [ , $expr$ ]

.)b .pp The .i expression s in the comma-separated list are truncated to the size indicated by the key word: .(b

keyword length (bits)

.byte 8

.word 16

.int 32

.long 32

.)b and assembled in successive locations. The .i expression s must be absolute. .pp Each .i expression may optionally be of the form: .(b

$expression sub 1$ : $expression sub 2$

.)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 ".byte 123" is equivalent to .q ".byte 8:123" , and .q ".byte 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

.quad $number$ [ , $number$ ]

.octa $number$ [ , $number$ ]

.float $number$ [ , $number$ ]

.double $number$ [ , $number$ ]

.ffloat $number$ [ , $number$ ]

.dfloat $number$ [ , $number$ ]

.gfloat $number$ [ , $number$ ]

.hfloat $number$ [ , $number$ ]

.)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

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

.)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

.ascii $string$ [ , $string$]

.asciz $string$ [ , $string$]

.)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:

.b .byte $string sub 0$ .b , $string sub 1$ .b , $...$

.(b

.comm $name$, $expression$

.)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

.lcomm $name$, $expression$

.)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

.globl $name$

.)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

.set $name$, $expression$

.)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

.lsym $name$, $expression$

.)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

.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$

.)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.

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:

$bold .stabn$ $expr sub 1$, $expr sub 2$, $expr sub 3$, $roman LL n$

$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.