Assembler directives are instructions to the assembler to perform various
bookkeeping tasks, storage reservation, and other control functions.
To distinquish
them from other instructions, directive names begin with a period.
Table 5-1
lists the assembler directives by category.
Table 5-1: Summary of Assembler Directives
Category | Directives |
Compiler-Use-Only Directives | .alias.bgnb .endb .err.file .gjsrlive .gjsrsaved .lab .livereg .loc .noalias.option .ugen .vreg |
Location Control Directives | .align .data .lit4 .lit8 .rconst .rdata .sdata .space .text |
Symbol Declaration Directives | .extern .globl .struct symbolic
equate
.weakext |
Routine Entry Point Definition Directives | .aent .ent |
Data Storage Directives | .ascii .asciiz .byte .comm .double .d_floating .extended .float .f_floating .gprel32 .g_floating .lcomm .long .quad .s_floating .t_floating .word .x_floating |
Repeat Block Directives | .endr .repeat |
Assembler Option Directive | .set |
Procedure Attribute Directives | .edata .eflag .end .fmask .frame .mask .prologue .save_ra |
Version Control Directive | .verstamp |
Scheduling and Architecture Subset Directives | .arch .tune |
The following list contains descriptions of the assembly directives (in alphabetical order):
Sets an alternate entry point for the current procedure.
Use
this information when you want to generate information for the debugger.
This
directive must appear between a pair of
.ent
and
.end
directives.
(The optional
symno
is for compiler use only.
It refers to a dense number in a
.T
file (symbol table).)
Indicates that memory referenced through the two registers will overlap. The compiler uses this form to improve instruction scheduling.
Sets low-order bits in the location counter to zero. The value of expression establishes the number of bits to be set to zero. The maximum value for expression is four (which produces octaword alignment).
If the
.align
directive advances the location counter,
the assembler fills the skipped bytes with zeros in data sections and
nop
instructions in text sections.
Normally, the
.word
,
.long
,
.quad
,
.float
,
.double
,
.extended
,
.d_floating
,
.f_floating
,
.g_floating
,
.s_floating
,
.t_floating
, and
.x_floating
directives automatically
align their data appropriately.
For example,
.word
does
an implicit
.align 1
, and
.double
does
an implicit
.align 3
.
You can disable the automatic alignment feature with
.align
0
.
The assembler reinstates automatic alignment at the next
.text
,
.data
,
.rdata
, or
.sdata
directive that it encounters.
Labels immediately preceding an automatic or explicit alignment are also realigned. For example:
foo: .align 3 .word 0
This is equivalent to:
.align 3 foo: .word 0
Specifies the version of the Alpha architecture that the assembler
is to generate instructions for.
The valid values for
model
are identical to those you can specify with the
-arch
flag on the
cc
command line.
See
cc
(1)
for details.
Assembles each
string
from the
list into successive locations.
The
.ascii
directive does
not pad the string with null characters.
You must put double quotation marks
(") around each string.
You can optionally use the backslash escape characters.
For a list of the backslash characters, see
Section 2.4.3.
Assembles each string in the list into successive locations and adds a null character. You can optionally use the backslash escape characters. For a list of the backslash characters, see Section 2.4.3.
For use only by compilers.
Sets the beginning
of a language block.
The
.bgnb
and
.endb
directives delimit the scope of a variable set.
The scope can be an entire
procedure, or it can be a nested scope (for example, a "{ }" block
in the C language).
The symbol number
symno
refers
to a dense number in a
.T
file (symbol table).
For an
explanation of
.T
files, see the
Symbol Table/Object File Specification
manual.
Truncates the values of the expressions specified in the comma-separated list to 8-bit values, and assembles the values in successive locations. The values of the expressions must be absolute.
The operands for the
.byte
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is an 8-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
Unless defined elsewhere, name becomes a global common symbol at the head of a block of at least expression bytes of storage. The linker overlays like-named common blocks, using the expression value of the largest block as the byte size of the overlay.
Directs the assembler to add all subsequent data to the
.data
section.
Initializes memory to double-precision (64-bit) VAX D_floating numbers. The values of the expressions must be absolute.
The operands for the
.d_floating
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 64-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.d_floating
directive automatically aligns its
data and any preceding labels on a double-word boundary.
You can disable
this feature with the
.align 0
directive.
Synonym for
.t_floating
.
0
.edata
1
lang-handler relocatable-expression
.edata
2
lang-handler constant-expression
Marks data related to exception handling.
If the flag is
0
, the assembler adds all subsequent
data to the
.xdata
section.
If the flag is
1
or
2
, the assembler
creates a function table entry for the next
.ent
directive.
The function table entry contains the language-specific handler (lang-handler) and data (relocatable-expression
or
constant-expression).
Encodes exception-related flags to be stored in the
PDSC_RPD_FLAGS
field of the procedure's run-time procedure descriptor.
See the
Calling Standard for Alpha Systems
for a description of the individual flags.
Sets the end of a procedure.
The
.ent
directive
sets the beginning of a procedure.
Use the
.ent
and
.end
directives when you want to generate information for the debugger.
Sets the end of a language block.
(See the description of
the
.bgnb
directive for details.
The
.bgnb
directive sets the beginning of a language block.)
Signals the end of a repeat block.
The
.repeat
directive starts a repeat block.
Sets the beginning of the procedure
proc_name.
Use this directive when you want to generate information for
the debugger.
The
.end
directive sets the end of a procedure.
The lex-level operand indicates the number of procedures that statically surround the current procedure. This operand is only informational. It does not affect the assembly process; the assembler ignores it.
For use only by compilers.
Signals an
error.
Any compiler frontend that detects an error condition puts this directive
in the input stream.
When the assembler encounters a
.err
directive, it quietly ceases to assemble the source file.
This prevents the
assembler from continuing to process a program that is incorrect.
Synonym for
.x_floating
.
Indicates that the specified symbol is global and external; that is, the symbol is defined in another object module and cannot be defined until link time. The name operand is a global undefined symbol and number is the expected size of the external object.
Initializes memory to single-precision (32-bit) VAX F_floating numbers. The values of the expressions must be absolute.
The operands for the
.f_floating
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 32-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.f_floating
directive automatically aligns its
data and preceding labels on a longword boundary.
You can disable this feature
by using the
.align 0
directive.
For use only by compilers.
Specifies
the source file from which the assembly instructions that follow originated.
This directive causes the assembler to stop generating line numbers that are
used by the debugger.
A subsequent
.loc
directive causes
the assembler to resume generating line numbers.
Synonym for
.s_floating
.
Sets a mask with a bit turned on for each floating-point register
that the current routine saved.
The least-significant bit corresponds to
register
$f0
.
The
offset
is
the distance, in bytes, from the virtual frame pointer to where the floating-point
registers are saved.
You must use
.ent
before
.fmask
,
and you can use only one
.fmask
for each
.ent
.
Space should be allocated for those registers specified in the
.fmask
.
Describes a stack frame. The first register is the frame register, frame-size is the size of the stack frame, that is, the number of bytes between the frame register and the virtual frame pointer. The second register specifies the register that contains the return address. The local_offset parameter, which is for use only by compilers, specifies the number of bytes between the virtual frame pointer and the local variables.
You must use
.ent
before
.frame
,
and you can use only one
.frame
for each
.ent
.
No stack traces can be done in the debugger without the
.frame
directive.
Initializes memory to double-precision (64-bit) VAX G_floating numbers. The values of the expressions must be absolute.
The operands for the
.g_floating
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 64-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.g_floating
directive automatically aligns its
data and any preceding labels on a quadword boundary.
You can disable this
feature with the
.align 0
directive.
For use only by compilers.
Sets the default
masks for live registers before a procedure call (a
bsr
or
jsr
instruction).
For use only by compilers. Sets the masks that define the registers whose values are preserved during a procedure call. See Table 6-1 and Table 6-2 for the default for integer and floating-point saved registers.
Identifies name as an external symbol. If the name is otherwise defined (for example, by its appearance as a label), the assembler exports the symbol; otherwise, it imports the symbol. In general, the assembler imports undefined symbols; that is, it gives them the UNIX storage class "global undefined" and requires the linker to resolve them.
Truncates the signed displacement between the global pointer value and the addresses specified in the comma-separated list to 32-bit values, and assembles the values in successive locations.
The operands for the
.gprel32
directive can optionally
have the following form:
addressVal [ : addressRep ]
The addressVal is the address value. The optional addressRep is a non-negative expression that specifies how many times to replicate the value of addressVal. The expression value (addressVal) and repetition count (addressRep) must be absolute.
The
.gprel32
directive automatically aligns its data
and preceding labels on a longword boundary.
You can disable this feature
with the
.align 0
directive.
For use only by compilers.
Sets the default
masks for live registers before a procedure's return (a
ret
instruction).
For use only by compilers. Associates a named label with the current location in the program text.
Gives the named symbol (name) a
data type of
bss
.
The assembler allocates the named symbol
to the
bss
area, and the expression defines the named symbol's
length.
If a
.globl
directive also specifies the name,
the assembler allocates the named symbol to external
bss
.
The assembler puts
bss
symbols in one of two
bss
areas.
If the defined size is less than or equal to the size
specified by the assembler or compiler's
-G
command-line
option, the assembler puts the symbols in the
sbss
area.
Allows 4-byte constants to be generated and placed in the
lit4
section.
This directive is only valid for
.long
(with nonrelocatable expressions),
.f_floating
,
.float
, and
.s_floating
.
Allows 8-byte constants to be generated and placed in the
lit4
section.
This directive is only valid for
.quad
(with nonrelocatable expressions),
.d_floating
,
.g_floating
,
.double
, and
.t_floating
.
For use only by compilers.
Affects the
next jump instruction even if it is not the successive instruction.
By default,
external
br
instructions and
jmp
instructions
are treated as external calls; that is, all registers are assumed to be live.
The
.livereg
directive cannot appear before an external
br
instruction because it will affect the next
ret
,
jsr
,
bsr
,
jmp
, or
call_pal callsys
instruction instead of the
br
instruction.
The directive cannot be used before a
call_pal bpt
instruction.
For
call_pal bpt
instructions, the assembler
also assumes that all registers are live.
To avoid unsafe optimizations by the reorganizer,
.livereg
notes to the assembler those registers that are live before a jump.
The directive
.livereg
takes two arguments,
int_bitmask
and
fp_bitmask, which
are 32-bit bitmasks with a bit turned on for each register that is live before
a jump.
The most significant bit corresponds to register
$0
(which is opposite to that used in other assembly directives, for example,
.mask
and
.fmask
).
The first bitmap indicates
live integer registers and the second indicates live floating-point registers.
When present, this directive causes the assembler to be more conservative
and to preserve the indicated register contents.
If omitted, the assembler
assumes the default masks.
The
.livereg
directive can
be coded before any of the following instructions:
bsr
,
jsr
,
ret
,
jmp
, and
call_pal callsys
.
For use only by compilers.
Specifies
the source file and the line within it that corresponds to the assembly instructions
that follow.
The assembler ignores the file number when this directive appears
in the assembly source file.
Then, the assembler assumes that the directive
refers to the most recent
.file
directive.
When a
.loc
directive appears in the binary assembly language
.G
file, the file number is a dense number pointing at a file symbol
in the symbol table
.T
file.
For more information about
.G
and
.T
files, see the
Symbol Table/Object File Specification
manual.
Truncates the values of the expressions specified in the comma-separated list to 32-bit values, and assembles the values in successive locations. The values of the expression can be relocatable.
The operands for the
.long
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 32-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.long
directive automatically aligns its data
and preceding labels on a longword boundary.
You can disable this feature
with the
.align 0
directive.
Sets a mask with a bit turned on for each general-purpose
register that the current routine saved.
The least significant bit corresponds
to register
$0
.
The
offset
is
the distance, in bytes, from the virtual frame pointer to where the registers
are saved.
You must use
.ent
before
.mask
,
and you can use only one
.mask
for each
.ent
.
Space should be allocated for those registers specified in the
.mask
.
Informs the assembler that reg1 and reg2 will never point to the same memory location when they are used as indexed registers. The assembler uses this as a hint to make more liberal assumptions about resource dependency in the program.
For use only by compilers. Informs the assembler that certain options were in effect during compilation. For example, these options can limit the assembler's freedom to perform branch optimizations.
Marks the end of the prologue section of a procedure.
A
flag
of
0
indicates
that the procedure does not use
$gp
; the caller does not
need to set up
$pv
prior to calling the procedure or restore
$gp
on return from the procedure.
A
flag
of
1
indicates
that the procedure does use
$gp
; the caller must set up
$pv
prior to calling the procedure and restore
$gp
on return from the procedure.
If
flag
is not specified, the behavior is
as if a value of
1
was specified.
Truncates the values of the expressions specified in the comma-separated list to 64-bit values, and assembles the values in successive locations. The values of the expressions can be relocatable.
The operands for the
.quad
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 64-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.quad
directive automatically aligns its data
and preceding labels on a quadword boundary.
You can disable this feature
with the
.align 0
directive.
Instructs the assembler to add subsequent data into the
.rconst
section.
(This is the same as the
.rdata
directive except that the entries cannot be relocatable.)
Instructs the assembler to add subsequent data into the
.rdata
section.
Repeats all instructions or data between the
.repeat
and
.endr
directives.
The
expression
defines how many times the enclosing text and data repeats.
With the
.repeat
directive, you cannot use labels, branch
instructions, or values that require relocation in the block.
Also note that
nesting
.repeat
directives is not allowed.
Specifies that
saved_ra_register
is the register in which the return address is saved during the execution
of the procedure.
If
.save_ra
is not used, the saved return
address register is assumed to be the same as the
return_pc_register
argument of the
frame
directive.
The
.save_ra
directive is valid only for register frame procedures.
Instructs the assembler to add subsequent data to the
.sdata
section.
Instructs the assembler to enable or disable certain options.
The assembler has the following default options:
reorder
,
macro
,
move
,
novolatile
, and
at
.
Only one option can be specified by a single
.set
directive.
The effects of the options are as follows:
The
reorder
option permits the assembler
to reorder machine-language instructions to improve performance.
The
noreorder
option prevents the assembler from
reordering machine-language instructions.
If a machine-language instruction
violates the hardware pipeline constraints, the assembler issues a warning
message.
The
macro
option permits the assembler
to generate multiple machine-language instructions from a single assembler
instruction.
The
nomacro
option causes the assembler to print
a warning whenever an assembler operation generates more than one machine-language
instruction.
You must select the
noreorder
option before
using the
nomacro
option; otherwise, an error results.
The
at
option permits the assembler to
use the
$at
register for macros, but generates warnings
if the source program uses
$at
.
When you use the
noat
option and an assembler operation
requires the
$at
register, the assembler issues a warning
message; however, the
noat
option does permit source programs
to use
$at
without warnings being issued.
The
nomove
options instructs the assembler
to mark each subsequent instruction so that it cannot be moved during reorganization.
The assembler can still move instructions from below the
nomove
region to above the region or vice versa.
The
nomove
option
has part of the effect of the "volatile" C declaration; it prevents
otherwise independent loads or stores from occurring in a different order
than intended.
The
move
option cancels the effect of
nomove
.
The
volatile
option instructs the assembler
that subsequent load and store instructions may not be moved in relation to
each other or removed by redundant load removal or other optimization.
The
volatile
option is less restrictive than
noreorder
;
it allows the assembler to move other instructions (that is, instructions
other than load and store instructions) without restrictions.
The
novolatile
option cancels the effect of the
volatile
option.
Initializes memory to single-precision (32-bit) IEEE floating-point numbers. The values of the expressions must be absolute.
The operands for the
.s_floating
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 32-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.s_floating
directive automatically aligns its
data and preceding labels on a longword boundary.
You can disable this feature
with the
.align 0
directive.
Advances the location counter by the number of bytes specified by the value of expression. The assembler fills the space with zeros.
Permits you to lay out a structure using labels plus directives
such as
.word
or
.byte
.
It ends at the
next segment directive (.data
,
.text
,
and so forth).
It does not emit any code or data, but defines the labels
within it to have values that are the sum of
expression
plus their offsets from the
.struct
itself.
Takes one of the following forms: name = expression or name = register. You must define the name only once in the assembly, and you cannot redefine it. The expression must be computable when you assemble the program, and the expression must involve only operators, constants, or equated symbols. You can use the name as a constant in any later statement.
Instructs the assembler to add subsequent code to the
.text
section.
(This is the default.)
Initializes memory to double-precision (64-bit) IEEE floating-point numbers. The values of the expressions must be absolute.
The operands for the
.t_floating
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 64-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.t_floating
directive automatically aligns its
data and any preceding labels on a quadword boundary.
You can disable this
feature with the
.align 0
directive.
Selects processor-specific instruction tuning for various
implementations of the Alpha architecture.
Regardless of the setting of the
.arch
directive, the generated code will run correctly on all implementations
of the Alpha architecture.
The valid values for
option
are identical to those you can specify with the
-arch
flag on the
cc
command line.
See
cc
(1)
for details.
For use only by compilers. Informs the assembler that the source was generated by the code generator.
Specifies the major and minor version numbers; for example,
version 0.15 would be
.verstamp 0 15.
For use only by compilers. Describes a register variable by giving the offset from the virtual frame pointer and the symbol number symno (the dense number) of the surrounding procedure.
Sets name1 to be a weak symbol during linking. If name2 is specified, name1 is created as a weak symbol with the same value as name2. Weak symbols can be silently redefined at link time.
Truncates the values of the expressions specified in the comma-separated list to 16-bit values, and assembles the values in successive locations. The values of the expressions must be absolute.
The operands for the
.word
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 16-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.word
directive automatically aligns its data
and preceding labels on a word boundary.
You can disable this feature with
the
.align 0
directive.
Initializes memory to quad-precision (128-bit) IEEE floating-point numbers. The values of the expressions must be absolute.
The operands for the
.x_floating
directive can optionally
have the following form:
expressionVal [ : expressionRep ]
The expressionVal is a 128-bit value. The optional expressionRep is a non-negative expression that specifies how many times to replicate the value of expressionVal. The expression value (expressionVal) and repetition count (expressionRep) must be absolute.
The
.x_floating
directive automatically aligns its
data and preceding labels on an octaword boundary.
You can disable this feature
with the
.align 0
directive.