[Lldb-commits] [lldb] bc36746 - [lldb][docs] Add documentation for AArch64 Linux SME only support (#165415)

[via lldb-commits]

Author: David Spickett
Date: 2026-04-01T13:59:09+01:00
New Revision: bc36746ddfee3ca7724e00311f6371090a43754c

URL: https://github.com/llvm/llvm-project/commit/bc36746ddfee3ca7724e00311f6371090a43754c
DIFF: https://github.com/llvm/llvm-project/commit/bc36746ddfee3ca7724e00311f6371090a43754c.diff

LOG: [lldb][docs] Add documentation for AArch64 Linux SME only support (#165415)

As for other features, this is a mixture of user facing decisions and
internal design decisions.

Added: 
    

Modified: 
    lldb/docs/use/aarch64-linux.md

Removed: 
    


################################################################################
diff  --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md
index 164d25cef6721..f48693ab58704 100644
--- a/lldb/docs/use/aarch64-linux.md
+++ b/lldb/docs/use/aarch64-linux.md
@@ -230,6 +230,77 @@ 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, 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.
+
+### 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. 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.
+
+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. `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 in non-streaming mode. They cannot be
+written to in non-streaming mode.
+
+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 state, LLDB generates the fake value, in the latter state, the
+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.
+
+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 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. All
+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
+[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.
+
+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: