AArch64 Dependent Features
**************************

Options
=======

-EB
     This option specifies that the output generated by the assembler should be marked as being encoded for a big-endian processor.

-EL
     This option specifies that the output generated by the assembler should be marked as being encoded for a little-endian processor.

-mabi=ABI
     Specify which ABI the source code uses.  The recognized arguments are: ilp32 and lp64, which decides the generated object file in ELF32 and ELF64 format respectively.  The default is lp64.

-mcpu=PROCESSOR[+EXTENSION...]
     This option specifies the target processor.  The assembler will issue an error message if an attempt is made to assemble an instruction which will not execute on the target processor.  The following processor names are recognized: cortex-a34, cortex-a35, cortex-a53, cortex-a55, cortex-a57, cortex-a65, cortex-a65ae, cortex-a72, cortex-a73, cortex-a75, cortex-a76, cortex-a76ae, cortex-a77, cortex-a78, cortex-a78ae, cortex-a78c, cortex-a510, cortex-a520, cortex-a710, cortex-a720, ares, exynos-m1, falkor, neoverse-n1, neoverse-n2, neoverse-e1, neoverse-v1, qdf24xx, saphira, thunderx, vulcan, xgene1 xgene2, cortex-r82, cortex-x1, cortex-x2, cortex-x3, and cortex-x4. The special name all may be used to allow the assembler to accept instructions valid for any supported processor, including all optional extensions.

     In addition to the basic instruction set, the assembler can be told to accept, or restrict, various extension mnemonics that extend the processor.  See AArch64 Extensions.

     If some implementations of a particular processor can have an extension, then then those extensions are automatically enabled. Consequently, you will not normally have to specify any additional extensions.

-march=ARCHITECTURE[+EXTENSION...]
     This option specifies the target architecture.  The assembler will issue an error message if an attempt is made to assemble an instruction which will not execute on the target architecture.  The following architecture names are recognized: armv8-a, armv8.1-a, armv8.2-a, armv8.3-a, armv8.4-a armv8.5-a, armv8.6-a, armv8.7-a, armv8.8-a, armv8.9-a, armv8-r, armv9-a, armv9.1-a, armv9.2-a, armv9.3-a, armv9.4-a and armv9.5-a.

     If both -mcpu and -march are specified, the assembler will use the setting for -mcpu.  If neither are specified, the assembler will default to -mcpu=all.

     The architecture option can be extended with the same instruction set extension options as the -mcpu option.  Unlike -mcpu, extensions are not always enabled by default. See AArch64 Extensions.

-mbig-obj
     On PE/COFF target this option forces the use of big object file format, which allows more than 32768 sections.

-mverbose-error
     This option enables verbose error messages for AArch64 gas.  This option is enabled by default.

-mno-verbose-error
     This option disables verbose error messages in AArch64 gas.

-menable-sysreg-checking
     This option enables error messages that are issued if an attempt is made to assemble a system register access which will not execute on the target architecture.

Architecture Extensions
=======================

The tables below lists the permitted architecture extensions and architecture versions that are supported by the assembler, including a brief description and a list of other extensions that they depend upon.

Multiple extensions may be specified, separated by a +. Extension mnemonics may also be removed from those the assembler accepts.  This is done by prepending no to the option that adds the extension.  Extensions that are removed must be listed after all extensions that have been added.

Enabling an extension that depends upon other extensions (either directly or recursively) will automatically cause those extensions to be enabled. Similarly, disabling an extension that is required by other extensions will automatically cause those extensions to be disabled.

