c-alpha.texi revision 91041
1@c Copyright 2002 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{ev4}, 59@code{ev5}, 60@code{lca45}, 61@code{ev5}, 62@code{ev56}, 63@code{pca56}, 64@code{ev6}. 65The special name @code{all} may be used to allow the assembler to accept 66instructions valid for any Alpha processor. 67 68In order to support existing practice in OSF/1 with respect to @code{.arch}, 69and existing practice within @command{MILO} (the Linux ARC bootloader), the 70numbered processor names (e.g.@: 21064) enable the processor-specific PALcode 71instructions, while the ``electro-vlasic'' names (e.g.@: @code{ev4}) do not. 72 73@cindex @code{-mdebug} command line option, Alpha 74@cindex @code{-no-mdebug} command line option, Alpha 75@item -mdebug 76@itemx -no-mdebug 77Enables or disables the generation of @code{.mdebug} encapsulation for 78stabs directives and procedure descriptors. The default is to automatically 79enable @code{.mdebug} when the first stabs directive is seen. 80 81@cindex @code{-relax} command line option, Alpha 82@item -relax 83This option forces all relocations to be put into the object file, instead 84of saving space and resolving some relocations at assembly time. Note that 85this option does not propagate all symbol arithmetic into the object file, 86because not all symbol arithmetic can be represented. However, the option 87can still be useful in specific applications. 88 89@cindex @code{-g} command line option, Alpha 90@item -g 91This option is used when the compiler generates debug information. When 92@command{gcc} is using @command{mips-tfile} to generate debug 93information for ECOFF, local labels must be passed through to the object 94file. Otherwise this option has no effect. 95 96@cindex @code{-G} command line option, Alpha 97@item -G@var{size} 98A local common symbol larger than @var{size} is placed in @code{.bss}, 99while smaller symbols are placed in @code{.sbss}. 100 101@cindex @code{-F} command line option, Alpha 102@cindex @code{-32addr} command line option, Alpha 103@item -F 104@itemx -32addr 105These options are ignored for backward compatibility. 106@end table 107 108@cindex Alpha Syntax 109@node Alpha Syntax 110@section Syntax 111The assembler syntax closely follow the Alpha Reference Manual; 112assembler directives and general syntax closely follow the OSF/1 and 113OpenVMS syntax, with a few differences for ELF. 114 115@menu 116* Alpha-Chars:: Special Characters 117* Alpha-Regs:: Register Names 118* Alpha-Relocs:: Relocations 119@end menu 120 121@node Alpha-Chars 122@subsection Special Characters 123 124@cindex line comment character, Alpha 125@cindex Alpha line comment character 126@samp{#} is the line comment character. 127 128@cindex line separator, Alpha 129@cindex statement separator, Alpha 130@cindex Alpha line separator 131@samp{;} can be used instead of a newline to separate statements. 132 133@node Alpha-Regs 134@subsection Register Names 135@cindex Alpha registers 136@cindex register names, Alpha 137 138The 32 integer registers are refered to as @samp{$@var{n}} or 139@samp{$r@var{n}}. In addition, registers 15, 28, 29, and 30 may 140be refered to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp}, 141and @samp{$sp} respectively. 142 143The 32 floating-point registers are refered to as @samp{$f@var{n}}. 144 145@node Alpha-Relocs 146@subsection Relocations 147@cindex Alpha relocations 148@cindex relocations, Alpha 149 150Some of these relocations are available for ECOFF, but mostly 151only for ELF. They are modeled after the relocation format 152introduced in Digial Unix 4.0, but there are additions. 153 154The format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}} 155where @var{tag} is the name of the relocation. In some cases 156@var{number} is used to relate specific instructions. 157 158The relocation is placed at the end of the instruction like so: 159 160@example 161ldah $0,a($29) !gprelhigh 162lda $0,a($0) !gprellow 163ldq $1,b($29) !literal!100 164ldl $2,0($1) !lituse_base!100 165@end example 166 167@table @code 168@item !literal 169@itemx !literal!@var{N} 170Used with an @code{ldq} instruction to load the address of a symbol 171from the GOT. 172 173A sequence number @var{N} is optional, and if present is used to pair 174@code{lituse} relocations with this @code{literal} relocation. The 175@code{lituse} relocations are used by the linker to optimize the code 176based on the final location of the symbol. 177 178Note that these optimizations are dependent on the data flow of the 179program. Therefore, if @emph{any} @code{lituse} is paired with a 180@code{literal} relocation, then @emph{all} uses of the register set by 181the @code{literal} instruction must also be marked with @code{lituse} 182relocations. This is because the original @code{literal} instruction 183may be deleted or transformed into another instruction. 184 185Also note that there may be a one-to-many relationship between 186@code{literal} and @code{lituse}, but not a many-to-one. That is, if 187there are two code paths that load up the same address and feed the 188value to a single use, then the use may not use a @code{lituse} 189relocation. 190 191@item !lituse_base!@var{N} 192Used with any memory format instruction (e.g.@: @code{ldl}) to indicate 193that the literal is used for an address load. The offset field of the 194instruction must be zero. During relaxation, the code may be altered 195to use a gp-relative load. 196 197@item !lituse_jsr!@var{N} 198Used with a register branch format instruction (e.g.@: @code{jsr}) to 199indicate that the literal is used for a call. During relaxation, the 200code may be altered to use a direct branch (e.g.@: @code{bsr}). 201 202@item !lituse_bytoff!@var{N} 203Used with a byte mask instruction (e.g.@: @code{extbl}) to indicate 204that only the low 3 bits of the address are relevant. During relaxation, 205the code may be altered to use an immediate instead of a register shift. 206 207@item !lituse_addr!@var{N} 208Used with any other instruction to indicate that the original address 209is in fact used, and the original @code{ldq} instruction may not be 210altered or deleted. This is useful in conjunction with @code{lituse_jsr} 211to test whether a weak symbol is defined. 212 213@example 214ldq $27,foo($29) !literal!1 215beq $27,is_undef !lituse_addr!1 216jsr $26,($27),foo !lituse_jsr!1 217@end example 218 219@item !gpdisp!@var{N} 220Used with @code{ldah} and @code{lda} to load the GP from the current 221address, a-la the @code{ldgp} macro. The source register for the 222@code{ldah} instruction must contain the address of the @code{ldah} 223instruction. There must be exactly one @code{lda} instruction paired 224with the @code{ldah} instruction, though it may appear anywhere in 225the instruction stream. The immediate operands must be zero. 226 227@example 228bsr $26,foo 229ldah $29,0($26) !gpdisp!1 230lda $29,0($29) !gpdisp!1 231@end example 232 233@item !gprelhigh 234Used with an @code{ldah} instruction to add the high 16 bits of a 23532-bit displacement from the GP. 236 237@item !gprellow 238Used with any memory format instruction to add the low 16 bits of a 23932-bit displacement from the GP. 240 241@item !gprel 242Used with any memory format instruction to add a 16-bit displacement 243from the GP. 244 245@item !samegp 246Used with any branch format instruction to skip the GP load at the 247target address. The referenced symbol must have the same GP as the 248source object file, and it must be declared to either not use @code{$27} 249or perform a standard GP load in the first two instructions via the 250@code{.prologue} directive. 251@end table 252 253@node Alpha Floating Point 254@section Floating Point 255@cindex floating point, Alpha (@sc{ieee}) 256@cindex Alpha floating point (@sc{ieee}) 257The Alpha family uses both @sc{ieee} and VAX floating-point numbers. 258 259@node Alpha Directives 260@section Alpha Assembler Directives 261 262@command{@value{AS}} for the Alpha supports many additional directives for 263compatibility with the native assembler. This section describes them only 264briefly. 265 266@cindex Alpha-only directives 267These are the additional directives in @code{@value{AS}} for the Alpha: 268 269@table @code 270@item .arch @var{cpu} 271Specifies the target processor. This is equivalent to the 272@option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options}, 273for a list of values for @var{cpu}. 274 275@item .ent @var{function}[, @var{n}] 276Mark the beginning of @var{function}. An optional number may follow for 277compatibility with the OSF/1 assembler, but is ignored. When generating 278@code{.mdebug} information, this will create a procedure descriptor for 279the function. In ELF, it will mark the symbol as a function a-la the 280generic @code{.type} directive. 281 282@item .end @var{function} 283Mark the end of @var{function}. In ELF, it will set the size of the symbol 284a-la the generic @code{.size} directive. 285 286@item .mask @var{mask}, @var{offset} 287Indicate which of the integer registers are saved in the current 288function's stack frame. @var{mask} is interpreted a bit mask in which 289bit @var{n} set indicates that register @var{n} is saved. The registers 290are saved in a block located @var{offset} bytes from the @dfn{canonical 291frame address} (CFA) which is the value of the stack pointer on entry to 292the function. The registers are saved sequentially, except that the 293return address register (normally @code{$26}) is saved first. 294 295This and the other directives that describe the stack frame are 296currently only used when generating @code{.mdebug} information. They 297may in the future be used to generate DWARF2 @code{.debug_frame} unwind 298information for hand written assembly. 299 300@item .fmask @var{mask}, @var{offset} 301Indicate which of the floating-point registers are saved in the current 302stack frame. The @var{mask} and @var{offset} parameters are interpreted 303as with @code{.mask}. 304 305@item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}] 306Describes the shape of the stack frame. The frame pointer in use is 307@var{framereg}; normally this is either @code{$fp} or @code{$sp}. The 308frame pointer is @var{frameoffset} bytes below the CFA. The return 309address is initially located in @var{retreg} until it is saved as 310indicated in @code{.mask}. For compatibility with OSF/1 an optional 311@var{argoffset} parameter is accepted and ignored. It is believed to 312indicate the offset from the CFA to the saved argument registers. 313 314@item .prologue @var{n} 315Indicate that the stack frame is set up and all registers have been 316spilled. The argument @var{n} indicates whether and how the function 317uses the incoming @dfn{procedure vector} (the address of the called 318function) in @code{$27}. 0 indicates that @code{$27} is not used; 1 319indicates that the first two instructions of the function use @code{$27} 320to perform a load of the GP register; 2 indicates that @code{$27} is 321used in some non-standard way and so the linker cannot elide the load of 322the procedure vector during relaxation. 323 324@item .gprel32 @var{expression} 325Computes the difference between the address in @var{expression} and the 326GP for the current object file, and stores it in 4 bytes. In addition 327to being smaller than a full 8 byte address, this also does not require 328a dynamic relocation when used in a shared library. 329 330@item .t_floating @var{expression} 331Stores @var{expression} as an @sc{ieee} double precision value. 332 333@item .s_floating @var{expression} 334Stores @var{expression} as an @sc{ieee} single precision value. 335 336@item .f_floating @var{expression} 337Stores @var{expression} as a VAX F format value. 338 339@item .g_floating @var{expression} 340Stores @var{expression} as a VAX G format value. 341 342@item .d_floating @var{expression} 343Stores @var{expression} as a VAX D format value. 344 345@item .set @var{feature} 346Enables or disables various assembler features. Using the positive 347name of the feature enables while using @samp{no@var{feature}} disables. 348 349@table @code 350@item at 351Indicates that macro expansions may clobber the @dfn{assembler 352temporary} (@code{$at} or @code{$28}) register. Some macros may not be 353expanded without this and will generate an error message if @code{noat} 354is in effect. When @code{at} is in effect, a warning will be generated 355if @code{$at} is used by the programmer. 356 357@item macro 358Enables the expasion of macro instructions. Note that variants of real 359instructions, such as @code{br label} vs @code{br $31,label} are 360considered alternate forms and not macros. 361 362@item move 363@itemx reorder 364@itemx volatile 365These control whether and how the assembler may re-order instructions. 366Accepted for compatibility with the OSF/1 assembler, but @command{@value{AS}} 367does not do instruction scheduling, so these features are ignored. 368@end table 369@end table 370 371The following directives are recognized for compatibility with the OSF/1 372assembler but are ignored. 373 374@example 375.proc .aproc 376.reguse .livereg 377.option .aent 378.ugen .eflag 379.alias .noalias 380@end example 381 382@node Alpha Opcodes 383@section Opcodes 384For detailed information on the Alpha machine instruction set, see the 385@c Attempt to work around a very overfull hbox. 386@iftex 387Alpha Architecture Handbook located at 388@smallfonts 389@example 390ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf 391@end example 392@textfonts 393@end iftex 394@ifnottex 395@uref{ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf,Alpha Architecture Handbook}. 396@end ifnottex 397