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, ares, exynos-m1, falkor, neoverse-n1, neoverse-n2, neoverse-e1, neoverse-v1, qdf24xx, saphira, thunderx, vulcan, xgene1 xgene2, cortex-r82, and cortex-x1. 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, and armv8-r.

     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.

-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.

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

The table below lists the permitted architecture extensions that are supported by the assembler and the conditions under which they are automatically enabled.

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 requires other extensions 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   Minimum Architecture   Enabled by default
Description
i8mm   ARMv8.2-A   ARMv8.6-A or later
Enable Int8 Matrix Multiply extension.
f32mm   ARMv8.2-A   No
Enable F32 Matrix Multiply extension.
f64mm   ARMv8.2-A   No
Enable F64 Matrix Multiply extension.
bf16   ARMv8.2-A   ARMv8.6-A or later
Enable BFloat16 extension.
compnum   ARMv8.2-A   ARMv8.3-A or later
Enable the complex number SIMD extensions.  This implies
fp16 and simd.
crc   ARMv8-A   ARMv8.1-A or later
Enable CRC instructions.
crypto   ARMv8-A   No
Enable cryptographic extensions.  This implies fp, simd, aes and sha2.
aes   ARMv8-A   No
Enable the AES cryptographic extensions. This implies fp and simd.
sha2   ARMv8-A   No
Enable the SHA2 cryptographic extensions. This implies fp and simd.
sha3   ARMv8.2-A   No
Enable the ARMv8.2-A SHA2 and SHA3 cryptographic extensions. This implies fp, simd and sha2.
sm4   ARMv8.2-A   No
Enable the ARMv8.2-A SM3 and SM4 cryptographic extensions. This implies fp and simd.
fp   ARMv8-A   ARMv8-A or later
Enable floating-point extensions.
fp16   ARMv8.2-A   ARMv8.2-A or later
Enable ARMv8.2 16-bit floating-point support.  This implies
fp.
lor   ARMv8-A   ARMv8.1-A or later
Enable Limited Ordering Regions extensions.
lse   ARMv8-A   ARMv8.1-A or later
Enable Large System extensions.
pan   ARMv8-A   ARMv8.1-A or later
Enable Privileged Access Never support.
profile   ARMv8.2-A   No
Enable statistical profiling extensions.
ras   ARMv8-A   ARMv8.2-A or later
Enable the Reliability, Availability and Serviceability
extension.
rcpc   ARMv8.2-A   ARMv8.3-A or later
Enable the weak release consistency extension.
rdma   ARMv8-A   ARMv8.1-A or later
Enable ARMv8.1 Advanced SIMD extensions.  This implies simd.
simd   ARMv8-A   ARMv8-A or later
Enable Advanced SIMD extensions.  This implies fp.
sve   ARMv8.2-A   No
Enable the Scalable Vector Extensions.  This implies fp16,
simd and compnum.
dotprod   ARMv8.2-A   ARMv8.4-A or later
Enable the Dot Product extension.  This implies simd.
fp16fml   ARMv8.2-A   ARMv8.4-A or later
Enable ARMv8.2 16-bit floating-point multiplication variant support.
This implies fp16.
sb   ARMv8-A   ARMv8.5-A or later
Enable the speculation barrier instruction sb.
predres   ARMv8-A   ARMv8.5-A or later
Enable the Execution and Data and Prediction instructions.
rng   ARMv8.5-A   No
Enable ARMv8.5-A random number instructions.
ssbs   ARMv8-A   ARMv8.5-A or later
Enable Speculative Store Bypassing Safe state read and write.
memtag   ARMv8.5-A   No
Enable ARMv8.5-A Memory Tagging Extensions.
tme   ARMv8-A   No
Enable Transactional Memory Extensions.
sve2   ARMv8-A   No
Enable the SVE2 Extension.
sve2-bitperm   ARMv8-A   No
Enable SVE2 BITPERM Extension.
sve2-sm4   ARMv8-A   No
Enable SVE2 SM4 Extension.
sve2-aes   ARMv8-A   No
Enable SVE2 AES Extension.  This also enables the .Q->.B form of the
pmullt and pmullb instructions.
sve2-sha3   ARMv8-A   No
Enable SVE2 SHA3 Extension.
flagm   ARMv8-A   ARMv8.4-A or later
Enable Flag Manipulation instructions.
ls64   ARMv8.6-A   ARMv8.7-A or later
Enable 64 Byte Loads/Stores.
pauth   ARMv8-A   No
Enable Pointer Authentication.

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 4.4 Register Names of ARMv8 Instruction Set Overview, which is available at http://infocenter.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
==========================

.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.

.bss
     This directive switches to the .bss section.

.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 ARMv8 Instruction Set Overview available at http://infocenter.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.