Extension   Depends upon   Description
aes   simd
Enable the AES and PMULL cryptographic extensions.
bf16   fp
Enable BFloat16 extension.
brbe
Enable the Branch Record Buffer extension.
chk
Enable the Check Feature Status Extension.
cmpbr
Enable Compare and Branch instructions.
compnum   simd
Enable the complex number SIMD extensions.  An alias of fcma.
cpa
Enable the Checked Pointer Arithmetic extension.
crc
Enable CRC instructions.
crypto   simd
Enable cryptographic extensions.  This is equivalent to aes+sha2.
cssc
Enable the Armv8.9-A Common Short Sequence Compression instructions.
d128   lse128
Enable the 128-bit Page Descriptor Extension.  This implies lse128.
dotprod   simd
Enable the Dot Product extension.
f16f32dot   simd, fp16
Enable Armv9.7 f16f32dot instructions.
f16f32mm   simd, fp16
Enable Armv9.7 f16f32mm instructions.
f16mm   simd, fp16
Enable f16mm instructions.
f32mm   sve
Enable the F32 Matrix Multiply extension.
f64mm   sve
Enable the F64 Matrix Multiply extension.
f8f16mm   simd fp8
Enable 8-bit floating-point matrix multiply-accumulate to half-precision instructions.
f8f32mm   simd fp
Enable 8-bit floating-point matrix multiply-accumulate to single-precision instructions.
faminmax   simd
Enable the famin and famax instructions.
fcma   fp16, simd
Enable the complex number SIMD extensions.
flagm
Enable Flag Manipulation instructions.
flagm2   flagm
Enable FlagM2 flag conversion instructions.
fp
Enable floating-point extensions.
fp8
Enable the Floating Point 8 (FP8) extension.
fp8dot2   fp8
Enable the FP8 2-way dot product instructions.
fp8dot4   fp8
Enable the FP8 4-way dot product instructions.
fp8fma   fp8
Enable the FP8 FMA instructions.
fp16fml   fp16
Enable Armv8.2 16-bit floating-point multiplication variant support.
fp16   fp
Enable Armv8.2 16-bit floating-point support.
fprcvt   fp
Enable Armv9.6 fprcvt instructions.
frintts   fp
Enable floating-point round to integral value instructions.
gcie
Enable the GICv5 (Generic Interrupt Controller) CPU Interface Extension.
gcs
Enable the Guarded Control Stack Extension.
hbc
Enable Armv8.8-A hinted conditional branch instructions.
i8mm   simd
Enable the Int8 Matrix Multiply extension.
ite
Enable the TRCIT instruction.
jscvt   fp
Enable the fjcvtzs JavaScript conversion instruction.
lor
Enable Limited Ordering Regions extensions.
ls64
Enable the 64 Byte Loads/Stores extensions.
lscp
Enable the load acquire and store release pair extension.
lse
Enable Large System extensions.
lse128   lse
Enable the 128-bit Atomic Instructions extension.
lsfe   fp
Enable Large System Float Extension.
lsui
Enable Unprivileged Load/Store instructions.
lut   simd
Enable the Lookup Table (LUT) extension.
memtag
Enable Armv8.5-A Memory Tagging Extensions.
mops
Enable Armv8.8-A memcpy and memset acceleration instructions.
mops-go   mops, memtag
Enable tag only variants of MOPS instructions.
mpamv2
Enable MPAMv2 system registers.
mtetc   memtag
Enable Data cache tag block operations.
occmo
Enable Outer Cacheable Cache Maintenance Operations.
pan
Enable Privileged Access Never support.
pauth
Enable Pointer Authentication.
poe2
Enable Permission overlays extension 2.
pops
Enable Point of Physical Storage.
predres
Enable execution and data prediction restriction instructions.
predres2   predres
Enable additional prediction restriction instructions.
profile
Enable statistical profiling extensions.
ras
Enable the Reliability, Availability and Serviceability extension.
rasv2   ras
Enable the Reliability, Availability and Serviceability extension v2.
rcpc
Enable the Load-Acquire RCpc instructions extension.
rcpc2   rcpc
Enable the Load-Acquire RCpc instructions extension v2.
rcpc3   rcpc2
Enable the Load-Acquire RCpc instructions extension v3.
rdma   simd
Enable rounding doubling multiply accumulate instructions.
rdm   simd
An alias of rdma.
rng
Enable Armv8.5-A random number instructions.
sb
Enable the speculation barrier instruction sb.
sha2   simd
Enable the SHA1 and SHA256 cryptographic extensions.
sha3   sha2
Enable the SHA512 and SHA3 cryptographic extensions.
simd   fp
Enable Advanced SIMD extensions.
sm4   simd
Enable the SM3 and SM4 cryptographic extensions.
sme   bf16, fp16, fcma
Enable the Scalable Matrix Extension.  This will also enable sve2, but disabling sve2 does not disable sme.
sme-b16b16   sme2, sve-b16b16
Enable SME ZA-targeting non-widening BFloat16 instructions.
sme-f8f16   sme2, fp8
Enable the SME F8F16 Extension.
sme-f8f32   sme2, fp8
Enable the SME F8F32 Extension.
sme-f16f16   sme2
Enable the SME2 F16F16 Extension.
sme-f64f64   sme
Enable SME F64F64 Extension.
sme-i16i64   sme
Enable SME I16I64 Extension.
sme-lutv2
Enable SME Lookup Table v2 (LUTv2) extension.
sme-mop4   sme2
Enable SME Quarter-tile outer product instructions.
sme-tmop   sme2
Enable SME structured sparsity outer product instructions.
sme2   sme
Enable SME2.
sme2p1   sme2
Enable SME2.1.
sme2p2   sme2p1
Enable SME2.2.
sme2p3   sme2p2
Enable SME2.3.
ssbs
Enable Speculative Store Bypassing Safe state read and write.
ssve-aes   sme2, sve-aes
Enable SVE AES instructions in streaming mode.
ssve-bitperm   sme2, sve-bitperm
Enable SVE AES instructions in streaming mode.
ssve-fexpa   sme2
Enable the SVE FEXPA instruction in streaming mode.
ssve-fp8dot2   sme2, fp8
Enable the Streaming SVE FP8 2-way dot product instructions.
ssve-fp8dot4   sme2, fp8
Enable the Streaming SVE FP8 4-way dot product instructions.
ssve-fp8fma   sme2, fp8
Enable the Streaming SVE FP8 FMA instructions.
sve   fcma
Enable the Scalable Vector Extension.
sve-aes   aes
Enable the SVE2 AES and PMULL Extensions.
sve-aes2
Enable the SVE-AES2 extension.
sve-b16b16
Enable the SVE B16B16 extension.  These instructions also require either +sve2 or +sme2.
sve-b16mm   sve
Enable the SVE B16MM Extension.
sve-bfscale
Enable the SVE BFSCALE extension. These instructions also require either +sve2 or +sme2.
sve-bitperm
Enable the SVE2 BITPERM Extension.
sve-f16f32mm   sve
Enable the SVE_F16F32MM extension.
sve2   sve
Enable SVE2.
sve2-aes   sve2, sve-aes
Enable the SVE2 AES and PMULL Extensions.
sve2-bitperm   sve2, sve-bitperm
Enable the SVE2 BITPERM Extension.
sve2-sha3   sve2, sha3
Enable the SVE2 SHA3 Extension.
sve2-sm4   sve2, sm4
Enable the SVE2 SM4 Extension.
sve2p1   sve2
Enable SVE2.1.
sve2p2   sve2p1
Enable SVE2.2.
sve2p3   sve2p2
Enable SVE2.3.
tev
TIndex Exception-like Vector Extension.
the
Enable the Translation Hardening Extension.
tlbid
Enable the TLBI Domains Extension.
tme
Enable the Transactional Memory Extension.
wfxt
Enable wfet and wfit instructions.
xs
Enable the XS memory attribute extension.

