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