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