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