gas/doc/c-alpha.texi

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