Architecture Version   Includes
armv8-a   simd, chk, ras
armv8.1-a   armv8-a, crc, lse, rdma, pan, lor
armv8.2-a   armv8.1-a
armv8.3-a   armv8.2-a, fcma, jscvt, pauth, rcpc
armv8.4-a   armv8.3-a, fp16fml, dotprod, flagm, rcpc2
armv8.5-a   armv8.4-a, frintts, flagm2, predres, sb, ssbs
armv8.6-a   armv8.5-a, bf16, i8mm
armv8.7-a   armv8.6-a, ls64, xs, wfxt
armv8.8-a   armv8.7-a, hbc, mops
armv8.9-a   armv8.8-a, rasv2, predres2
armv9-a   armv8.5-a, sve2
armv9.1-a   armv9-a, armv8.6-a
armv9.2-a   armv9.1-a, armv8.7-a
armv9.3-a   armv9.2-a, armv8.8-a
armv9.4-a   armv9.3-a, armv8.9-a
armv9.5-a   armv9.4-a, cpa, lut, faminmax
armv9.6-a   armv9.5-a, cmpbr, lsui, occmo
armv9.7-a   armv9.6-a, sve2p2, sve2p3, f16f32dot
armv8-r   armv8.4-a+nolor

Syntax
======

Special Characters
------------------

