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