Alpha Dependent Features
************************

Notes
=====

The documentation here is primarily for the ELF object format. AS also supports the ECOFF and EVAX formats, but features specific to these formats are not yet documented.

Options
=======

-mCPU
     This option specifies the target processor.  If an attempt is made to assemble an instruction which will not execute on the target processor, the assembler may either expand the instruction as a macro or issue an error message.  This option is equivalent to the .arch directive.

     The following processor names are recognized: 21064, 21064a, 21066, 21068, 21164, 21164a, 21164pc, 21264, 21264a, 21264b, ev4, ev5, lca45, ev5, ev56, pca56, ev6, ev67, ev68. The special name all may be used to allow the assembler to accept instructions valid for any Alpha processor.

     In order to support existing practice in OSF/1 with respect to .arch, and existing practice within MILO (the Linux ARC bootloader), the numbered processor names (e.g. 21064) enable the processor-specific PALcode instructions, while the ``electro-vlasic'' names (e.g. ev4) do not.

-mdebug
-no-mdebug
     Enables or disables the generation of .mdebug encapsulation for stabs directives and procedure descriptors.  The default is to automatically enable .mdebug when the first stabs directive is seen.

-relax
     This option forces all relocations to be put into the object file, instead of saving space and resolving some relocations at assembly time.  Note that this option does not propagate all symbol arithmetic into the object file, because not all symbol arithmetic can be represented.  However, the option can still be useful in specific applications.

-g
     This option is used when the compiler generates debug information.  When gcc is using mips-tfile to generate debug information for ECOFF, local labels must be passed through to the object file.  Otherwise this option has no effect.

-GSIZE
     A local common symbol larger than SIZE is placed in .bss, while smaller symbols are placed in .sbss.

-F
-32addr
     These options are ignored for backward compatibility.

Syntax
======

The assembler syntax closely follow the Alpha Reference Manual; assembler directives and general syntax closely follow the OSF/1 and OpenVMS syntax, with a few differences for ELF.

Special Characters
------------------

# is the line comment character.

; can be used instead of a newline to separate statements.

Register Names
--------------

The 32 integer registers are refered to as $N or $rN.  In addition, registers 15, 28, 29, and 30 may be refered to by the symbols $fp, $at, $gp, and $sp respectively.

The 32 floating-point registers are refered to as $fN.

Relocations
-----------

Some of these relocations are available for ECOFF, but mostly only for ELF.  They are modeled after the relocation format introduced in Digial Unix 4.0, but there are additions.

The format is !TAG or !TAG!NUMBER where TAG is the name of the relocation.  In some cases NUMBER is used to relate specific instructions.

The relocation is placed at the end of the instruction like so:

     ldah  $0,a($29)    !gprelhigh
     lda   $0,a($0)     !gprellow
     ldq   $1,b($29)    !literal!100
     ldl   $2,0($1)     !lituse_base!100

!literal
!literal!N
     Used with an ldq instruction to load the address of a symbol from the GOT.

     A sequence number N is optional, and if present is used to pair lituse relocations with this literal relocation.  The lituse relocations are used by the linker to optimize the code based on the final location of the symbol.

     Note that these optimizations are dependent on the data flow of the program.  Therefore, if any lituse is paired with a literal relocation, then all uses of the register set by the literal instruction must also be marked with lituse relocations.  This is because the original literal instruction may be deleted or transformed into another instruction.

     Also note that there may be a one-to-many relationship between literal and lituse, but not a many-to-one.  That is, if there are two code paths that load up the same address and feed the value to a single use, then the use may not use a lituse relocation.

!lituse_base!N
     Used with any memory format instruction (e.g. ldl) to indicate that the literal is used for an address load.  The offset field of the instruction must be zero.  During relaxation, the code may be altered to use a gp-relative load.

!lituse_jsr!N
     Used with a register branch format instruction (e.g. jsr) to indicate that the literal is used for a call.  During relaxation, the code may be altered to use a direct branch (e.g. bsr).

!lituse_bytoff!N
     Used with a byte mask instruction (e.g. extbl) to indicate that only the low 3 bits of the address are relevant.  During relaxation, the code may be altered to use an immediate instead of a register shift.

!lituse_addr!N
     Used with any other instruction to indicate that the original address is in fact used, and the original ldq instruction may not be altered or deleted.  This is useful in conjunction with lituse_jsr to test whether a weak symbol is defined.

          ldq  $27,foo($29)   !literal!1
          beq  $27,is_undef   !lituse_addr!1
          jsr  $26,($27),foo  !lituse_jsr!1

!lituse_tlsgd!N
     Used with a register branch format instruction to indicate that the literal is the call to __tls_get_addr used to compute the address of the thread-local storage variable whose descriptor was loaded with !tlsgd!N.

!lituse_tlsldm!N
     Used with a register branch format instruction to indicate that the literal is the call to __tls_get_addr used to compute the address of the base of the thread-local storage block for the current module.  The descriptor for the module must have been loaded with !tlsldm!N.

!gpdisp!N
     Used with ldah and lda to load the GP from the current address, a-la the ldgp macro.  The source register for the ldah instruction must contain the address of the ldah instruction.  There must be exactly one lda instruction paired with the ldah instruction, though it may appear anywhere in the instruction stream.  The immediate operands must be zero.

          bsr  $26,foo
          ldah $29,0($26)     !gpdisp!1
          lda  $29,0($29)     !gpdisp!1

!gprelhigh
     Used with an ldah instruction to add the high 16 bits of a 32-bit displacement from the GP.

