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