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.
10 @chapter Alpha Dependent Features
14 @node Machine Dependencies
15 @chapter Alpha Dependent Features
21 * Alpha Options:: Options
22 * Alpha Syntax:: Syntax
23 * Alpha Floating Point:: Floating Point
24 * Alpha Directives:: Alpha Machine Directives
25 * Alpha Opcodes:: Opcodes
31 @cindex notes for Alpha
33 The documentation here is primarily for the ELF object format.
34 @code{@value{AS}} also supports the ECOFF and EVAX formats, but
35 features specific to these formats are not yet documented.
40 @cindex options for Alpha
44 @cindex @code{-m@var{cpu}} command line option, Alpha
46 This option specifies the target processor. If an attempt is made to
47 assemble an instruction which will not execute on the target processor,
48 the assembler may either expand the instruction as a macro or issue an
49 error message. This option is equivalent to the @code{.arch} directive.
51 The following processor names are recognized:
71 The special name @code{all} may be used to allow the assembler to accept
72 instructions valid for any Alpha processor.
74 In order to support existing practice in OSF/1 with respect to @code{.arch},
75 and existing practice within @command{MILO} (the Linux ARC bootloader), the
76 numbered processor names (e.g.@: 21064) enable the processor-specific PALcode
77 instructions, while the ``electro-vlasic'' names (e.g.@: @code{ev4}) do not.
79 @cindex @code{-mdebug} command line option, Alpha
80 @cindex @code{-no-mdebug} command line option, Alpha
83 Enables or disables the generation of @code{.mdebug} encapsulation for
84 stabs directives and procedure descriptors. The default is to automatically
85 enable @code{.mdebug} when the first stabs directive is seen.
87 @cindex @code{-relax} command line option, Alpha
89 This option forces all relocations to be put into the object file, instead
90 of saving space and resolving some relocations at assembly time. Note that
91 this option does not propagate all symbol arithmetic into the object file,
92 because not all symbol arithmetic can be represented. However, the option
93 can still be useful in specific applications.
95 @cindex @code{-replace} command line option, Alpha
96 @cindex @code{-noreplace} command line option, Alpha
99 Enables or disables the optimization of procedure calls, both at assemblage
100 and 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
104 @cindex @code{-g} command line option, Alpha
106 This option is used when the compiler generates debug information. When
107 @command{gcc} is using @command{mips-tfile} to generate debug
108 information for ECOFF, local labels must be passed through to the object
109 file. Otherwise this option has no effect.
111 @cindex @code{-G} command line option, Alpha
113 A local common symbol larger than @var{size} is placed in @code{.bss},
114 while smaller symbols are placed in @code{.sbss}.
116 @cindex @code{-F} command line option, Alpha
117 @cindex @code{-32addr} command line option, Alpha
120 These options are ignored for backward compatibility.
127 The assembler syntax closely follow the Alpha Reference Manual;
128 assembler directives and general syntax closely follow the OSF/1 and
129 OpenVMS syntax, with a few differences for ELF.
132 * Alpha-Chars:: Special Characters
133 * Alpha-Regs:: Register Names
134 * Alpha-Relocs:: Relocations
138 @subsection Special Characters
140 @cindex line comment character, Alpha
141 @cindex Alpha line comment character
142 @samp{#} is the line comment character.
144 @cindex line separator, Alpha
145 @cindex statement separator, Alpha
146 @cindex Alpha line separator
147 @samp{;} can be used instead of a newline to separate statements.
150 @subsection Register Names
151 @cindex Alpha registers
152 @cindex register names, Alpha
154 The 32 integer registers are referred to as @samp{$@var{n}} or
155 @samp{$r@var{n}}. In addition, registers 15, 28, 29, and 30 may
156 be referred to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp},
157 and @samp{$sp} respectively.
159 The 32 floating-point registers are referred to as @samp{$f@var{n}}.
162 @subsection Relocations
163 @cindex Alpha relocations
164 @cindex relocations, Alpha
166 Some of these relocations are available for ECOFF, but mostly
167 only for ELF. They are modeled after the relocation format
168 introduced in Digital Unix 4.0, but there are additions.
170 The format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}}
171 where @var{tag} is the name of the relocation. In some cases
172 @var{number} is used to relate specific instructions.
174 The relocation is placed at the end of the instruction like so:
177 ldah $0,a($29) !gprelhigh
178 lda $0,a($0) !gprellow
179 ldq $1,b($29) !literal!100
180 ldl $2,0($1) !lituse_base!100
185 @itemx !literal!@var{N}
186 Used with an @code{ldq} instruction to load the address of a symbol
189 A sequence number @var{N} is optional, and if present is used to pair
190 @code{lituse} relocations with this @code{literal} relocation. The
191 @code{lituse} relocations are used by the linker to optimize the code
192 based on the final location of the symbol.
194 Note that these optimizations are dependent on the data flow of the
195 program. Therefore, if @emph{any} @code{lituse} is paired with a
196 @code{literal} relocation, then @emph{all} uses of the register set by
197 the @code{literal} instruction must also be marked with @code{lituse}
198 relocations. This is because the original @code{literal} instruction
199 may be deleted or transformed into another instruction.
201 Also note that there may be a one-to-many relationship between
202 @code{literal} and @code{lituse}, but not a many-to-one. That is, if
203 there are two code paths that load up the same address and feed the
204 value to a single use, then the use may not use a @code{lituse}
207 @item !lituse_base!@var{N}
208 Used with any memory format instruction (e.g.@: @code{ldl}) to indicate
209 that the literal is used for an address load. The offset field of the
210 instruction must be zero. During relaxation, the code may be altered
211 to use a gp-relative load.
213 @item !lituse_jsr!@var{N}
214 Used with a register branch format instruction (e.g.@: @code{jsr}) to
215 indicate that the literal is used for a call. During relaxation, the
216 code may be altered to use a direct branch (e.g.@: @code{bsr}).
218 @item !lituse_jsrdirect!@var{N}
219 Similar to @code{lituse_jsr}, but also that this call cannot be vectored
220 through a PLT entry. This is useful for functions with special calling
221 conventions which do not allow the normal call-clobbered registers to be
224 @item !lituse_bytoff!@var{N}
225 Used with a byte mask instruction (e.g.@: @code{extbl}) to indicate
226 that only the low 3 bits of the address are relevant. During relaxation,
227 the code may be altered to use an immediate instead of a register shift.
229 @item !lituse_addr!@var{N}
230 Used with any other instruction to indicate that the original address
231 is in fact used, and the original @code{ldq} instruction may not be
232 altered or deleted. This is useful in conjunction with @code{lituse_jsr}
233 to test whether a weak symbol is defined.
236 ldq $27,foo($29) !literal!1
237 beq $27,is_undef !lituse_addr!1
238 jsr $26,($27),foo !lituse_jsr!1
241 @item !lituse_tlsgd!@var{N}
242 Used with a register branch format instruction to indicate that the
243 literal is the call to @code{__tls_get_addr} used to compute the
244 address of the thread-local storage variable whose descriptor was
245 loaded with @code{!tlsgd!@var{N}}.
247 @item !lituse_tlsldm!@var{N}
248 Used with a register branch format instruction to indicate that the
249 literal is the call to @code{__tls_get_addr} used to compute the
250 address of the base of the thread-local storage block for the current
251 module. The descriptor for the module must have been loaded with
252 @code{!tlsldm!@var{N}}.
254 @item !gpdisp!@var{N}
255 Used with @code{ldah} and @code{lda} to load the GP from the current
256 address, a-la the @code{ldgp} macro. The source register for the
257 @code{ldah} instruction must contain the address of the @code{ldah}
258 instruction. There must be exactly one @code{lda} instruction paired
259 with the @code{ldah} instruction, though it may appear anywhere in
260 the instruction stream. The immediate operands must be zero.
264 ldah $29,0($26) !gpdisp!1
265 lda $29,0($29) !gpdisp!1
269 Used with an @code{ldah} instruction to add the high 16 bits of a
270 32-bit displacement from the GP.
273 Used with any memory format instruction to add the low 16 bits of a
274 32-bit displacement from the GP.
277 Used with any memory format instruction to add a 16-bit displacement
281 Used with any branch format instruction to skip the GP load at the
282 target address. The referenced symbol must have the same GP as the
283 source object file, and it must be declared to either not use @code{$27}
284 or perform a standard GP load in the first two instructions via the
285 @code{.prologue} directive.
288 @itemx !tlsgd!@var{N}
289 Used with an @code{lda} instruction to load the address of a TLS
290 descriptor for a symbol in the GOT.
292 The sequence number @var{N} is optional, and if present it used to
293 pair the descriptor load with both the @code{literal} loading the
294 address of the @code{__tls_get_addr} function and the @code{lituse_tlsgd}
295 marking the call to that function.
297 For proper relaxation, both the @code{tlsgd}, @code{literal} and
298 @code{lituse} relocations must be in the same extended basic block.
299 That is, the relocation with the lowest address must be executed
303 @itemx !tlsldm!@var{N}
304 Used with an @code{lda} instruction to load the address of a TLS
305 descriptor for the current module in the GOT.
307 Similar in other respects to @code{tlsgd}.
310 Used with an @code{ldq} instruction to load the offset of the TLS
311 symbol within its module's thread-local storage block. Also known
312 as the dynamic thread pointer offset or dtp-relative offset.
317 Like @code{gprel} relocations except they compute dtp-relative offsets.
320 Used with an @code{ldq} instruction to load the offset of the TLS
321 symbol from the thread pointer. Also known as the tp-relative offset.
326 Like @code{gprel} relocations except they compute tp-relative offsets.
329 @node Alpha Floating Point
330 @section Floating Point
331 @cindex floating point, Alpha (@sc{ieee})
332 @cindex Alpha floating point (@sc{ieee})
333 The Alpha family uses both @sc{ieee} and VAX floating-point numbers.
335 @node Alpha Directives
336 @section Alpha Assembler Directives
338 @command{@value{AS}} for the Alpha supports many additional directives for
339 compatibility with the native assembler. This section describes them only
342 @cindex Alpha-only directives
343 These are the additional directives in @code{@value{AS}} for the Alpha:
346 @item .arch @var{cpu}
347 Specifies the target processor. This is equivalent to the
348 @option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options},
349 for a list of values for @var{cpu}.
351 @item .ent @var{function}[, @var{n}]
352 Mark the beginning of @var{function}. An optional number may follow for
353 compatibility with the OSF/1 assembler, but is ignored. When generating
354 @code{.mdebug} information, this will create a procedure descriptor for
355 the function. In ELF, it will mark the symbol as a function a-la the
356 generic @code{.type} directive.
358 @item .end @var{function}
359 Mark the end of @var{function}. In ELF, it will set the size of the symbol
360 a-la the generic @code{.size} directive.
362 @item .mask @var{mask}, @var{offset}
363 Indicate which of the integer registers are saved in the current
364 function's stack frame. @var{mask} is interpreted a bit mask in which
365 bit @var{n} set indicates that register @var{n} is saved. The registers
366 are saved in a block located @var{offset} bytes from the @dfn{canonical
367 frame address} (CFA) which is the value of the stack pointer on entry to
368 the function. The registers are saved sequentially, except that the
369 return address register (normally @code{$26}) is saved first.
371 This and the other directives that describe the stack frame are
372 currently only used when generating @code{.mdebug} information. They
373 may in the future be used to generate DWARF2 @code{.debug_frame} unwind
374 information for hand written assembly.
376 @item .fmask @var{mask}, @var{offset}
377 Indicate which of the floating-point registers are saved in the current
378 stack frame. The @var{mask} and @var{offset} parameters are interpreted
379 as with @code{.mask}.
381 @item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}]
382 Describes the shape of the stack frame. The frame pointer in use is
383 @var{framereg}; normally this is either @code{$fp} or @code{$sp}. The
384 frame pointer is @var{frameoffset} bytes below the CFA. The return
385 address is initially located in @var{retreg} until it is saved as
386 indicated in @code{.mask}. For compatibility with OSF/1 an optional
387 @var{argoffset} parameter is accepted and ignored. It is believed to
388 indicate the offset from the CFA to the saved argument registers.
390 @item .prologue @var{n}
391 Indicate that the stack frame is set up and all registers have been
392 spilled. The argument @var{n} indicates whether and how the function
393 uses the incoming @dfn{procedure vector} (the address of the called
394 function) in @code{$27}. 0 indicates that @code{$27} is not used; 1
395 indicates that the first two instructions of the function use @code{$27}
396 to perform a load of the GP register; 2 indicates that @code{$27} is
397 used in some non-standard way and so the linker cannot elide the load of
398 the procedure vector during relaxation.
400 @item .usepv @var{function}, @var{which}
401 Used to indicate the use of the @code{$27} register, similar to
402 @code{.prologue}, but without the other semantics of needing to
403 be inside an open @code{.ent}/@code{.end} block.
405 The @var{which} argument should be either @code{no}, indicating that
406 @code{$27} is not used, or @code{std}, indicating that the first two
407 instructions of the function perform a GP load.
409 One might use this directive instead of @code{.prologue} if you are
410 also using dwarf2 CFI directives.
412 @item .gprel32 @var{expression}
413 Computes the difference between the address in @var{expression} and the
414 GP for the current object file, and stores it in 4 bytes. In addition
415 to being smaller than a full 8 byte address, this also does not require
416 a dynamic relocation when used in a shared library.
418 @item .t_floating @var{expression}
419 Stores @var{expression} as an @sc{ieee} double precision value.
421 @item .s_floating @var{expression}
422 Stores @var{expression} as an @sc{ieee} single precision value.
424 @item .f_floating @var{expression}
425 Stores @var{expression} as a VAX F format value.
427 @item .g_floating @var{expression}
428 Stores @var{expression} as a VAX G format value.
430 @item .d_floating @var{expression}
431 Stores @var{expression} as a VAX D format value.
433 @item .set @var{feature}
434 Enables or disables various assembler features. Using the positive
435 name of the feature enables while using @samp{no@var{feature}} disables.
439 Indicates that macro expansions may clobber the @dfn{assembler
440 temporary} (@code{$at} or @code{$28}) register. Some macros may not be
441 expanded without this and will generate an error message if @code{noat}
442 is in effect. When @code{at} is in effect, a warning will be generated
443 if @code{$at} is used by the programmer.
446 Enables the expansion of macro instructions. Note that variants of real
447 instructions, such as @code{br label} vs @code{br $31,label} are
448 considered alternate forms and not macros.
453 These control whether and how the assembler may re-order instructions.
454 Accepted for compatibility with the OSF/1 assembler, but @command{@value{AS}}
455 does not do instruction scheduling, so these features are ignored.
459 The following directives are recognized for compatibility with the OSF/1
460 assembler but are ignored.
472 For detailed information on the Alpha machine instruction set, see the
473 @c Attempt to work around a very overfull hbox.
475 Alpha Architecture Handbook located at
478 ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf
483 @uref{ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf,Alpha Architecture Handbook}.