!gprellow
     Used with any memory format instruction to add the low 16 bits of a 32-bit displacement from the GP.

!gprel
     Used with any memory format instruction to add a 16-bit displacement from the GP.

!samegp
     Used with any branch format instruction to skip the GP load at the target address.  The referenced symbol must have the same GP as the source object file, and it must be declared to either not use $27 or perform a standard GP load in the first two instructions via the .prologue directive.

!tlsgd
!tlsgd!N
     Used with an lda instruction to load the address of a TLS descriptor for a symbol in the GOT.

     The sequence number N is optional, and if present it used to pair the descriptor load with both the literal loading the address of the __tls_get_addr function and the lituse_tlsgd marking the call to that function.

     For proper relaxation, both the tlsgd, literal and lituse relocations must be in the same extended basic block. That is, the relocation with the lowest address must be executed first at runtime.

!tlsldm
!tlsldm!N
     Used with an lda instruction to load the address of a TLS descriptor for the current module in the GOT.

     Similar in other respects to tlsgd.

!gotdtprel
     Used with an ldq instruction to load the offset of the TLS symbol within its module's thread-local storage block.  Also known as the dynamic thread pointer offset or dtp-relative offset.

!dtprelhi
!dtprello
!dtprel
     Like gprel relocations except they compute dtp-relative offsets.

!gottprel
     Used with an ldq instruction to load the offset of the TLS symbol from the thread pointer.  Also known as the tp-relative offset.

!tprelhi
!tprello
!tprel
     Like gprel relocations except they compute tp-relative offsets.

Floating Point
==============

The Alpha family uses both IEEE and VAX floating-point numbers.

Alpha Assembler Directives
==========================

AS for the Alpha supports many additional directives for compatibility with the native assembler.  This section describes them only briefly.

These are the additional directives in AS for the Alpha:

.arch CPU
     Specifies the target processor.  This is equivalent to the -mCPU command-line option.  See Options, for a list of values for CPU.

.ent FUNCTION[, N]
     Mark the beginning of FUNCTION.  An optional number may follow for compatibility with the OSF/1 assembler, but is ignored.  When generating .mdebug information, this will create a procedure descriptor for the function.  In ELF, it will mark the symbol as a function a-la the generic .type directive.

.end FUNCTION
     Mark the end of FUNCTION.  In ELF, it will set the size of the symbol a-la the generic .size directive.

.mask MASK, OFFSET
     Indicate which of the integer registers are saved in the current function's stack frame.  MASK is interpreted a bit mask in which bit N set indicates that register N is saved.  The registers are saved in a block located OFFSET bytes from the canonical frame address (CFA) which is the value of the stack pointer on entry to the function.  The registers are saved sequentially, except that the return address register (normally $26) is saved first.

     This and the other directives that describe the stack frame are currently only used when generating .mdebug information.  They may in the future be used to generate DWARF2 .debug_frame unwind information for hand written assembly.

.fmask MASK, OFFSET
     Indicate which of the floating-point registers are saved in the current stack frame.  The MASK and OFFSET parameters are interpreted as with .mask.

.frame FRAMEREG, FRAMEOFFSET, RETREG[, ARGOFFSET]
     Describes the shape of the stack frame.  The frame pointer in use is FRAMEREG; normally this is either $fp or $sp.  The frame pointer is FRAMEOFFSET bytes below the CFA.  The return address is initially located in RETREG until it is saved as indicated in .mask.  For compatibility with OSF/1 an optional ARGOFFSET parameter is accepted and ignored.  It is believed to indicate the offset from the CFA to the saved argument registers.

.prologue N
     Indicate that the stack frame is set up and all registers have been spilled.  The argument N indicates whether and how the function uses the incoming procedure vector (the address of the called function) in $27.  0 indicates that $27 is not used; 1 indicates that the first two instructions of the function use $27 to perform a load of the GP register; 2 indicates that $27 is used in some non-standard way and so the linker cannot elide the load of the procedure vector during relaxation.

.gprel32 EXPRESSION
     Computes the difference between the address in EXPRESSION and the GP for the current object file, and stores it in 4 bytes.  In addition to being smaller than a full 8 byte address, this also does not require a dynamic relocation when used in a shared library.

.t_floating EXPRESSION
     Stores EXPRESSION as an IEEE double precision value.

.s_floating EXPRESSION
     Stores EXPRESSION as an IEEE single precision value.

.f_floating EXPRESSION
     Stores EXPRESSION as a VAX F format value.

.g_floating EXPRESSION
     Stores EXPRESSION as a VAX G format value.

.d_floating EXPRESSION
     Stores EXPRESSION as a VAX D format value.

.set FEATURE
     Enables or disables various assembler features.  Using the positive name of the feature enables while using noFEATURE disables.

     at
          Indicates that macro expansions may clobber the assembler temporary ($at or $28) register.  Some macros may not be expanded without this and will generate an error message if noat is in effect.  When at is in effect, a warning will be generated if $at is used by the programmer.

     macro
          Enables the expasion of macro instructions.  Note that variants of real instructions, such as br label vs br $31,label are considered alternate forms and not macros.

     move
     reorder
     volatile
          These control whether and how the assembler may re-order instructions. Accepted for compatibility with the OSF/1 assembler, but AS does not do instruction scheduling, so these features are ignored.

The following directives are recognized for compatibility with the OSF/1 assembler but are ignored.

     .proc           .aproc
     .reguse         .livereg
     .option         .aent
     .ugen           .eflag
     .alias          .noalias

Opcodes
=======

For detailed information on the Alpha machine instruction set, see the Alpha Architecture Handbook (ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf).