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