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