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