gas/doc/c-aarch64.texi

   1 @c Copyright (C) 2009-2017 Free Software Foundation, Inc.
   2 @c Contributed by ARM Ltd.
   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 AArch64-Dependent
  10 @chapter AArch64 Dependent Features
  11 @end ifset
  12
  13 @ifclear GENERIC
  14 @node Machine Dependencies
  15 @chapter AArch64 Dependent Features
  16 @end ifclear
  17
  18 @cindex AArch64 support
  19 @menu
  20 * AArch64 Options::              Options
  21 * AArch64 Extensions::           Extensions
  22 * AArch64 Syntax::               Syntax
  23 * AArch64 Floating Point::       Floating Point
  24 * AArch64 Directives::           AArch64 Machine Directives
  25 * AArch64 Opcodes::              Opcodes
  26 * AArch64 Mapping Symbols::      Mapping Symbols
  27 @end menu
  28
  29 @node AArch64 Options
  30 @section Options
  31 @cindex AArch64 options (none)
  32 @cindex options for AArch64 (none)
  33
  34 @c man begin OPTIONS
  35 @table @gcctabopt
  36
  37 @cindex @option{-EB} command line option, AArch64
  38 @item -EB
  39 This option specifies that the output generated by the assembler should
  40 be marked as being encoded for a big-endian processor.
  41
  42 @cindex @option{-EL} command line option, AArch64
  43 @item -EL
  44 This option specifies that the output generated by the assembler should
  45 be marked as being encoded for a little-endian processor.
  46
  47 @cindex @option{-mabi=} command line option, AArch64
  48 @item -mabi=@var{abi}
  49 Specify which ABI the source code uses.  The recognized arguments
  50 are: @code{ilp32} and @code{lp64}, which decides the generated object
  51 file in ELF32 and ELF64 format respectively.  The default is @code{lp64}.
  52
  53 @cindex @option{-mcpu=} command line option, AArch64
  54 @item -mcpu=@var{processor}[+@var{extension}@dots{}]
  55 This option specifies the target processor.  The assembler will issue an error
  56 message if an attempt is made to assemble an instruction which will not execute
  57 on the target processor.  The following processor names are recognized:
  58 @code{cortex-a35},
  59 @code{cortex-a53},
  60 @code{cortex-a57},
  61 @code{cortex-a72},
  62 @code{cortex-a73},
  63 @code{exynos-m1},
  64 @code{falkor},
  65 @code{qdf24xx},
  66 @code{thunderx},
  67 @code{vulcan},
  68 @code{xgene1}
  69 and
  70 @code{xgene2}.
  71 The special name @code{all} may be used to allow the assembler to accept
  72 instructions valid for any supported processor, including all optional
  73 extensions.
  74
  75 In addition to the basic instruction set, the assembler can be told to
  76 accept, or restrict, various extension mnemonics that extend the
  77 processor.  @xref{AArch64 Extensions}.
  78
  79 If some implementations of a particular processor can have an
  80 extension, then then those extensions are automatically enabled.
  81 Consequently, you will not normally have to specify any additional
  82 extensions.
  83
  84 @cindex @option{-march=} command line option, AArch64
  85 @item -march=@var{architecture}[+@var{extension}@dots{}]
  86 This option specifies the target architecture.  The assembler will
  87 issue an error message if an attempt is made to assemble an
  88 instruction which will not execute on the target architecture.  The
  89 following architecture names are recognized: @code{armv8-a},
  90 @code{armv8.1-a}, @code{armv8.2-a} and @code{armv8.3-a}.
  91
  92 If both @option{-mcpu} and @option{-march} are specified, the
  93 assembler will use the setting for @option{-mcpu}.  If neither are
  94 specified, the assembler will default to @option{-mcpu=all}.
  95
  96 The architecture option can be extended with the same instruction set
  97 extension options as the @option{-mcpu} option.  Unlike
  98 @option{-mcpu}, extensions are not always enabled by default,
  99 @xref{AArch64 Extensions}.
 100
 101 @cindex @code{-mverbose-error} command line option, AArch64
 102 @item -mverbose-error
 103 This option enables verbose error messages for AArch64 gas.  This option
 104 is enabled by default.
 105
 106 @cindex @code{-mno-verbose-error} command line option, AArch64
 107 @item -mno-verbose-error
 108 This option disables verbose error messages in AArch64 gas.
 109
 110 @end table
 111 @c man end
 112
 113 @node AArch64 Extensions
 114 @section Architecture Extensions
 115
 116 The table below lists the permitted architecture extensions that are
 117 supported by the assembler and the conditions under which they are
 118 automatically enabled.
 119
 120 Multiple extensions may be specified, separated by a @code{+}.
 121 Extension mnemonics may also be removed from those the assembler
 122 accepts.  This is done by prepending @code{no} to the option that adds
 123 the extension.  Extensions that are removed must be listed after all
 124 extensions that have been added.
 125
 126 Enabling an extension that requires other extensions will
 127 automatically cause those extensions to be enabled.  Similarly,
 128 disabling an extension that is required by other extensions will
 129 automatically cause those extensions to be disabled.
 130
 131 @multitable @columnfractions .12 .17 .17 .54
 132 @headitem Extension @tab Minimum Architecture @tab Enabled by default
 133  @tab Description
 134 @item @code{compnum} @tab ARMv8.2-A @tab ARMv8.3-A or later
 135  @tab Enable the complex number SIMD extensions.  This implies
 136  @code{fp16} and @code{simd}.
 137 @item @code{crc} @tab ARMv8-A @tab ARMv8.1-A or later
 138  @tab Enable CRC instructions.
 139 @item @code{crypto} @tab ARMv8-A @tab No
 140  @tab Enable cryptographic extensions.  This implies @code{fp} and @code{simd}.
 141 @item @code{fp} @tab ARMv8-A @tab ARMv8-A or later
 142  @tab Enable floating-point extensions.
 143 @item @code{fp16} @tab ARMv8.2-A @tab ARMv8.2-A or later
 144  @tab Enable ARMv8.2 16-bit floating-point support.  This implies
 145  @code{fp}.
 146 @item @code{lor} @tab ARMv8-A @tab ARMv8.1-A or later
 147  @tab Enable Limited Ordering Regions extensions.
 148 @item @code{lse} @tab ARMv8-A @tab ARMv8.1-A or later
 149  @tab Enable Large System extensions.
 150 @item @code{pan} @tab ARMv8-A @tab ARMv8.1-A or later
 151  @tab Enable Privileged Access Never support.
 152 @item @code{profile} @tab ARMv8.2-A @tab No
 153  @tab Enable statistical profiling extensions.
 154 @item @code{ras} @tab ARMv8-A @tab ARMv8.2-A or later
 155  @tab Enable the Reliability, Availability and Serviceability
 156  extension.
 157 @item @code{rdma} @tab ARMv8-A @tab ARMv8.1-A or later
 158  @tab Enable ARMv8.1 Advanced SIMD extensions.  This implies @code{simd}.
 159 @item @code{simd} @tab ARMv8-A @tab ARMv8-A or later
 160  @tab Enable Advanced SIMD extensions.  This implies @code{fp}.
 161 @item @code{sve} @tab ARMv8.2-A @tab No
 162  @tab Enable the Scalable Vector Extensions.  This implies @code{fp16},
 163  @code{simd} and @code{compnum}.
 164 @end multitable
 165
 166 @node AArch64 Syntax
 167 @section Syntax
 168 @menu
 169 * AArch64-Chars::                Special Characters
 170 * AArch64-Regs::                 Register Names
 171 * AArch64-Relocations::      Relocations
 172 @end menu
 173
 174 @node AArch64-Chars
 175 @subsection Special Characters
 176
 177 @cindex line comment character, AArch64
 178 @cindex AArch64 line comment character
 179 The presence of a @samp{//} on a line indicates the start of a comment
 180 that extends to the end of the current line.  If a @samp{#} appears as
 181 the first character of a line, the whole line is treated as a comment.
 182
 183 @cindex line separator, AArch64
 184 @cindex statement separator, AArch64
 185 @cindex AArch64 line separator
 186 The @samp{;} character can be used instead of a newline to separate
 187 statements.
 188
 189 @cindex immediate character, AArch64
 190 @cindex AArch64 immediate character
 191 The @samp{#} can be optionally used to indicate immediate operands.
 192
 193 @node AArch64-Regs
 194 @subsection Register Names
 195
 196 @cindex AArch64 register names
 197 @cindex register names, AArch64
 198 Please refer to the section @samp{4.4 Register Names} of
 199 @samp{ARMv8 Instruction Set Overview}, which is available at
 200 @uref{http://infocenter.arm.com}.
 201
 202 @node AArch64-Relocations
 203 @subsection Relocations
 204
 205 @cindex relocations, AArch64
 206 @cindex AArch64 relocations
 207 @cindex MOVN, MOVZ and MOVK group relocations, AArch64
 208 Relocations for @samp{MOVZ} and @samp{MOVK} instructions can be generated
 209 by prefixing the label with @samp{#:abs_g2:} etc.
 210 For example to load the 48-bit absolute address of @var{foo} into x0:
 211
 212 @smallexample
 213         movz x0, #:abs_g2:foo           // bits 32-47, overflow check
 214         movk x0, #:abs_g1_nc:foo        // bits 16-31, no overflow check
 215         movk x0, #:abs_g0_nc:foo        // bits  0-15, no overflow check
 216 @end smallexample
 217
 218 @cindex ADRP, ADD, LDR/STR group relocations, AArch64
 219 Relocations for @samp{ADRP}, and @samp{ADD}, @samp{LDR} or @samp{STR}
 220 instructions can be generated by prefixing the label with
 221 @samp{:pg_hi21:} and @samp{#:lo12:} respectively.
 222
 223 For example to use 33-bit (+/-4GB) pc-relative addressing to
 224 load the address of @var{foo} into x0:
 225
 226 @smallexample
 227         adrp x0, :pg_hi21:foo
 228         add  x0, x0, #:lo12:foo
 229 @end smallexample
 230
 231 Or to load the value of @var{foo} into x0:
 232
 233 @smallexample
 234         adrp x0, :pg_hi21:foo
 235         ldr  x0, [x0, #:lo12:foo]
 236 @end smallexample
 237
 238 Note that @samp{:pg_hi21:} is optional.
 239
 240 @smallexample
 241         adrp x0, foo
 242 @end smallexample
 243
 244 is equivalent to
 245
 246 @smallexample
 247         adrp x0, :pg_hi21:foo
 248 @end smallexample
 249
 250 @node AArch64 Floating Point
 251 @section Floating Point
 252
 253 @cindex floating point, AArch64 (@sc{ieee})
 254 @cindex AArch64 floating point (@sc{ieee})
 255 The AArch64 architecture uses @sc{ieee} floating-point numbers.
 256
 257 @node AArch64 Directives
 258 @section AArch64 Machine Directives
 259
 260 @cindex machine directives, AArch64
 261 @cindex AArch64 machine directives
 262 @table @code
 263
 264 @c AAAAAAAAAAAAAAAAAAAAAAAAA
 265
 266 @cindex @code{.arch} directive, AArch64
 267 @item .arch @var{name}
 268 Select the target architecture.  Valid values for @var{name} are the same as
 269 for the @option{-march} commandline option.
 270
 271 Specifying @code{.arch} clears any previously selected architecture
 272 extensions.
 273
 274 @cindex @code{.arch_extension} directive, AArch64
 275 @item .arch_extension @var{name}
 276 Add or remove an architecture extension to the target architecture.  Valid
 277 values for @var{name} are the same as those accepted as architectural
 278 extensions by the @option{-mcpu} commandline option.
 279
 280 @code{.arch_extension} may be used multiple times to add or remove extensions
 281 incrementally to the architecture being compiled for.
 282
 283 @c BBBBBBBBBBBBBBBBBBBBBBBBBB
 284
 285 @cindex @code{.bss} directive, AArch64
 286 @item .bss
 287 This directive switches to the @code{.bss} section.
 288
 289 @c CCCCCCCCCCCCCCCCCCCCCCCCCC
 290
 291 @cindex @code{.cpu} directive, AArch64
 292 @item .cpu @var{name}
 293 Set the target processor.  Valid values for @var{name} are the same as
 294 those accepted by the @option{-mcpu=} command line option.
 295
 296 @c DDDDDDDDDDDDDDDDDDDDDDDDDD
 297
 298 @cindex @code{.dword} directive, AArch64
 299 @item .dword @var{expressions}
 300 The @code{.dword} directive produces 64 bit values.
 301
 302 @c EEEEEEEEEEEEEEEEEEEEEEEEEE
 303
 304 @cindex @code{.even} directive, AArch64
 305 @item .even
 306 The @code{.even} directive aligns the output on the next even byte
 307 boundary.
 308
 309 @c FFFFFFFFFFFFFFFFFFFFFFFFFF
 310 @c GGGGGGGGGGGGGGGGGGGGGGGGGG
 311 @c HHHHHHHHHHHHHHHHHHHHHHHHHH
 312 @c IIIIIIIIIIIIIIIIIIIIIIIIII
 313
 314 @cindex @code{.inst} directive, AArch64
 315 @item .inst @var{expressions}
 316 Inserts the expressions into the output as if they were instructions,
 317 rather than data.
 318
 319 @c JJJJJJJJJJJJJJJJJJJJJJJJJJ
 320 @c KKKKKKKKKKKKKKKKKKKKKKKKKK
 321 @c LLLLLLLLLLLLLLLLLLLLLLLLLL
 322
 323 @cindex @code{.ltorg} directive, AArch64
 324 @item .ltorg
 325 This directive causes the current contents of the literal pool to be
 326 dumped into the current section (which is assumed to be the .text
 327 section) at the current location (aligned to a word boundary).
 328 GAS maintains a separate literal pool for each section and each
 329 sub-section.  The @code{.ltorg} directive will only affect the literal
 330 pool of the current section and sub-section.  At the end of assembly
 331 all remaining, un-empty literal pools will automatically be dumped.
 332
 333 Note - older versions of GAS would dump the current literal
 334 pool any time a section change occurred.  This is no longer done, since
 335 it prevents accurate control of the placement of literal pools.
 336
 337 @c MMMMMMMMMMMMMMMMMMMMMMMMMM
 338
 339 @c NNNNNNNNNNNNNNNNNNNNNNNNNN
 340 @c OOOOOOOOOOOOOOOOOOOOOOOOOO
 341
 342 @c PPPPPPPPPPPPPPPPPPPPPPPPPP
 343
 344 @cindex @code{.pool} directive, AArch64
 345 @item .pool
 346 This is a synonym for .ltorg.
 347
 348 @c QQQQQQQQQQQQQQQQQQQQQQQQQQ
 349 @c RRRRRRRRRRRRRRRRRRRRRRRRRR
 350
 351 @cindex @code{.req} directive, AArch64
 352 @item @var{name} .req @var{register name}
 353 This creates an alias for @var{register name} called @var{name}.  For
 354 example:
 355
 356 @smallexample
 357         foo .req w0
 358 @end smallexample
 359
 360 @c SSSSSSSSSSSSSSSSSSSSSSSSSS
 361
 362 @c TTTTTTTTTTTTTTTTTTTTTTTTTT
 363
 364 @cindex @code{.tlsdescadd} directive, AArch64
 365 @item   @code{.tlsdescadd}
 366 Emits a TLSDESC_ADD reloc on the next instruction.
 367
 368 @cindex @code{.tlsdesccall} directive, AArch64
 369 @item   @code{.tlsdesccall}
 370 Emits a TLSDESC_CALL reloc on the next instruction.
 371
 372 @cindex @code{.tlsdescldr} directive, AArch64
 373 @item   @code{.tlsdescldr}
 374 Emits a TLSDESC_LDR reloc on the next instruction.
 375
 376 @c UUUUUUUUUUUUUUUUUUUUUUUUUU
 377
 378 @cindex @code{.unreq} directive, AArch64
 379 @item .unreq @var{alias-name}
 380 This undefines a register alias which was previously defined using the
 381 @code{req} directive.  For example:
 382
 383 @smallexample
 384         foo .req w0
 385         .unreq foo
 386 @end smallexample
 387
 388 An error occurs if the name is undefined.  Note - this pseudo op can
 389 be used to delete builtin in register name aliases (eg 'w0').  This
 390 should only be done if it is really necessary.
 391
 392 @c VVVVVVVVVVVVVVVVVVVVVVVVVV
 393
 394 @c WWWWWWWWWWWWWWWWWWWWWWWWWW
 395 @c XXXXXXXXXXXXXXXXXXXXXXXXXX
 396
 397 @cindex @code{.xword} directive, AArch64
 398 @item .xword @var{expressions}
 399 The @code{.xword} directive produces 64 bit values.  This is the same
 400 as the @code{.dword} directive.
 401
 402 @c YYYYYYYYYYYYYYYYYYYYYYYYYY
 403 @c ZZZZZZZZZZZZZZZZZZZZZZZZZZ
 404
 405 @end table
 406
 407 @node AArch64 Opcodes
 408 @section Opcodes
 409
 410 @cindex AArch64 opcodes
 411 @cindex opcodes for AArch64
 412 GAS implements all the standard AArch64 opcodes.  It also
 413 implements several pseudo opcodes, including several synthetic load
 414 instructions.
 415
 416 @table @code
 417
 418 @cindex @code{LDR reg,=<expr>} pseudo op, AArch64
 419 @item LDR =
 420 @smallexample
 421   ldr <register> , =<expression>
 422 @end smallexample
 423
 424 The constant expression will be placed into the nearest literal pool (if it not
 425 already there) and a PC-relative LDR instruction will be generated.
 426
 427 @end table
 428
 429 For more information on the AArch64 instruction set and assembly language
 430 notation, see @samp{ARMv8 Instruction Set Overview} available at
 431 @uref{http://infocenter.arm.com}.
 432
 433
 434 @node AArch64 Mapping Symbols
 435 @section Mapping Symbols
 436
 437 The AArch64 ELF specification requires that special symbols be inserted
 438 into object files to mark certain features:
 439
 440 @table @code
 441
 442 @cindex @code{$x}
 443 @item $x
 444 At the start of a region of code containing AArch64 instructions.
 445
 446 @cindex @code{$d}
 447 @item $d
 448 At the start of a region of data.
 449
 450 @end table