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