Import binutils-2.20
[dragonfly.git] / contrib / binutils-2.20 / gas / doc / c-alpha.texi
CommitLineData
8e158dd0
SS
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
32The documentation here is primarily for the ELF object format.
33@code{@value{AS}} also supports the ECOFF and EVAX formats, but
34features 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}
44This option specifies the target processor. If an attempt is made to
45assemble an instruction which will not execute on the target processor,
46the assembler may either expand the instruction as a macro or issue an
47error message. This option is equivalent to the @code{.arch} directive.
48
49The 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}.
69The special name @code{all} may be used to allow the assembler to accept
70instructions valid for any Alpha processor.
71
72In order to support existing practice in OSF/1 with respect to @code{.arch},
73and existing practice within @command{MILO} (the Linux ARC bootloader), the
74numbered processor names (e.g.@: 21064) enable the processor-specific PALcode
75instructions, 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
81Enables or disables the generation of @code{.mdebug} encapsulation for
82stabs directives and procedure descriptors. The default is to automatically
83enable @code{.mdebug} when the first stabs directive is seen.
84
85@cindex @code{-relax} command line option, Alpha
86@item -relax
87This option forces all relocations to be put into the object file, instead
88of saving space and resolving some relocations at assembly time. Note that
89this option does not propagate all symbol arithmetic into the object file,
90because not all symbol arithmetic can be represented. However, the option
91can 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
97Enables or disables the optimization of procedure calls, both at assemblage
98and 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
100Utility Manual.
101
102@cindex @code{-g} command line option, Alpha
103@item -g
104This option is used when the compiler generates debug information. When
105@command{gcc} is using @command{mips-tfile} to generate debug
106information for ECOFF, local labels must be passed through to the object
107file. Otherwise this option has no effect.
108
109@cindex @code{-G} command line option, Alpha
110@item -G@var{size}
111A local common symbol larger than @var{size} is placed in @code{.bss},
112while 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
118These options are ignored for backward compatibility.
119@end table
120
121@cindex Alpha Syntax
122@node Alpha Syntax
123@section Syntax
124The assembler syntax closely follow the Alpha Reference Manual;
125assembler directives and general syntax closely follow the OSF/1 and
126OpenVMS 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
151The 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
153be referred to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp},
154and @samp{$sp} respectively.
155
156The 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
163Some of these relocations are available for ECOFF, but mostly
164only for ELF. They are modeled after the relocation format
165introduced in Digital Unix 4.0, but there are additions.
166
167The format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}}
168where @var{tag} is the name of the relocation. In some cases
169@var{number} is used to relate specific instructions.
170
171The relocation is placed at the end of the instruction like so:
172
173@example
174ldah $0,a($29) !gprelhigh
175lda $0,a($0) !gprellow
176ldq $1,b($29) !literal!100
177ldl $2,0($1) !lituse_base!100
178@end example
179
180@table @code
181@item !literal
182@itemx !literal!@var{N}
183Used with an @code{ldq} instruction to load the address of a symbol
184from the GOT.
185
186A 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
189based on the final location of the symbol.
190
191Note that these optimizations are dependent on the data flow of the
192program. Therefore, if @emph{any} @code{lituse} is paired with a
193@code{literal} relocation, then @emph{all} uses of the register set by
194the @code{literal} instruction must also be marked with @code{lituse}
195relocations. This is because the original @code{literal} instruction
196may be deleted or transformed into another instruction.
197
198Also 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
200there are two code paths that load up the same address and feed the
201value to a single use, then the use may not use a @code{lituse}
202relocation.
203
204@item !lituse_base!@var{N}
205Used with any memory format instruction (e.g.@: @code{ldl}) to indicate
206that the literal is used for an address load. The offset field of the
207instruction must be zero. During relaxation, the code may be altered
208to use a gp-relative load.
209
210@item !lituse_jsr!@var{N}
211Used with a register branch format instruction (e.g.@: @code{jsr}) to
212indicate that the literal is used for a call. During relaxation, the
213code may be altered to use a direct branch (e.g.@: @code{bsr}).
214
215@item !lituse_jsrdirect!@var{N}
216Similar to @code{lituse_jsr}, but also that this call cannot be vectored
217through a PLT entry. This is useful for functions with special calling
218conventions which do not allow the normal call-clobbered registers to be
219clobbered.
220
221@item !lituse_bytoff!@var{N}
222Used with a byte mask instruction (e.g.@: @code{extbl}) to indicate
223that only the low 3 bits of the address are relevant. During relaxation,
224the code may be altered to use an immediate instead of a register shift.
225
226@item !lituse_addr!@var{N}
227Used with any other instruction to indicate that the original address
228is in fact used, and the original @code{ldq} instruction may not be
229altered or deleted. This is useful in conjunction with @code{lituse_jsr}
230to test whether a weak symbol is defined.
231
232@example
233ldq $27,foo($29) !literal!1
234beq $27,is_undef !lituse_addr!1
235jsr $26,($27),foo !lituse_jsr!1
236@end example
237
238@item !lituse_tlsgd!@var{N}
239Used with a register branch format instruction to indicate that the
240literal is the call to @code{__tls_get_addr} used to compute the
241address of the thread-local storage variable whose descriptor was
242loaded with @code{!tlsgd!@var{N}}.
243
244@item !lituse_tlsldm!@var{N}
245Used with a register branch format instruction to indicate that the
246literal is the call to @code{__tls_get_addr} used to compute the
247address of the base of the thread-local storage block for the current
248module. The descriptor for the module must have been loaded with
249@code{!tlsldm!@var{N}}.
250
251@item !gpdisp!@var{N}
252Used with @code{ldah} and @code{lda} to load the GP from the current
253address, a-la the @code{ldgp} macro. The source register for the
254@code{ldah} instruction must contain the address of the @code{ldah}
255instruction. There must be exactly one @code{lda} instruction paired
256with the @code{ldah} instruction, though it may appear anywhere in
257the instruction stream. The immediate operands must be zero.
258
259@example
260bsr $26,foo
261ldah $29,0($26) !gpdisp!1
262lda $29,0($29) !gpdisp!1
263@end example
264
265@item !gprelhigh
266Used with an @code{ldah} instruction to add the high 16 bits of a
26732-bit displacement from the GP.
268
269@item !gprellow
270Used with any memory format instruction to add the low 16 bits of a
27132-bit displacement from the GP.
272
273@item !gprel
274Used with any memory format instruction to add a 16-bit displacement
275from the GP.
276
277@item !samegp
278Used with any branch format instruction to skip the GP load at the
279target address. The referenced symbol must have the same GP as the
280source object file, and it must be declared to either not use @code{$27}
281or 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}
286Used with an @code{lda} instruction to load the address of a TLS
287descriptor for a symbol in the GOT.
288
289The sequence number @var{N} is optional, and if present it used to
290pair the descriptor load with both the @code{literal} loading the
291address of the @code{__tls_get_addr} function and the @code{lituse_tlsgd}
292marking the call to that function.
293
294For proper relaxation, both the @code{tlsgd}, @code{literal} and
295@code{lituse} relocations must be in the same extended basic block.
296That is, the relocation with the lowest address must be executed
297first at runtime.
298
299@item !tlsldm
300@itemx !tlsldm!@var{N}
301Used with an @code{lda} instruction to load the address of a TLS
302descriptor for the current module in the GOT.
303
304Similar in other respects to @code{tlsgd}.
305
306@item !gotdtprel
307Used with an @code{ldq} instruction to load the offset of the TLS
308symbol within its module's thread-local storage block. Also known
309as the dynamic thread pointer offset or dtp-relative offset.
310
311@item !dtprelhi
312@itemx !dtprello
313@itemx !dtprel
314Like @code{gprel} relocations except they compute dtp-relative offsets.
315
316@item !gottprel
317Used with an @code{ldq} instruction to load the offset of the TLS
318symbol from the thread pointer. Also known as the tp-relative offset.
319
320@item !tprelhi
321@itemx !tprello
322@itemx !tprel
323Like @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})
330The 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
336compatibility with the native assembler. This section describes them only
337briefly.
338
339@cindex Alpha-only directives
340These are the additional directives in @code{@value{AS}} for the Alpha:
341
342@table @code
343@item .arch @var{cpu}
344Specifies the target processor. This is equivalent to the
345@option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options},
346for a list of values for @var{cpu}.
347
348@item .ent @var{function}[, @var{n}]
349Mark the beginning of @var{function}. An optional number may follow for
350compatibility with the OSF/1 assembler, but is ignored. When generating
351@code{.mdebug} information, this will create a procedure descriptor for
352the function. In ELF, it will mark the symbol as a function a-la the
353generic @code{.type} directive.
354
355@item .end @var{function}
356Mark the end of @var{function}. In ELF, it will set the size of the symbol
357a-la the generic @code{.size} directive.
358
359@item .mask @var{mask}, @var{offset}
360Indicate which of the integer registers are saved in the current
361function's stack frame. @var{mask} is interpreted a bit mask in which
362bit @var{n} set indicates that register @var{n} is saved. The registers
363are saved in a block located @var{offset} bytes from the @dfn{canonical
364frame address} (CFA) which is the value of the stack pointer on entry to
365the function. The registers are saved sequentially, except that the
366return address register (normally @code{$26}) is saved first.
367
368This and the other directives that describe the stack frame are
369currently only used when generating @code{.mdebug} information. They
370may in the future be used to generate DWARF2 @code{.debug_frame} unwind
371information for hand written assembly.
372
373@item .fmask @var{mask}, @var{offset}
374Indicate which of the floating-point registers are saved in the current
375stack frame. The @var{mask} and @var{offset} parameters are interpreted
376as with @code{.mask}.
377
378@item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}]
379Describes 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
381frame pointer is @var{frameoffset} bytes below the CFA. The return
382address is initially located in @var{retreg} until it is saved as
383indicated in @code{.mask}. For compatibility with OSF/1 an optional
384@var{argoffset} parameter is accepted and ignored. It is believed to
385indicate the offset from the CFA to the saved argument registers.
386
387@item .prologue @var{n}
388Indicate that the stack frame is set up and all registers have been
389spilled. The argument @var{n} indicates whether and how the function
390uses the incoming @dfn{procedure vector} (the address of the called
391function) in @code{$27}. 0 indicates that @code{$27} is not used; 1
392indicates that the first two instructions of the function use @code{$27}
393to perform a load of the GP register; 2 indicates that @code{$27} is
394used in some non-standard way and so the linker cannot elide the load of
395the procedure vector during relaxation.
396
397@item .usepv @var{function}, @var{which}
398Used to indicate the use of the @code{$27} register, similar to
399@code{.prologue}, but without the other semantics of needing to
400be inside an open @code{.ent}/@code{.end} block.
401
402The @var{which} argument should be either @code{no}, indicating that
403@code{$27} is not used, or @code{std}, indicating that the first two
404instructions of the function perform a GP load.
405
406One might use this directive instead of @code{.prologue} if you are
407also using dwarf2 CFI directives.
408
409@item .gprel32 @var{expression}
410Computes the difference between the address in @var{expression} and the
411GP for the current object file, and stores it in 4 bytes. In addition
412to being smaller than a full 8 byte address, this also does not require
413a dynamic relocation when used in a shared library.
414
415@item .t_floating @var{expression}
416Stores @var{expression} as an @sc{ieee} double precision value.
417
418@item .s_floating @var{expression}
419Stores @var{expression} as an @sc{ieee} single precision value.
420
421@item .f_floating @var{expression}
422Stores @var{expression} as a VAX F format value.
423
424@item .g_floating @var{expression}
425Stores @var{expression} as a VAX G format value.
426
427@item .d_floating @var{expression}
428Stores @var{expression} as a VAX D format value.
429
430@item .set @var{feature}
431Enables or disables various assembler features. Using the positive
432name of the feature enables while using @samp{no@var{feature}} disables.
433
434@table @code
435@item at
436Indicates that macro expansions may clobber the @dfn{assembler
437temporary} (@code{$at} or @code{$28}) register. Some macros may not be
438expanded without this and will generate an error message if @code{noat}
439is in effect. When @code{at} is in effect, a warning will be generated
440if @code{$at} is used by the programmer.
441
442@item macro
443Enables the expansion of macro instructions. Note that variants of real
444instructions, such as @code{br label} vs @code{br $31,label} are
445considered alternate forms and not macros.
446
447@item move
448@itemx reorder
449@itemx volatile
450These control whether and how the assembler may re-order instructions.
451Accepted for compatibility with the OSF/1 assembler, but @command{@value{AS}}
452does not do instruction scheduling, so these features are ignored.
453@end table
454@end table
455
456The following directives are recognized for compatibility with the OSF/1
457assembler 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
469For detailed information on the Alpha machine instruction set, see the
470@c Attempt to work around a very overfull hbox.
471@iftex
472Alpha Architecture Handbook located at
473@smallfonts
474@example
475ftp://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