1@c Copyright 2002, 2003 2@c Free Software Foundation, Inc. 3@c This is part of the GAS manual. 4@c For copying conditions, see the file as.texinfo. 5 6@ifset GENERIC 7@page 8@node Alpha-Dependent 9@chapter Alpha Dependent Features 10@end ifset 11 12@ifclear GENERIC 13@node Machine Dependencies 14@chapter Alpha Dependent Features 15@end ifclear 16 17@cindex Alpha support 18@menu 19* Alpha Notes:: Notes 20* Alpha Options:: Options 21* Alpha Syntax:: Syntax 22* Alpha Floating Point:: Floating Point 23* Alpha Directives:: Alpha Machine Directives 24* Alpha Opcodes:: Opcodes 25@end menu 26 27@node Alpha Notes 28@section Notes 29@cindex Alpha notes 30@cindex notes for Alpha 31 32The documentation here is primarily for the ELF object format. 33@code{@value{AS}} also supports the ECOFF and EVAX formats, but 34features specific to these formats are not yet documented. 35 36@node Alpha Options 37@section Options 38@cindex Alpha options 39@cindex options for Alpha 40 41@table @option 42@cindex @code{-m@var{cpu}} command line option, Alpha 43@item -m@var{cpu} 44This option specifies the target processor. If an attempt is made to 45assemble an instruction which will not execute on the target processor, 46the assembler may either expand the instruction as a macro or issue an 47error message. This option is equivalent to the @code{.arch} directive. 48 49The following processor names are recognized: 50@code{21064}, 51@code{21064a}, 52@code{21066}, 53@code{21068}, 54@code{21164}, 55@code{21164a}, 56@code{21164pc}, 57@code{21264}, 58@code{21264a}, 59@code{21264b}, 60@code{ev4}, 61@code{ev5}, 62@code{lca45}, 63@code{ev5}, 64@code{ev56}, 65@code{pca56}, 66@code{ev6}, 67@code{ev67}, 68@code{ev68}. 69The special name @code{all} may be used to allow the assembler to accept 70instructions valid for any Alpha processor. 71 72In order to support existing practice in OSF/1 with respect to @code{.arch}, 73and existing practice within @command{MILO} (the Linux ARC bootloader), the 74numbered processor names (e.g.@: 21064) enable the processor-specific PALcode 75instructions, while the ``electro-vlasic'' names (e.g.@: @code{ev4}) do not. 76 77@cindex @code{-mdebug} command line option, Alpha 78@cindex @code{-no-mdebug} command line option, Alpha 79@item -mdebug 80@itemx -no-mdebug 81Enables or disables the generation of @code{.mdebug} encapsulation for 82stabs directives and procedure descriptors. The default is to automatically 83enable @code{.mdebug} when the first stabs directive is seen. 84 85@cindex @code{-relax} command line option, Alpha 86@item -relax 87This option forces all relocations to be put into the object file, instead 88of saving space and resolving some relocations at assembly time. Note that 89this option does not propagate all symbol arithmetic into the object file, 90because not all symbol arithmetic can be represented. However, the option 91can still be useful in specific applications. 92 93@cindex @code{-g} command line option, Alpha 94@item -g 95This option is used when the compiler generates debug information. When 96@command{gcc} is using @command{mips-tfile} to generate debug 97information for ECOFF, local labels must be passed through to the object 98file. Otherwise this option has no effect. 99 100@cindex @code{-G} command line option, Alpha 101@item -G@var{size} 102A local common symbol larger than @var{size} is placed in @code{.bss}, 103while smaller symbols are placed in @code{.sbss}. 104 105@cindex @code{-F} command line option, Alpha 106@cindex @code{-32addr} command line option, Alpha 107@item -F 108@itemx -32addr 109These options are ignored for backward compatibility. 110@end table 111 112@cindex Alpha Syntax 113@node Alpha Syntax 114@section Syntax 115The assembler syntax closely follow the Alpha Reference Manual; 116assembler directives and general syntax closely follow the OSF/1 and 117OpenVMS syntax, with a few differences for ELF. 118 119@menu 120* Alpha-Chars:: Special Characters 121* Alpha-Regs:: Register Names 122* Alpha-Relocs:: Relocations 123@end menu 124 125@node Alpha-Chars 126@subsection Special Characters 127 128@cindex line comment character, Alpha 129@cindex Alpha line comment character 130@samp{#} is the line comment character. 131 132@cindex line separator, Alpha 133@cindex statement separator, Alpha 134@cindex Alpha line separator 135@samp{;} can be used instead of a newline to separate statements. 136 137@node Alpha-Regs 138@subsection Register Names 139@cindex Alpha registers 140@cindex register names, Alpha 141 142The 32 integer registers are referred to as @samp{$@var{n}} or 143@samp{$r@var{n}}. In addition, registers 15, 28, 29, and 30 may 144be referred to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp}, 145and @samp{$sp} respectively. 146 147The 32 floating-point registers are referred to as @samp{$f@var{n}}. 148 149@node Alpha-Relocs 150@subsection Relocations 151@cindex Alpha relocations 152@cindex relocations, Alpha 153 154Some of these relocations are available for ECOFF, but mostly 155only for ELF. They are modeled after the relocation format 156introduced in Digital Unix 4.0, but there are additions. 157 158The format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}} 159where @var{tag} is the name of the relocation. In some cases 160@var{number} is used to relate specific instructions. 161 162The relocation is placed at the end of the instruction like so: 163 164@example 165ldah $0,a($29) !gprelhigh 166lda $0,a($0) !gprellow 167ldq $1,b($29) !literal!100 168ldl $2,0($1) !lituse_base!100 169@end example 170 171@table @code 172@item !literal 173@itemx !literal!@var{N} 174Used with an @code{ldq} instruction to load the address of a symbol 175from the GOT. 176 177A sequence number @var{N} is optional, and if present is used to pair 178@code{lituse} relocations with this @code{literal} relocation. The 179@code{lituse} relocations are used by the linker to optimize the code 180based on the final location of the symbol. 181 182Note that these optimizations are dependent on the data flow of the 183program. Therefore, if @emph{any} @code{lituse} is paired with a 184@code{literal} relocation, then @emph{all} uses of the register set by 185the @code{literal} instruction must also be marked with @code{lituse} 186relocations. This is because the original @code{literal} instruction 187may be deleted or transformed into another instruction. 188 189Also note that there may be a one-to-many relationship between 190@code{literal} and @code{lituse}, but not a many-to-one. That is, if 191there are two code paths that load up the same address and feed the 192value to a single use, then the use may not use a @code{lituse} 193relocation. 194 195@item !lituse_base!@var{N} 196Used with any memory format instruction (e.g.@: @code{ldl}) to indicate 197that the literal is used for an address load. The offset field of the 198instruction must be zero. During relaxation, the code may be altered 199to use a gp-relative load. 200 201@item !lituse_jsr!@var{N} 202Used with a register branch format instruction (e.g.@: @code{jsr}) to 203indicate that the literal is used for a call. During relaxation, the 204code may be altered to use a direct branch (e.g.@: @code{bsr}). 205 206@item !lituse_jsrdirect!@var{N} 207Similar to @code{lituse_jsr}, but also that this call cannot be vectored 208through a PLT entry. This is useful for functions with special calling 209conventions which do not allow the normal call-clobbered registers to be 210clobbered. 211 212@item !lituse_bytoff!@var{N} 213Used with a byte mask instruction (e.g.@: @code{extbl}) to indicate 214that only the low 3 bits of the address are relevant. During relaxation, 215the code may be altered to use an immediate instead of a register shift. 216 217@item !lituse_addr!@var{N} 218Used with any other instruction to indicate that the original address 219is in fact used, and the original @code{ldq} instruction may not be 220altered or deleted. This is useful in conjunction with @code{lituse_jsr} 221to test whether a weak symbol is defined. 222 223@example 224ldq $27,foo($29) !literal!1 225beq $27,is_undef !lituse_addr!1 226jsr $26,($27),foo !lituse_jsr!1 227@end example 228 229@item !lituse_tlsgd!@var{N} 230Used with a register branch format instruction to indicate that the 231literal is the call to @code{__tls_get_addr} used to compute the 232address of the thread-local storage variable whose descriptor was 233loaded with @code{!tlsgd!@var{N}}. 234 235@item !lituse_tlsldm!@var{N} 236Used with a register branch format instruction to indicate that the 237literal is the call to @code{__tls_get_addr} used to compute the 238address of the base of the thread-local storage block for the current 239module. The descriptor for the module must have been loaded with 240@code{!tlsldm!@var{N}}. 241 242@item !gpdisp!@var{N} 243Used with @code{ldah} and @code{lda} to load the GP from the current 244address, a-la the @code{ldgp} macro. The source register for the 245@code{ldah} instruction must contain the address of the @code{ldah} 246instruction. There must be exactly one @code{lda} instruction paired 247with the @code{ldah} instruction, though it may appear anywhere in 248the instruction stream. The immediate operands must be zero. 249 250@example 251bsr $26,foo 252ldah $29,0($26) !gpdisp!1 253lda $29,0($29) !gpdisp!1 254@end example 255 256@item !gprelhigh 257Used with an @code{ldah} instruction to add the high 16 bits of a 25832-bit displacement from the GP. 259 260@item !gprellow 261Used with any memory format instruction to add the low 16 bits of a 26232-bit displacement from the GP. 263 264@item !gprel 265Used with any memory format instruction to add a 16-bit displacement 266from the GP. 267 268@item !samegp 269Used with any branch format instruction to skip the GP load at the 270target address. The referenced symbol must have the same GP as the 271source object file, and it must be declared to either not use @code{$27} 272or perform a standard GP load in the first two instructions via the 273@code{.prologue} directive. 274 275@item !tlsgd 276@itemx !tlsgd!@var{N} 277Used with an @code{lda} instruction to load the address of a TLS 278descriptor for a symbol in the GOT. 279 280The sequence number @var{N} is optional, and if present it used to 281pair the descriptor load with both the @code{literal} loading the 282address of the @code{__tls_get_addr} function and the @code{lituse_tlsgd} 283marking the call to that function. 284 285For proper relaxation, both the @code{tlsgd}, @code{literal} and 286@code{lituse} relocations must be in the same extended basic block. 287That is, the relocation with the lowest address must be executed 288first at runtime. 289 290@item !tlsldm 291@itemx !tlsldm!@var{N} 292Used with an @code{lda} instruction to load the address of a TLS 293descriptor for the current module in the GOT. 294 295Similar in other respects to @code{tlsgd}. 296 297@item !gotdtprel 298Used with an @code{ldq} instruction to load the offset of the TLS 299symbol within its module's thread-local storage block. Also known 300as the dynamic thread pointer offset or dtp-relative offset. 301 302@item !dtprelhi 303@itemx !dtprello 304@itemx !dtprel 305Like @code{gprel} relocations except they compute dtp-relative offsets. 306 307@item !gottprel 308Used with an @code{ldq} instruction to load the offset of the TLS 309symbol from the thread pointer. Also known as the tp-relative offset. 310 311@item !tprelhi 312@itemx !tprello 313@itemx !tprel 314Like @code{gprel} relocations except they compute tp-relative offsets. 315@end table 316 317@node Alpha Floating Point 318@section Floating Point 319@cindex floating point, Alpha (@sc{ieee}) 320@cindex Alpha floating point (@sc{ieee}) 321The Alpha family uses both @sc{ieee} and VAX floating-point numbers. 322 323@node Alpha Directives 324@section Alpha Assembler Directives 325 326@command{@value{AS}} for the Alpha supports many additional directives for 327compatibility with the native assembler. This section describes them only 328briefly. 329 330@cindex Alpha-only directives 331These are the additional directives in @code{@value{AS}} for the Alpha: 332 333@table @code 334@item .arch @var{cpu} 335Specifies the target processor. This is equivalent to the 336@option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options}, 337for a list of values for @var{cpu}. 338 339@item .ent @var{function}[, @var{n}] 340Mark the beginning of @var{function}. An optional number may follow for 341compatibility with the OSF/1 assembler, but is ignored. When generating 342@code{.mdebug} information, this will create a procedure descriptor for 343the function. In ELF, it will mark the symbol as a function a-la the 344generic @code{.type} directive. 345 346@item .end @var{function} 347Mark the end of @var{function}. In ELF, it will set the size of the symbol 348a-la the generic @code{.size} directive. 349 350@item .mask @var{mask}, @var{offset} 351Indicate which of the integer registers are saved in the current 352function's stack frame. @var{mask} is interpreted a bit mask in which 353bit @var{n} set indicates that register @var{n} is saved. The registers 354are saved in a block located @var{offset} bytes from the @dfn{canonical 355frame address} (CFA) which is the value of the stack pointer on entry to 356the function. The registers are saved sequentially, except that the 357return address register (normally @code{$26}) is saved first. 358 359This and the other directives that describe the stack frame are 360currently only used when generating @code{.mdebug} information. They 361may in the future be used to generate DWARF2 @code{.debug_frame} unwind 362information for hand written assembly. 363 364@item .fmask @var{mask}, @var{offset} 365Indicate which of the floating-point registers are saved in the current 366stack frame. The @var{mask} and @var{offset} parameters are interpreted 367as with @code{.mask}. 368 369@item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}] 370Describes the shape of the stack frame. The frame pointer in use is 371@var{framereg}; normally this is either @code{$fp} or @code{$sp}. The 372frame pointer is @var{frameoffset} bytes below the CFA. The return 373address is initially located in @var{retreg} until it is saved as 374indicated in @code{.mask}. For compatibility with OSF/1 an optional 375@var{argoffset} parameter is accepted and ignored. It is believed to 376indicate the offset from the CFA to the saved argument registers. 377 378@item .prologue @var{n} 379Indicate that the stack frame is set up and all registers have been 380spilled. The argument @var{n} indicates whether and how the function 381uses the incoming @dfn{procedure vector} (the address of the called 382function) in @code{$27}. 0 indicates that @code{$27} is not used; 1 383indicates that the first two instructions of the function use @code{$27} 384to perform a load of the GP register; 2 indicates that @code{$27} is 385used in some non-standard way and so the linker cannot elide the load of 386the procedure vector during relaxation. 387 388@item .usepv @var{function}, @var{which} 389Used to indicate the use of the @code{$27} register, similar to 390@code{.prologue}, but without the other semantics of needing to 391be inside an open @code{.ent}/@code{.end} block. 392 393The @var{which} argument should be either @code{no}, indicating that 394@code{$27} is not used, or @code{std}, indicating that the first two 395instructions of the function perform a GP load. 396 397One might use this directive instead of @code{.prologue} if you are 398also using dwarf2 CFI directives. 399 400@item .gprel32 @var{expression} 401Computes the difference between the address in @var{expression} and the 402GP for the current object file, and stores it in 4 bytes. In addition 403to being smaller than a full 8 byte address, this also does not require 404a dynamic relocation when used in a shared library. 405 406@item .t_floating @var{expression} 407Stores @var{expression} as an @sc{ieee} double precision value. 408 409@item .s_floating @var{expression} 410Stores @var{expression} as an @sc{ieee} single precision value. 411 412@item .f_floating @var{expression} 413Stores @var{expression} as a VAX F format value. 414 415@item .g_floating @var{expression} 416Stores @var{expression} as a VAX G format value. 417 418@item .d_floating @var{expression} 419Stores @var{expression} as a VAX D format value. 420 421@item .set @var{feature} 422Enables or disables various assembler features. Using the positive 423name of the feature enables while using @samp{no@var{feature}} disables. 424 425@table @code 426@item at 427Indicates that macro expansions may clobber the @dfn{assembler 428temporary} (@code{$at} or @code{$28}) register. Some macros may not be 429expanded without this and will generate an error message if @code{noat} 430is in effect. When @code{at} is in effect, a warning will be generated 431if @code{$at} is used by the programmer. 432 433@item macro 434Enables the expansion of macro instructions. Note that variants of real 435instructions, such as @code{br label} vs @code{br $31,label} are 436considered alternate forms and not macros. 437 438@item move 439@itemx reorder 440@itemx volatile 441These control whether and how the assembler may re-order instructions. 442Accepted for compatibility with the OSF/1 assembler, but @command{@value{AS}} 443does not do instruction scheduling, so these features are ignored. 444@end table 445@end table 446 447The following directives are recognized for compatibility with the OSF/1 448assembler but are ignored. 449 450@example 451.proc .aproc 452.reguse .livereg 453.option .aent 454.ugen .eflag 455.alias .noalias 456@end example 457 458@node Alpha Opcodes 459@section Opcodes 460For detailed information on the Alpha machine instruction set, see the 461@c Attempt to work around a very overfull hbox. 462@iftex 463Alpha Architecture Handbook located at 464@smallfonts 465@example 466ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf 467@end example 468@textfonts 469@end iftex 470@ifnottex 471@uref{ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf,Alpha Architecture Handbook}. 472@end ifnottex 473