gas/doc/c-aarch64.texi

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