c-alpha.texi revision 104834
191041Sobrien@c Copyright 2002 291041Sobrien@c Free Software Foundation, Inc. 391041Sobrien@c This is part of the GAS manual. 491041Sobrien@c For copying conditions, see the file as.texinfo. 591041Sobrien 691041Sobrien@ifset GENERIC 791041Sobrien@page 891041Sobrien@node Alpha-Dependent 991041Sobrien@chapter Alpha Dependent Features 1091041Sobrien@end ifset 1191041Sobrien 1291041Sobrien@ifclear GENERIC 1391041Sobrien@node Machine Dependencies 1491041Sobrien@chapter Alpha Dependent Features 1591041Sobrien@end ifclear 1691041Sobrien 1791041Sobrien@cindex Alpha support 1891041Sobrien@menu 1991041Sobrien* Alpha Notes:: Notes 2091041Sobrien* Alpha Options:: Options 2191041Sobrien* Alpha Syntax:: Syntax 2291041Sobrien* Alpha Floating Point:: Floating Point 2391041Sobrien* Alpha Directives:: Alpha Machine Directives 2491041Sobrien* Alpha Opcodes:: Opcodes 2591041Sobrien@end menu 2691041Sobrien 2791041Sobrien@node Alpha Notes 2891041Sobrien@section Notes 2991041Sobrien@cindex Alpha notes 3091041Sobrien@cindex notes for Alpha 3191041Sobrien 3291041SobrienThe documentation here is primarily for the ELF object format. 3391041Sobrien@code{@value{AS}} also supports the ECOFF and EVAX formats, but 3491041Sobrienfeatures specific to these formats are not yet documented. 3591041Sobrien 3691041Sobrien@node Alpha Options 3791041Sobrien@section Options 3891041Sobrien@cindex Alpha options 3991041Sobrien@cindex options for Alpha 4091041Sobrien 4191041Sobrien@table @option 4291041Sobrien@cindex @code{-m@var{cpu}} command line option, Alpha 4391041Sobrien@item -m@var{cpu} 4491041SobrienThis option specifies the target processor. If an attempt is made to 4591041Sobrienassemble an instruction which will not execute on the target processor, 4691041Sobrienthe assembler may either expand the instruction as a macro or issue an 4791041Sobrienerror message. This option is equivalent to the @code{.arch} directive. 4891041Sobrien 4991041SobrienThe following processor names are recognized: 5091041Sobrien@code{21064}, 5191041Sobrien@code{21064a}, 5291041Sobrien@code{21066}, 5391041Sobrien@code{21068}, 5491041Sobrien@code{21164}, 5591041Sobrien@code{21164a}, 5691041Sobrien@code{21164pc}, 5791041Sobrien@code{21264}, 58104834Sobrien@code{21264a}, 59104834Sobrien@code{21264b}, 6091041Sobrien@code{ev4}, 6191041Sobrien@code{ev5}, 6291041Sobrien@code{lca45}, 6391041Sobrien@code{ev5}, 6491041Sobrien@code{ev56}, 6591041Sobrien@code{pca56}, 66104834Sobrien@code{ev6}, 67104834Sobrien@code{ev67}, 68104834Sobrien@code{ev68}. 6991041SobrienThe special name @code{all} may be used to allow the assembler to accept 7091041Sobrieninstructions valid for any Alpha processor. 7191041Sobrien 7291041SobrienIn order to support existing practice in OSF/1 with respect to @code{.arch}, 7391041Sobrienand existing practice within @command{MILO} (the Linux ARC bootloader), the 7491041Sobriennumbered processor names (e.g.@: 21064) enable the processor-specific PALcode 7591041Sobrieninstructions, while the ``electro-vlasic'' names (e.g.@: @code{ev4}) do not. 7691041Sobrien 7791041Sobrien@cindex @code{-mdebug} command line option, Alpha 7891041Sobrien@cindex @code{-no-mdebug} command line option, Alpha 7991041Sobrien@item -mdebug 8091041Sobrien@itemx -no-mdebug 8191041SobrienEnables or disables the generation of @code{.mdebug} encapsulation for 8291041Sobrienstabs directives and procedure descriptors. The default is to automatically 8391041Sobrienenable @code{.mdebug} when the first stabs directive is seen. 8491041Sobrien 8591041Sobrien@cindex @code{-relax} command line option, Alpha 8691041Sobrien@item -relax 8791041SobrienThis option forces all relocations to be put into the object file, instead 8891041Sobrienof saving space and resolving some relocations at assembly time. Note that 8991041Sobrienthis option does not propagate all symbol arithmetic into the object file, 9091041Sobrienbecause not all symbol arithmetic can be represented. However, the option 9191041Sobriencan still be useful in specific applications. 9291041Sobrien 9391041Sobrien@cindex @code{-g} command line option, Alpha 9491041Sobrien@item -g 9591041SobrienThis option is used when the compiler generates debug information. When 9691041Sobrien@command{gcc} is using @command{mips-tfile} to generate debug 9791041Sobrieninformation for ECOFF, local labels must be passed through to the object 9891041Sobrienfile. Otherwise this option has no effect. 9991041Sobrien 10091041Sobrien@cindex @code{-G} command line option, Alpha 10191041Sobrien@item -G@var{size} 10291041SobrienA local common symbol larger than @var{size} is placed in @code{.bss}, 10391041Sobrienwhile smaller symbols are placed in @code{.sbss}. 10491041Sobrien 10591041Sobrien@cindex @code{-F} command line option, Alpha 10691041Sobrien@cindex @code{-32addr} command line option, Alpha 10791041Sobrien@item -F 10891041Sobrien@itemx -32addr 10991041SobrienThese options are ignored for backward compatibility. 11091041Sobrien@end table 11191041Sobrien 11291041Sobrien@cindex Alpha Syntax 11391041Sobrien@node Alpha Syntax 11491041Sobrien@section Syntax 11591041SobrienThe assembler syntax closely follow the Alpha Reference Manual; 11691041Sobrienassembler directives and general syntax closely follow the OSF/1 and 11791041SobrienOpenVMS syntax, with a few differences for ELF. 11891041Sobrien 11991041Sobrien@menu 12091041Sobrien* Alpha-Chars:: Special Characters 12191041Sobrien* Alpha-Regs:: Register Names 12291041Sobrien* Alpha-Relocs:: Relocations 12391041Sobrien@end menu 12491041Sobrien 12591041Sobrien@node Alpha-Chars 12691041Sobrien@subsection Special Characters 12791041Sobrien 12891041Sobrien@cindex line comment character, Alpha 12991041Sobrien@cindex Alpha line comment character 13091041Sobrien@samp{#} is the line comment character. 13191041Sobrien 13291041Sobrien@cindex line separator, Alpha 13391041Sobrien@cindex statement separator, Alpha 13491041Sobrien@cindex Alpha line separator 13591041Sobrien@samp{;} can be used instead of a newline to separate statements. 13691041Sobrien 13791041Sobrien@node Alpha-Regs 13891041Sobrien@subsection Register Names 13991041Sobrien@cindex Alpha registers 14091041Sobrien@cindex register names, Alpha 14191041Sobrien 14291041SobrienThe 32 integer registers are refered to as @samp{$@var{n}} or 14391041Sobrien@samp{$r@var{n}}. In addition, registers 15, 28, 29, and 30 may 14491041Sobrienbe refered to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp}, 14591041Sobrienand @samp{$sp} respectively. 14691041Sobrien 14791041SobrienThe 32 floating-point registers are refered to as @samp{$f@var{n}}. 14891041Sobrien 14991041Sobrien@node Alpha-Relocs 15091041Sobrien@subsection Relocations 15191041Sobrien@cindex Alpha relocations 15291041Sobrien@cindex relocations, Alpha 15391041Sobrien 15491041SobrienSome of these relocations are available for ECOFF, but mostly 15591041Sobrienonly for ELF. They are modeled after the relocation format 15691041Sobrienintroduced in Digial Unix 4.0, but there are additions. 15791041Sobrien 15891041SobrienThe format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}} 15991041Sobrienwhere @var{tag} is the name of the relocation. In some cases 16091041Sobrien@var{number} is used to relate specific instructions. 16191041Sobrien 16291041SobrienThe relocation is placed at the end of the instruction like so: 16391041Sobrien 16491041Sobrien@example 16591041Sobrienldah $0,a($29) !gprelhigh 16691041Sobrienlda $0,a($0) !gprellow 16791041Sobrienldq $1,b($29) !literal!100 16891041Sobrienldl $2,0($1) !lituse_base!100 16991041Sobrien@end example 17091041Sobrien 17191041Sobrien@table @code 17291041Sobrien@item !literal 17391041Sobrien@itemx !literal!@var{N} 17491041SobrienUsed with an @code{ldq} instruction to load the address of a symbol 17591041Sobrienfrom the GOT. 17691041Sobrien 17791041SobrienA sequence number @var{N} is optional, and if present is used to pair 17891041Sobrien@code{lituse} relocations with this @code{literal} relocation. The 17991041Sobrien@code{lituse} relocations are used by the linker to optimize the code 18091041Sobrienbased on the final location of the symbol. 18191041Sobrien 18291041SobrienNote that these optimizations are dependent on the data flow of the 18391041Sobrienprogram. Therefore, if @emph{any} @code{lituse} is paired with a 18491041Sobrien@code{literal} relocation, then @emph{all} uses of the register set by 18591041Sobrienthe @code{literal} instruction must also be marked with @code{lituse} 18691041Sobrienrelocations. This is because the original @code{literal} instruction 18791041Sobrienmay be deleted or transformed into another instruction. 18891041Sobrien 18991041SobrienAlso note that there may be a one-to-many relationship between 19091041Sobrien@code{literal} and @code{lituse}, but not a many-to-one. That is, if 19191041Sobrienthere are two code paths that load up the same address and feed the 19291041Sobrienvalue to a single use, then the use may not use a @code{lituse} 19391041Sobrienrelocation. 19491041Sobrien 19591041Sobrien@item !lituse_base!@var{N} 19691041SobrienUsed with any memory format instruction (e.g.@: @code{ldl}) to indicate 19791041Sobrienthat the literal is used for an address load. The offset field of the 19891041Sobrieninstruction must be zero. During relaxation, the code may be altered 19991041Sobriento use a gp-relative load. 20091041Sobrien 20191041Sobrien@item !lituse_jsr!@var{N} 20291041SobrienUsed with a register branch format instruction (e.g.@: @code{jsr}) to 20391041Sobrienindicate that the literal is used for a call. During relaxation, the 20491041Sobriencode may be altered to use a direct branch (e.g.@: @code{bsr}). 20591041Sobrien 20691041Sobrien@item !lituse_bytoff!@var{N} 20791041SobrienUsed with a byte mask instruction (e.g.@: @code{extbl}) to indicate 20891041Sobrienthat only the low 3 bits of the address are relevant. During relaxation, 20991041Sobrienthe code may be altered to use an immediate instead of a register shift. 21091041Sobrien 21191041Sobrien@item !lituse_addr!@var{N} 21291041SobrienUsed with any other instruction to indicate that the original address 21391041Sobrienis in fact used, and the original @code{ldq} instruction may not be 21491041Sobrienaltered or deleted. This is useful in conjunction with @code{lituse_jsr} 21591041Sobriento test whether a weak symbol is defined. 21691041Sobrien 21791041Sobrien@example 21891041Sobrienldq $27,foo($29) !literal!1 21991041Sobrienbeq $27,is_undef !lituse_addr!1 22091041Sobrienjsr $26,($27),foo !lituse_jsr!1 22191041Sobrien@end example 22291041Sobrien 223104834Sobrien@item !lituse_tlsgd!@var{N} 224104834SobrienUsed with a register branch format instruction to indicate that the 225104834Sobrienliteral is the call to @code{__tls_get_addr} used to compute the 226104834Sobrienaddress of the thread-local storage variable whose descriptor was 227104834Sobrienloaded with @code{!tlsgd!@var{N}}. 228104834Sobrien 229104834Sobrien@item !lituse_tlsldm!@var{N} 230104834SobrienUsed with a register branch format instruction to indicate that the 231104834Sobrienliteral is the call to @code{__tls_get_addr} used to compute the 232104834Sobrienaddress of the base of the thread-local storage block for the current 233104834Sobrienmodule. The descriptor for the module must have been loaded with 234104834Sobrien@code{!tlsldm!@var{N}}. 235104834Sobrien 23691041Sobrien@item !gpdisp!@var{N} 23791041SobrienUsed with @code{ldah} and @code{lda} to load the GP from the current 23891041Sobrienaddress, a-la the @code{ldgp} macro. The source register for the 23991041Sobrien@code{ldah} instruction must contain the address of the @code{ldah} 24091041Sobrieninstruction. There must be exactly one @code{lda} instruction paired 24191041Sobrienwith the @code{ldah} instruction, though it may appear anywhere in 24291041Sobrienthe instruction stream. The immediate operands must be zero. 24391041Sobrien 24491041Sobrien@example 24591041Sobrienbsr $26,foo 24691041Sobrienldah $29,0($26) !gpdisp!1 24791041Sobrienlda $29,0($29) !gpdisp!1 24891041Sobrien@end example 24991041Sobrien 25091041Sobrien@item !gprelhigh 25191041SobrienUsed with an @code{ldah} instruction to add the high 16 bits of a 25291041Sobrien32-bit displacement from the GP. 25391041Sobrien 25491041Sobrien@item !gprellow 25591041SobrienUsed with any memory format instruction to add the low 16 bits of a 25691041Sobrien32-bit displacement from the GP. 25791041Sobrien 25891041Sobrien@item !gprel 25991041SobrienUsed with any memory format instruction to add a 16-bit displacement 26091041Sobrienfrom the GP. 26191041Sobrien 26291041Sobrien@item !samegp 26391041SobrienUsed with any branch format instruction to skip the GP load at the 26491041Sobrientarget address. The referenced symbol must have the same GP as the 26591041Sobriensource object file, and it must be declared to either not use @code{$27} 26691041Sobrienor perform a standard GP load in the first two instructions via the 26791041Sobrien@code{.prologue} directive. 268104834Sobrien 269104834Sobrien@item !tlsgd 270104834Sobrien@itemx !tlsgd!@var{N} 271104834SobrienUsed with an @code{lda} instruction to load the address of a TLS 272104834Sobriendescriptor for a symbol in the GOT. 273104834Sobrien 274104834SobrienThe sequence number @var{N} is optional, and if present it used to 275104834Sobrienpair the descriptor load with both the @code{literal} loading the 276104834Sobrienaddress of the @code{__tls_get_addr} function and the @code{lituse_tlsgd} 277104834Sobrienmarking the call to that function. 278104834Sobrien 279104834SobrienFor proper relaxation, both the @code{tlsgd}, @code{literal} and 280104834Sobrien@code{lituse} relocations must be in the same extended basic block. 281104834SobrienThat is, the relocation with the lowest address must be executed 282104834Sobrienfirst at runtime. 283104834Sobrien 284104834Sobrien@item !tlsldm 285104834Sobrien@itemx !tlsldm!@var{N} 286104834SobrienUsed with an @code{lda} instruction to load the address of a TLS 287104834Sobriendescriptor for the current module in the GOT. 288104834Sobrien 289104834SobrienSimilar in other respects to @code{tlsgd}. 290104834Sobrien 291104834Sobrien@item !gotdtprel 292104834SobrienUsed with an @code{ldq} instruction to load the offset of the TLS 293104834Sobriensymbol within its module's thread-local storage block. Also known 294104834Sobrienas the dynamic thread pointer offset or dtp-relative offset. 295104834Sobrien 296104834Sobrien@item !dtprelhi 297104834Sobrien@itemx !dtprello 298104834Sobrien@itemx !dtprel 299104834SobrienLike @code{gprel} relocations except they compute dtp-relative offsets. 300104834Sobrien 301104834Sobrien@item !gottprel 302104834SobrienUsed with an @code{ldq} instruction to load the offset of the TLS 303104834Sobriensymbol from the thread pointer. Also known as the tp-relative offset. 304104834Sobrien 305104834Sobrien@item !tprelhi 306104834Sobrien@itemx !tprello 307104834Sobrien@itemx !tprel 308104834SobrienLike @code{gprel} relocations except they compute tp-relative offsets. 30991041Sobrien@end table 31091041Sobrien 31191041Sobrien@node Alpha Floating Point 31291041Sobrien@section Floating Point 31391041Sobrien@cindex floating point, Alpha (@sc{ieee}) 31491041Sobrien@cindex Alpha floating point (@sc{ieee}) 31591041SobrienThe Alpha family uses both @sc{ieee} and VAX floating-point numbers. 31691041Sobrien 31791041Sobrien@node Alpha Directives 31891041Sobrien@section Alpha Assembler Directives 31991041Sobrien 32091041Sobrien@command{@value{AS}} for the Alpha supports many additional directives for 32191041Sobriencompatibility with the native assembler. This section describes them only 32291041Sobrienbriefly. 32391041Sobrien 32491041Sobrien@cindex Alpha-only directives 32591041SobrienThese are the additional directives in @code{@value{AS}} for the Alpha: 32691041Sobrien 32791041Sobrien@table @code 32891041Sobrien@item .arch @var{cpu} 32991041SobrienSpecifies the target processor. This is equivalent to the 33091041Sobrien@option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options}, 33191041Sobrienfor a list of values for @var{cpu}. 33291041Sobrien 33391041Sobrien@item .ent @var{function}[, @var{n}] 33491041SobrienMark the beginning of @var{function}. An optional number may follow for 33591041Sobriencompatibility with the OSF/1 assembler, but is ignored. When generating 33691041Sobrien@code{.mdebug} information, this will create a procedure descriptor for 33791041Sobrienthe function. In ELF, it will mark the symbol as a function a-la the 33891041Sobriengeneric @code{.type} directive. 33991041Sobrien 34091041Sobrien@item .end @var{function} 34191041SobrienMark the end of @var{function}. In ELF, it will set the size of the symbol 34291041Sobriena-la the generic @code{.size} directive. 34391041Sobrien 34491041Sobrien@item .mask @var{mask}, @var{offset} 34591041SobrienIndicate which of the integer registers are saved in the current 34691041Sobrienfunction's stack frame. @var{mask} is interpreted a bit mask in which 34791041Sobrienbit @var{n} set indicates that register @var{n} is saved. The registers 34891041Sobrienare saved in a block located @var{offset} bytes from the @dfn{canonical 34991041Sobrienframe address} (CFA) which is the value of the stack pointer on entry to 35091041Sobrienthe function. The registers are saved sequentially, except that the 35191041Sobrienreturn address register (normally @code{$26}) is saved first. 35291041Sobrien 35391041SobrienThis and the other directives that describe the stack frame are 35491041Sobriencurrently only used when generating @code{.mdebug} information. They 35591041Sobrienmay in the future be used to generate DWARF2 @code{.debug_frame} unwind 35691041Sobrieninformation for hand written assembly. 35791041Sobrien 35891041Sobrien@item .fmask @var{mask}, @var{offset} 35991041SobrienIndicate which of the floating-point registers are saved in the current 36091041Sobrienstack frame. The @var{mask} and @var{offset} parameters are interpreted 36191041Sobrienas with @code{.mask}. 36291041Sobrien 36391041Sobrien@item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}] 36491041SobrienDescribes the shape of the stack frame. The frame pointer in use is 36591041Sobrien@var{framereg}; normally this is either @code{$fp} or @code{$sp}. The 36691041Sobrienframe pointer is @var{frameoffset} bytes below the CFA. The return 36791041Sobrienaddress is initially located in @var{retreg} until it is saved as 36891041Sobrienindicated in @code{.mask}. For compatibility with OSF/1 an optional 36991041Sobrien@var{argoffset} parameter is accepted and ignored. It is believed to 37091041Sobrienindicate the offset from the CFA to the saved argument registers. 37191041Sobrien 37291041Sobrien@item .prologue @var{n} 37391041SobrienIndicate that the stack frame is set up and all registers have been 37491041Sobrienspilled. The argument @var{n} indicates whether and how the function 37591041Sobrienuses the incoming @dfn{procedure vector} (the address of the called 37691041Sobrienfunction) in @code{$27}. 0 indicates that @code{$27} is not used; 1 37791041Sobrienindicates that the first two instructions of the function use @code{$27} 37891041Sobriento perform a load of the GP register; 2 indicates that @code{$27} is 37991041Sobrienused in some non-standard way and so the linker cannot elide the load of 38091041Sobrienthe procedure vector during relaxation. 38191041Sobrien 38291041Sobrien@item .gprel32 @var{expression} 38391041SobrienComputes the difference between the address in @var{expression} and the 38491041SobrienGP for the current object file, and stores it in 4 bytes. In addition 38591041Sobriento being smaller than a full 8 byte address, this also does not require 38691041Sobriena dynamic relocation when used in a shared library. 38791041Sobrien 38891041Sobrien@item .t_floating @var{expression} 38991041SobrienStores @var{expression} as an @sc{ieee} double precision value. 39091041Sobrien 39191041Sobrien@item .s_floating @var{expression} 39291041SobrienStores @var{expression} as an @sc{ieee} single precision value. 39391041Sobrien 39491041Sobrien@item .f_floating @var{expression} 39591041SobrienStores @var{expression} as a VAX F format value. 39691041Sobrien 39791041Sobrien@item .g_floating @var{expression} 39891041SobrienStores @var{expression} as a VAX G format value. 39991041Sobrien 40091041Sobrien@item .d_floating @var{expression} 40191041SobrienStores @var{expression} as a VAX D format value. 40291041Sobrien 40391041Sobrien@item .set @var{feature} 40491041SobrienEnables or disables various assembler features. Using the positive 40591041Sobrienname of the feature enables while using @samp{no@var{feature}} disables. 40691041Sobrien 40791041Sobrien@table @code 40891041Sobrien@item at 40991041SobrienIndicates that macro expansions may clobber the @dfn{assembler 41091041Sobrientemporary} (@code{$at} or @code{$28}) register. Some macros may not be 41191041Sobrienexpanded without this and will generate an error message if @code{noat} 41291041Sobrienis in effect. When @code{at} is in effect, a warning will be generated 41391041Sobrienif @code{$at} is used by the programmer. 41491041Sobrien 41591041Sobrien@item macro 41691041SobrienEnables the expasion of macro instructions. Note that variants of real 41791041Sobrieninstructions, such as @code{br label} vs @code{br $31,label} are 41891041Sobrienconsidered alternate forms and not macros. 41991041Sobrien 42091041Sobrien@item move 42191041Sobrien@itemx reorder 42291041Sobrien@itemx volatile 42391041SobrienThese control whether and how the assembler may re-order instructions. 42491041SobrienAccepted for compatibility with the OSF/1 assembler, but @command{@value{AS}} 42591041Sobriendoes not do instruction scheduling, so these features are ignored. 42691041Sobrien@end table 42791041Sobrien@end table 42891041Sobrien 42991041SobrienThe following directives are recognized for compatibility with the OSF/1 43091041Sobrienassembler but are ignored. 43191041Sobrien 43291041Sobrien@example 43391041Sobrien.proc .aproc 43491041Sobrien.reguse .livereg 43591041Sobrien.option .aent 43691041Sobrien.ugen .eflag 43791041Sobrien.alias .noalias 43891041Sobrien@end example 43991041Sobrien 44091041Sobrien@node Alpha Opcodes 44191041Sobrien@section Opcodes 44291041SobrienFor detailed information on the Alpha machine instruction set, see the 44391041Sobrien@c Attempt to work around a very overfull hbox. 44491041Sobrien@iftex 44591041SobrienAlpha Architecture Handbook located at 44691041Sobrien@smallfonts 44791041Sobrien@example 44891041Sobrienftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf 44991041Sobrien@end example 45091041Sobrien@textfonts 45191041Sobrien@end iftex 45291041Sobrien@ifnottex 45391041Sobrien@uref{ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf,Alpha Architecture Handbook}. 45491041Sobrien@end ifnottex 455