[Lldb-commits] [lldb] [lldb][docs] Add documentation for AArch64 Linux SME only support (PR #165415)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Wed Apr 1 05:46:36 PDT 2026
https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/165415
>From f7c4f813060ee2abc8e13604d27d57555701997c Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Tue, 28 Oct 2025 10:38:17 +0000
Subject: [PATCH 1/5] [lldb][docs] Add documentation for AArch64 Linux SME only
support
---
lldb/docs/use/aarch64-linux.md | 69 ++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md
index 164d25cef6721..1a301adce7a99 100644
--- a/lldb/docs/use/aarch64-linux.md
+++ b/lldb/docs/use/aarch64-linux.md
@@ -230,6 +230,75 @@ bytes.
`zt0`'s value and whether it is active or not will be saved prior to
expression evaluation and restored afterwards.
+## SME Only Systems
+
+AArch64 systems may have both SVE and SME (that is, `FEAT_SVE` and `FEAT_SVE`),
+or they can have only SME. If they only have SME, the system has the usual
+SVE state, but that state and SVE instructions may only be used while in
+streaming mode.
+
+The LLDB experience is very similar to SVE+SME systems, with a few notable
+changes.
+
+### Registers
+
+When in streaming mode, registers act as they would on an SVE+SME system.
+Outside of streaming mode LLDB will show the `Z` registers as zero extended copies
+of the `V` registers.
+
+Writes to `Z` registers are allowed, but these are converted to `V` register writes
+and so only the bottom 128-bits will be applied. Note that the size of the value
+written to a `Z` register must match the current streaming vector length, even if
+the process is in non-streaming mode.
+
+It is useful for LLDB developers to know that for an SME only system,
+`lldb-server` describes the system as having `Z` registers with `V` registers
+as subsets of those registers. We do not change the representation each time
+the mode changes.
+
+A consequence of this is that if the user writes to a `V` register while in
+non-streaming mode, it will be sent to `lldb-server` as a `Z` register write
+of a zero extended value. Then `lldb-server` will convert that back into a `V`
+register write with the value truncated to 128-bit.
+
+In streaming mode, it will be zero extended, sent as a `Z` write and written
+to the real streaming SVE `Z` register without truncation.
+
+`P` registers will be shown as 0s outside of streaming mode. They cannot be written
+to in this state.
+
+The `ffr` register will also be shown as 0s outside of streaming mode. In streaming
+mode, use of `ffr` is forbidden so it will also show as 0s. It cannot be written
+to in either state.
+
+(in the former, LLDB generates the fake value, in the latter, the kernel
+generates it)
+
+The `ZA` and `ZT0` registers act as they would for an SVE+SME system.
+
+Since there is no non-streaming SVE, there is non non-streaming vector length.
+Therefore even in non-streaming mode, the value shown in `vg` will be the
+streaming vector length, and be equal to the value shown for `svg`.
+
+### Expression Evaluation
+
+Some instructions are illegal to use in streaming mode (unless `FEAT_SMEFA64`
+is present). LLDB will not make any attempt to make expressions compatible
+with the current mode. If part of the expression is not compatible, it will
+result in a SIGILL that will be cleaned up as it normally would be.
+
+All register, ZA and mode state will be restored as normal after an expression.
+
+Note that to restore to a non-streaming state from a streaming state, LLDB uses
+a special part of the Linux Kernel's
+[SME ABI](https://docs.kernel.org/arch/arm64/sme.html). Where FPSIMD data is
+written to the non-existent non-streaming SVE register set, with the vector
+length set to 0 to cause the process to exit streaming mode.
+
+This is only used for this purpose. Otherwise, in non-streaming mode FP
+registers are accessed using the FP register set, and in streaming mode using
+the streaming SVE register set.
+
## Guarded Control Stack Extension (GCS)
GCS support includes the following new registers:
>From b6ea454583d8dd3aaa1c01f443e5553a3194f307 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 5 Nov 2025 14:38:34 +0000
Subject: [PATCH 2/5] misc
---
lldb/docs/use/aarch64-linux.md | 45 +++++++++++++++++-----------------
1 file changed, 22 insertions(+), 23 deletions(-)
diff --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md
index 1a301adce7a99..9ce364d30f38f 100644
--- a/lldb/docs/use/aarch64-linux.md
+++ b/lldb/docs/use/aarch64-linux.md
@@ -232,13 +232,12 @@ expression evaluation and restored afterwards.
## SME Only Systems
-AArch64 systems may have both SVE and SME (that is, `FEAT_SVE` and `FEAT_SVE`),
+AArch64 systems may have both SVE and SME (that is, `FEAT_SVE` and `FEAT_SME`),
or they can have only SME. If they only have SME, the system has the usual
SVE state, but that state and SVE instructions may only be used while in
streaming mode.
-The LLDB experience is very similar to SVE+SME systems, with a few notable
-changes.
+The LLDB experience is very similar to SVE+SME systems, with a few changes.
### Registers
@@ -247,53 +246,53 @@ Outside of streaming mode LLDB will show the `Z` registers as zero extended copi
of the `V` registers.
Writes to `Z` registers are allowed, but these are converted to `V` register writes
-and so only the bottom 128-bits will be applied. Note that the size of the value
+and so only the bottom 128-bits will be applied. The size of the value
written to a `Z` register must match the current streaming vector length, even if
the process is in non-streaming mode.
-It is useful for LLDB developers to know that for an SME only system,
-`lldb-server` describes the system as having `Z` registers with `V` registers
-as subsets of those registers. We do not change the representation each time
-the mode changes.
+For an SME only system, `lldb-server` describes the system as having `Z`
+registers with `V` registers as subsets of those registers. We do not change the
+representation each time the mode changes.
A consequence of this is that if the user writes to a `V` register while in
non-streaming mode, it will be sent to `lldb-server` as a `Z` register write
-of a zero extended value. Then `lldb-server` will convert that back into a `V`
-register write with the value truncated to 128-bit.
+of a zero extended value. `lldb-server` will convert that back into a `V`
+register write with the value truncated to 128-bits.
In streaming mode, it will be zero extended, sent as a `Z` write and written
to the real streaming SVE `Z` register without truncation.
-`P` registers will be shown as 0s outside of streaming mode. They cannot be written
-to in this state.
+`P` registers will be shown as 0s in non-streaming mode. They cannot be
+written to in non-streaming mode.
-The `ffr` register will also be shown as 0s outside of streaming mode. In streaming
+The `ffr` register will also be shown as 0s in non-streaming mode. In streaming
mode, use of `ffr` is forbidden so it will also show as 0s. It cannot be written
to in either state.
-(in the former, LLDB generates the fake value, in the latter, the kernel
-generates it)
+(in the former state, LLDB generates the fake value, in the latter state, the
+kernel tells `lldb-server` that the value is 0)
The `ZA` and `ZT0` registers act as they would for an SVE+SME system.
-Since there is no non-streaming SVE, there is non non-streaming vector length.
+Since there is no non-streaming SVE, there is no non-streaming vector length.
Therefore even in non-streaming mode, the value shown in `vg` will be the
-streaming vector length, and be equal to the value shown for `svg`.
+streaming vector length, and it will be equal to the value of `svg`.
### Expression Evaluation
-Some instructions are illegal to use in streaming mode (unless `FEAT_SMEFA64`
-is present). LLDB will not make any attempt to make expressions compatible
-with the current mode. If part of the expression is not compatible, it will
-result in a SIGILL that will be cleaned up as it normally would be.
+Some instructions are illegal to use in streaming mode, unless `FEAT_SMEFA64`
+is present. LLDB will not make any attempt to make expressions compatible
+with the current mode. If part of an expression is not compatible, it will
+result in a `SIGILL` that will be cleaned up as any other signal would be.
All register, ZA and mode state will be restored as normal after an expression.
Note that to restore to a non-streaming state from a streaming state, LLDB uses
a special part of the Linux Kernel's
-[SME ABI](https://docs.kernel.org/arch/arm64/sme.html). Where FPSIMD data is
+[SME ABI](https://docs.kernel.org/arch/arm64/sme.html). FPSIMD format data is
written to the non-existent non-streaming SVE register set, with the vector
-length set to 0 to cause the process to exit streaming mode.
+length set to 0 to cause the process to exit streaming mode and apply those
+FPSIMD values to the `V` registers.
This is only used for this purpose. Otherwise, in non-streaming mode FP
registers are accessed using the FP register set, and in streaming mode using
>From 3ef725d6e8cc952035bad007015b2a3e4f9b2c72 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 5 Nov 2025 14:39:38 +0000
Subject: [PATCH 3/5] ephasise expression compatibility
---
lldb/docs/use/aarch64-linux.md | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md
index 9ce364d30f38f..7b296b569cb11 100644
--- a/lldb/docs/use/aarch64-linux.md
+++ b/lldb/docs/use/aarch64-linux.md
@@ -281,11 +281,14 @@ streaming vector length, and it will be equal to the value of `svg`.
### Expression Evaluation
Some instructions are illegal to use in streaming mode, unless `FEAT_SMEFA64`
-is present. LLDB will not make any attempt to make expressions compatible
-with the current mode. If part of an expression is not compatible, it will
-result in a `SIGILL` that will be cleaned up as any other signal would be.
+is present.
-All register, ZA and mode state will be restored as normal after an expression.
+LLDB **will not** make any attempt to make expressions compatible with the
+current mode.
+
+If part of an expression is not compatible, it will
+result in a `SIGILL` that will be cleaned up as any other signal would be. All
+register, ZA and mode state will be restored as normal after an expression.
Note that to restore to a non-streaming state from a streaming state, LLDB uses
a special part of the Linux Kernel's
>From cfceb0288d846babb6417633d9317678b1ff2651 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 5 Nov 2025 14:40:20 +0000
Subject: [PATCH 4/5] misc
---
lldb/docs/use/aarch64-linux.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md
index 7b296b569cb11..cdf653d05a4f9 100644
--- a/lldb/docs/use/aarch64-linux.md
+++ b/lldb/docs/use/aarch64-linux.md
@@ -288,7 +288,7 @@ current mode.
If part of an expression is not compatible, it will
result in a `SIGILL` that will be cleaned up as any other signal would be. All
-register, ZA and mode state will be restored as normal after an expression.
+register, `ZA` and mode state will be restored as normal after an expression.
Note that to restore to a non-streaming state from a streaming state, LLDB uses
a special part of the Linux Kernel's
>From 92ddb826907ece92f072087f35bd4c3cc9a99b68 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at arm.com>
Date: Wed, 1 Apr 2026 12:42:29 +0000
Subject: [PATCH 5/5] corrections
---
lldb/docs/use/aarch64-linux.md | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md
index cdf653d05a4f9..f48693ab58704 100644
--- a/lldb/docs/use/aarch64-linux.md
+++ b/lldb/docs/use/aarch64-linux.md
@@ -232,10 +232,9 @@ expression evaluation and restored afterwards.
## SME Only Systems
-AArch64 systems may have both SVE and SME (that is, `FEAT_SVE` and `FEAT_SME`),
-or they can have only SME. If they only have SME, the system has the usual
-SVE state, but that state and SVE instructions may only be used while in
-streaming mode.
+AArch64 systems may have both SVE and SME, or they can have only SME. If they
+only have SME, the system has the usual SVE state, but that state and SVE
+instructions may only be used while in streaming mode.
The LLDB experience is very similar to SVE+SME systems, with a few changes.
@@ -270,7 +269,7 @@ mode, use of `ffr` is forbidden so it will also show as 0s. It cannot be written
to in either state.
(in the former state, LLDB generates the fake value, in the latter state, the
-kernel tells `lldb-server` that the value is 0)
+kernel tells `lldb-server` that the value is 0, the result is the same)
The `ZA` and `ZT0` registers act as they would for an SVE+SME system.
@@ -288,11 +287,12 @@ current mode.
If part of an expression is not compatible, it will
result in a `SIGILL` that will be cleaned up as any other signal would be. All
-register, `ZA` and mode state will be restored as normal after an expression.
+register, `ZA` and mode state will be restored as normal after expression
+evaluation.
Note that to restore to a non-streaming state from a streaming state, LLDB uses
a special part of the Linux Kernel's
-[SME ABI](https://docs.kernel.org/arch/arm64/sme.html). FPSIMD format data is
+[SVE ABI](https://docs.kernel.org/arch/arm64/sve.html). FPSIMD format data is
written to the non-existent non-streaming SVE register set, with the vector
length set to 0 to cause the process to exit streaming mode and apply those
FPSIMD values to the `V` registers.
More information about the lldb-commits
mailing list