gas/doc/c-aarch64.texi

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