The presence of a // on a line indicates the start of a comment that extends to the end of the current line.  If a # appears as the first character of a line, the whole line is treated as a comment.

The ; character can be used instead of a newline to separate statements.

The # can be optionally used to indicate immediate operands.

Register Names
--------------

Please refer to the section Register names of Arm Architecture Reference Manual for A-profile architecture, which is available at https://developer.arm.com/.

Relocations
-----------

Relocations for MOVZ and MOVK instructions can be generated by prefixing the label with #:abs_g2: etc. For example to load the 48-bit absolute address of FOO into x0:

             movz x0, #:abs_g2:foo		// bits 32-47, overflow check
             movk x0, #:abs_g1_nc:foo	// bits 16-31, no overflow check
             movk x0, #:abs_g0_nc:foo	// bits  0-15, no overflow check

Relocations for ADRP, and ADD, LDR or STR instructions can be generated by prefixing the label with :pg_hi21: and #:lo12: respectively.

For example to use 33-bit (+/-4GB) pc-relative addressing to load the address of FOO into x0:

             adrp x0, :pg_hi21:foo
             add  x0, x0, #:lo12:foo

Or to load the value of FOO into x0:

             adrp x0, :pg_hi21:foo
             ldr  x0, [x0, #:lo12:foo]

Note that :pg_hi21: is optional.

             adrp x0, foo

is equivalent to

             adrp x0, :pg_hi21:foo

Floating Point
==============

The AArch64 architecture uses IEEE floating-point numbers.

AArch64 Machine Directives
==========================

.aeabi_subsection NAME, COMPREHENSION, ENCODING
     Create or switch the current object attributes subsection to NAME.  Valid values for NAME are following the pattern [a-zA-Z0-9_]+.

     The subsection property COMPREHENSION determines how a program processing the attributes handles attributes that it does not recognize (perhaps because the object file was generated by a different version of the toolchain).  A subsection that is marked optional can be skipped if it is not understood.  A subsection marked required implies that information conveyed by the attribute is required for correct processing of the object file; a fatal diagnostic must be generated if a tool does not recognize either the tag or the value associated with it.

     ENCODING specifies the expected encoding of the attributes recorded in the subsection.  Currently supported values are ULEB128/uleb128 and NTBS/ntbs (null-terminated byte string).

     On the first declaration of a subsection, both COMPREHENSION and ENCODING are mandatory parameters. However, on subsequent declarations, none of the parameters is required. If they are still specified, their values will be matched against the ones from the first declaration. Any mismatch will be reported as an error.

.aeabi_attribute TAG, VALUE
     Create an attribute with the pair TAG, VALUE in the current subsection.  TAG can either be an integer value, or a known named key. VALUE can either be an integer or a string.

     The complete list of subsections and tags supported on AArch64 is documented in Build Attributes for the Arm 64-bit Architecture (AArch64).

.arch NAME
     Select the target architecture.  Valid values for NAME are the same as for the -march command-line option.

     Specifying .arch clears any previously selected architecture extensions.

.arch_extension NAME
     Add or remove an architecture extension to the target architecture.  Valid values for NAME are the same as those accepted as architectural extensions by the -mcpu command-line option.

     .arch_extension may be used multiple times to add or remove extensions incrementally to the architecture being compiled for.

.cfi_mte_tagged_frame
     The .cfi_mte_tagged_frame directive inserts a 'G' character into the CIE corresponding to the current frame's FDE, meaning that the associated frames may modify MTE tags on the stack space they use.  This information is intended to be used by the stack unwinder in order to properly untag stack frames.

.cpu NAME
     Set the target processor.  Valid values for NAME are the same as those accepted by the -mcpu= command-line option.

.dword EXPRESSIONS
     The .dword directive produces 64 bit values.

.even
     The .even directive aligns the output on the next even byte boundary.

.float16 VALUE [,...,VALUE_N]
     Place the half precision floating point representation of one or more floating-point values into the current section. The format used to encode the floating point values is always the IEEE 754-2008 half precision floating point format.

.inst EXPRESSIONS
     Inserts the expressions into the output as if they were instructions, rather than data.

.ltorg
     This directive causes the current contents of the literal pool to be dumped into the current section (which is assumed to be the .text section) at the current location (aligned to a word boundary). GAS maintains a separate literal pool for each section and each sub-section.  The .ltorg directive will only affect the literal pool of the current section and sub-section.  At the end of assembly all remaining, un-empty literal pools will automatically be dumped.

     Note - older versions of GAS would dump the current literal pool any time a section change occurred.  This is no longer done, since it prevents accurate control of the placement of literal pools.

.pool
     This is a synonym for .ltorg.

NAME .req REGISTER NAME
     This creates an alias for REGISTER NAME called NAME.  For example:

                  foo .req w0

     ip0, ip1, lr and fp are automatically defined to alias to X16, X17, X30 and X29 respectively.

.tlsdescadd
     Emits a TLSDESC_ADD reloc on the next instruction.

.tlsdesccall
     Emits a TLSDESC_CALL reloc on the next instruction.

.tlsdescldr
     Emits a TLSDESC_LDR reloc on the next instruction.

.unreq ALIAS-NAME
     This undefines a register alias which was previously defined using the req directive.  For example:

                  foo .req w0
                  .unreq foo

     An error occurs if the name is undefined.  Note - this pseudo op can be used to delete builtin in register name aliases (eg 'w0').  This should only be done if it is really necessary.

.variant_pcs SYMBOL
     This directive marks SYMBOL referencing a function that may follow a variant procedure call standard with different register usage convention from the base procedure call standard.

.xword EXPRESSIONS
     The .xword directive produces 64 bit values.  This is the same as the .dword directive.

.cfi_b_key_frame
     The .cfi_b_key_frame directive inserts a 'B' character into the CIE corresponding to the current frame's FDE, meaning that its return address has been signed with the B-key.  If two frames are signed with differing keys then they will not share the same CIE.  This information is intended to be used by the stack unwinder in order to properly authenticate return addresses.

Opcodes
=======

GAS implements all the standard AArch64 opcodes.  It also implements several pseudo opcodes, including several synthetic load instructions.

LDR =

            ldr <register> , =<expression>

     The constant expression will be placed into the nearest literal pool (if it not already there) and a PC-relative LDR instruction will be generated.

For more information on the AArch64 instruction set and assembly language notation, see Arm Architecture Reference Manual for A-profile architecture available at https://developer.arm.com/.

Mapping Symbols
===============

The AArch64 ELF specification requires that special symbols be inserted into object files to mark certain features:

$x
     At the start of a region of code containing AArch64 instructions.

$d
     At the start of a region of data.