G.5.1 AArch64 Features

G.5.1.1 AArch64 core registers feature

The ‘org.gnu.gdb.aarch64.core’ feature is required for AArch64 targets. It must contain the following:

• - ‘x0’ through ‘x30’, the general purpose registers, with size of 64 bits. Register ‘x30’ is also known as the link register, or ‘lr’.
• - ‘sp’, the stack pointer register or ‘x31’. It is 64 bits in size and has a type of ‘data_ptr’.
• - ‘pc’, the program counter register. It is 64 bits in size and has a type of ‘code_ptr’.
• - ‘cpsr’, the current program status register. It is 32 bits in size and has a custom flags type.

The semantics of the individual flags and fields in ‘cpsr’ can change as new architectural features are added. The current layout can be found in the aarch64-core.xml file.

Extra registers are allowed in this feature, but they will not affect GDB.

G.5.1.2 AArch64 floating-point registers feature

The ‘org.gnu.gdb.aarch64.fpu’ feature is optional. If present, it must contain the following registers:

• - ‘v0’ through ‘v31’, the vector registers with size of 128 bits. The type is a custom vector type.
• - ‘fpsr’, the floating-point status register. It is 32 bits in size and has a custom flags type.
• - ‘fpcr’, the floating-point control register. It is 32 bits in size and has a custom flags type.

The semantics of the individual flags and fields in ‘fpsr’ and ‘fpcr’ can change as new architectural features are added.

The types for the vector registers, ‘fpsr’ and ‘fpcr’ registers can be found in the aarch64-fpu.xml file.

Extra registers are allowed in this feature, but they will not affect GDB.

G.5.1.3 AArch64 SVE registers feature

The ‘org.gnu.gdb.aarch64.sve’ feature is optional. If present, it means the target supports the Scalable Vector Extension and must contain the following registers:

• - ‘z0’ through ‘z31’, the scalable vector registers. Their sizes are variable and a multiple of 128 bits up to a maximum of 2048 bit. Their type is a custom union type that helps visualize different sizes of sub-vectors.
• - ‘fpsr’, the floating-point status register. It is 32 bits in size and has a custom flags type.
• - ‘fpcr’, the floating-point control register. It is 32 bits in size and has a custom flags type.
• - ‘p0’ through ‘p15’, the predicate registers. Their sizes are variable, based on the current vector length, and a multiple of 16 bits. Their types are a custom union to help visualize sub-elements.
• - ‘ffr’, the First Fault register. It has a variable size based on the current vector length and is a multiple of 16 bits. The type is the same as the predicate registers.
• - ‘vg’, the vector granule. It represents the number of 64 bits chunks in a ‘z’ register. It is closely associated with the current vector length. It has a type of ‘int’.

When GDB sees the SVE feature, it will assume the Scalable Vector Extension is supported, and will adjust the sizes of the ‘z’, ‘p’ and ‘ffr’ registers accordingly, based on the value of ‘vg’.

GDB will also create pseudo-registers equivalent to the ‘v’ vector registers from the ‘org.gnu.gdb.aarch64.fpu’ feature.

The first 128 bits of the ‘z’ registers overlap the 128 bits of the ‘v’ registers, so changing one will trigger a change to the other.

For the types of the ‘z’, ‘p’ and ‘ffr’ registers, please check the aarch64-sve.c file. No XML file is available for this feature because it is dynamically generated based on the current vector length.

The semantics of the individual flags and fields in ‘fpsr’ and ‘fpcr’ can change as new architectural features are added.

The types for the ‘fpsr’ and ‘fpcr’ registers can be found in the aarch64-sve.c file, and should match what is described in aarch64-fpu.xml.

Extra registers are allowed in this feature, but they will not affect GDB.

G.5.1.4 AArch64 Pointer Authentication registers feature

The ‘org.gnu.gdb.aarch64.pauth’ optional feature was introduced so GDB could detect support for the Pointer Authentication extension. If present, it must contain one of two possible register sets.

Pointer Authentication masks for user-mode:

• - ‘pauth_dmask’, the user-mode pointer authentication mask for data pointers. It is 64 bits in size.
• - ‘pauth_cmask’, the user-mode pointer authentication mask for code pointers. It is 64 bits in size.

Pointer Authentication masks for user-mode and kernel-mode:

• - ‘pauth_dmask’, the user-mode pointer authentication mask for data pointers. It is 64 bits in size.
• - ‘pauth_cmask’, the user-mode pointer authentication mask for code pointers. It is 64 bits in size.
• - ‘pauth_dmask_high’, the kernel-mode pointer authentication mask for data pointers. It is 64 bits in size.
• - ‘pauth_cmask_high’, the kernel-mode pointer authentication mask for code pointers. It is 64 bits in size.

