5 Assembler Directives

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	`.bgnb .endb .file .gjsrlive .gjsrsaved .lab .livereg .loc .option .ugen .vreg`
Location Control Directives	`.align .data .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 .lit4 .lit8 .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):

.aent name [,symno]: 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).)

.alias reg1, reg2: Indicates that memory referenced through the two registers will overlap. The compiler uses this form to improve instruction scheduling.

.align expression

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

is the same as

.align 3
foo: .word 0

.arch model: 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.

.ascii string [ , string ] ...: Assembles each string from the list into successive locations. The .ascii directive does not pad the string with null characters. You must put 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.

.asciiz string [ , string ] ...: 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.

.bgnb symno: 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 Chapter 8.

.byte expression1 [,expression2] ... [expressionN]

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.

.comm name, expression: 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.

.data: Directs the assembler to add all subsequent data to the .data section.

.d_floating expression1 [,expression2] ... [expressionN]

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 .

.double expression1 [,expression2] ... [expressionN]: Synonym for .t_floating.

.edata 0
.edata 1 lang-handler relocatable-expression
.edata 2 lang-handler constant-expression

Marks data related to exception handling.

If flag is zero, the assembler adds all subsequent data to the .xdata section.

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

.eflag flags: Encodes exception-related flags to be stored in the PDSC_RPD_FLAGS field of the procedure's run-time procedure descriptor. Refer to the Calling Standard for Alpha Systems for a description of the individual flags.

.end [ proc_name ]: 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.

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

.endr: Signals the end of a repeat block. The .repeat directive starts a repeat block.

.ent proc_name [ lex-level ]: 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.

.err: For use only by compilers. Signals an error. Any compiler front-end 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.

.extended expression1 [,expression2] ... [expressionN]: Synonym for .x_floating.

.extern name [ number ]: 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.

.f_floating expression1 [,expression2] ... [expressionN]

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.

.file file_number file_name_string: 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.

.float expression1 [,expression2] ... [expressionN]: Synonym for .s_floating.

.fmask mask offset: 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.

.frame frame-register frame-size return_pc-register [local_offset]: 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.

.g_floating expression1 [,expression2] ... [expressionN]

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

.gjsrlive: For use only by compilers. Sets the default masks for live registers before a procedure call (a bsr or jsr instruction).

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

.globl name: 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.

.gprel32 address1[, address2] ... [,addressN]

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.

.gretlive: For use by compilers. Sets the default masks for live registers before a procedure's return (a ret instruction).

.lab label_name: For use only by compilers. Associates a named label with the current location in the program text.

.lcomm name, expression: 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.

.lit4: Allows 4-byte constants to be generated and placed in the lit4 section. This directive is only valid for .long (with non-relocatable expressions), .f_floating, .float, and .s_floating.

.lit8: Allows 8-byte constants to be generated and placed in the lit4 section. This directive is only valid for .quad (with non-relocatable expressions), .d_floating, .g_floating, .double, and .t_floating.

.livereg int_bitmask fp_bitmask

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.

.loc file_number line_number: 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 Chapter 8.

.long expression1 [,expression2] ... [expressionN]

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 .long directive automatically aligns its data and preceding labels on a longword boundary. You can disable this feature with the
.align 0 directive.

.mask mask, offset: 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.

.noalias reg1, reg2: 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.

.option options: 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.

.prologue flag

Marks the end of the prologue section of a procedure.

A flag of zero 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 one 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 one was specified.

.quad expression1 [,expression2] ... [expressionN]

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 .quad directive automatically aligns its data and preceding labels on a quadword boundary. You can disable this feature with the .align 0 directive.

.rdata: Instructs the assembler to add subsequent data into the .rdata section.

.repeat expression: 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.

.save_ra saved_ra_register: 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.

.sdata: Instructs the assembler to add subsequent data to the .sdata section.

.set option

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.

.s_floating expression1 [,expression2] ... [expressionN]

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 .s_floating directive automatically aligns its data and preceding labels on a longword boundary. You can disable this feature with the .align 0 directive.

.space expression: Advances the location counter by the number of bytes specified by the value of expression. The assembler fills the space with zeros.

.struct expression: 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.

symbolic equate: 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 the name. 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.

.text: Instructs the assembler to add subsequent code to the .text section. (This is the default.)

.t_floating expression1 [,expression2] ... [expressionN]

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

.tune option: 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.

.ugen: For use only by compilers. Informs the assembler that the source was generated by the code generator.

.verstamp major minor: Specifies the major and minor version numbers; for example, version 0.15 would be .verstamp 0 15.

.vreg register offset symno: 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.

.weakext name1 [,name2]: 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.

.word expression1 [,expression2] ... [expressionN]

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.

.x_floating expression1 [,expression2] ... [expressionN]

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.