If GDB sees any of the two sets of registers in this feature, it will assume the target is capable of signing pointers. If so, GDB will decorate backtraces with a ‘[PAC]’ marker alongside a function that has a signed link register value that needs to be unmasked/decoded.

GDB will also use the masks to remove non-address bits from pointers.

Extra registers are allowed in this feature, but they will not affect GDB.

Please note the ‘org.gnu.gdb.aarch64.pauth’ feature string is deprecated and must only be used for backwards compatibility with older releases of GDB and gdbserver. Targets that support Pointer Authentication must advertise such capability by using the ‘org.gnu.gdb.aarch64.pauth_v2’ feature string instead.

The ‘org.gnu.gdb.aarch64.pauth_v2’ feature has the exact same contents as feature ‘org.gnu.gdb.aarch64.pauth’.

The reason for having feature ‘org.gnu.gdb.aarch64.pauth_v2’ is a bug in previous versions of GDB (versions 9, 10, 11 and 12). This bug caused GDB to crash whenever the target reported support for Pointer Authentication (using feature string ‘org.gnu.gdb.aarch64.pauth’) and also reported additional system registers that were not accounted for by GDB. This is more common when using emulators and on bare-metal debugging scenarios.

It can also happen if a newer gdbserver is used with an old GDB that has the bug. In such a case, the newer gdbserver might report Pointer Authentication support via the ‘org.gnu.gdb.aarch64.pauth’ feature string and also report additional registers the older GDB does not know about, potentially leading to a crash.

G.5.1.5 AArch64 TLS registers feature

The ‘org.gnu.gdb.aarch64.tls’ optional feature was introduced to expose the TLS registers to GDB. If present, it must contain either one of the following register sets.

Only ‘tpidr’:

• - ‘tpidr’, the software thread id register. It is 64 bits in size and has a type of ‘data_ptr’.

Both ‘tpidr’ and ‘tpidr2’.

• - ‘tpidr’, the software thread id register. It is 64 bits in size and has a type of ‘data_ptr’.
• - ‘tpidr2’, the second software thread id register. It is 64 bits in size and has a type of ‘data_ptr’. It may be used in the future alongside the Scalable Matrix Extension for a lazy restore scheme.

If GDB sees this feature, it will attempt to find one of the variations of the register set. If ‘tpidr2’ is available, GDB may act on it to display additional data in the future.

There is no XML for this feature as the presence of ‘tpidr2’ is determined dynamically at runtime.

Extra registers are allowed in this feature, but they will not affect GDB.

G.5.1.6 AArch64 MTE registers feature

The ‘org.gnu.gdb.aarch64.mte’ optional feature was introduced so GDB could detect support for the Memory Tagging Extension and control memory tagging settings. If present, this feature must have the following register:

• - ‘tag_ctl’, the tag control register. It is 64 bits in size and has a type of ‘uint64’.

Memory Tagging detection is done via a runtime check though, so the presence of this feature and register is not enough to enable memory tagging support.

This restriction may be lifted in the future.

Extra registers are allowed in this feature, but they will not affect GDB.

G.5.1.7 AArch64 SME registers feature

The ‘org.gnu.gdb.aarch64.sme’ feature is optional. If present, it should contain registers ZA, SVG and SVCR. See AArch64 SME.

• - ZA is a register represented by a vector of svlxsvl bytes. See svl.
• - SVG is a 64-bit register containing the value of svg. See svg.
• - SVCR is a 64-bit status pseudo-register with two valid bits. Bit 0 (SM) shows whether the streaming SVE mode is enabled or disabled. Bit 1 (ZA) shows whether the ZA register state is active (in use) or not. See aarch64 sme svcr.

  The rest of the unused bits of the SVCR pseudo-register is undefined and reserved. Such bits should not be used and may be defined by future extensions of the architecture.

Extra registers are allowed in this feature, but they will not affect GDB.

The ‘org.gnu.gdb.aarch64.sme’ feature is required when the target also reports support for the ‘org.gnu.gdb.aarch64.sme2’ feature.

G.5.1.8 AArch64 SME2 registers feature

The ‘org.gnu.gdb.aarch64.sme2’ feature is optional. If present, then the ‘org.gnu.gdb.aarch64.sme’ feature must also be present. The ‘org.gnu.gdb.aarch64.sme2’ feature should contain the following: See AArch64 SME2.

• - ZT0 is a register of 512 bits (64 bytes). It is defined as a vector of bytes.

Extra registers are allowed in this feature, but they will not affect GDB.