[PATCH 17/17] [gdb/docs] sme: Document SME registers and features

[Luis Machado <luis.machado@arm.com>]

Provide documentation for the SME feature and other information that
should be useful for users that need to debug a SME-capable target.
---
 gdb/NEWS            | 11 ++++++++
 gdb/doc/gdb.texinfo | 68 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 10a1a70fa52..48a82172f0e 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -3,6 +3,17 @@
 
 *** Changes since GDB 13
 
+* GDB now supports the AArch64 Scalable Matrix Extension (SME), which includes
+  a new matrix register named ZA, a new thread register TPIDR2 and a new vector
+  length register SVG (streaming vector granule).  GDB also supports tracking
+  ZA state across signal frames.  
+
+  Some features are still under development or are dependent on ABI specs that
+  are still in alpha stage.  For example, manual function calls with ZA state
+  don't have any special handling, and tracking of SVG changes based on
+  DWARF information is still not implemented, but there are plans to do so in
+  the future.
+
 * GDB now has some support for integer types larger than 64 bits.
 
 * Removed targets and native configurations
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 2d5358a792b..f84e05fbed2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -26038,6 +26038,61 @@ but the lengths of the @code{z} and @code{p} registers will not change.  This
 is a known limitation of @value{GDBN} and does not affect the execution of the
 target process.
 
+@subsubsection AArch64 SME.
+@cindex AArch64 SME.
+
+When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix
+Extension (SME) is present, then @value{GDBN} will provide the @code{za}
+register.  @value{GDBN} will also provide the  @code{svg} pseudo register and
+the @code{svcr} pseudo register.
+
+The @code{za} register is a 2-dimensional vector of bytes with a size of svl
+x svl, where svl is the streaming vector length.
+
+The @code{svg} vector is the streaming vector granule for the current thread
+and represents the number of 64-bit chunks in one dimension of the @code{za}
+register.
+
+The @code{svcr} register (streaming vector control register) is a status
+register that holds two state bits: @code{SM} in bit 0 and @code{ZA} in bit 1.
+
+If the @code{SM} bit is 1, it means the current thread is in streaming
+mode, and the SVE registers will have their sizes based on the @code{svg}
+register.  If the @code{SM} bit is 0, the current thread is not in streaming
+mode, and the SVE registers have sizes based on the @code{vg} register.
+
+If the @code{ZA} bit is 1, it means the @code{ZA} state, and therefore the
+@code{za} register, is being used and has meaningful contents.  If the
+@code{ZA} bit is 0, the ZA state is unavailable and the contents of the
+@code{za} register are undefined.
+
+If the @code{ZA} state is 0, the @code{za} register and its pseudo registers
+will read as <unavailable>.
+
+If the streaming vector length changes, then the @code{svg} register will be
+updated,  as well as the @code{za} register.
+
+The possible values for @code{svg} are 2, 4, 8, 16, 32.  These numbers
+correspond to streaming vector length values of 16 bytes, 32 bytes, 64 bytes,
+128 bytes and 256 bytes.
+
+The minimum size of the @code{za} register is there 16 x 16 bytes, and the
+maximum size is 256 x 256 bytes.  The size of the @code{za} register is the
+size of all the SVE @code{z} registers combined.
+
+The @code{za} register can also be referenced using tiles and tile slices.
+
+There is a fixed number of @code{za} tile pseudo registers (32). They are:
+za0b, za0h, za1h, zas0, zas1, zas2, zas3, zad0, zad1, zad2, zad3, zad4, zad5.
+
+The tile slice pseudo registers are numerous.  For a minimum streaming vector
+length of 16 bytes, there are 5 x 32 pseudo registers.  For the maximum
+streaming vector length of 256 bytes, there are 5 x 512 pseudo registers.
+
+The tile slice pseudo registers have the following naming pattern:
+
+za<tile number><orientation><slice number>.
+
 @subsubsection AArch64 Pointer Authentication.
 @cindex AArch64 Pointer Authentication.
 @anchor{AArch64 PAC}
@@ -48030,6 +48085,19 @@ This restriction may be lifted in the future.
 Extra registers are allowed in this feature, but they will not affect
 @value{GDBN}.
 
+The @samp{org.gnu.gdb.aarch64.sme} feature is optional.  If present,
+it should contain registers @samp{za}, @samp{svg} and @samp{svcr}.
+
+@samp{za} is a vector of bytes of size svl x svl.  @samp{svg} is a 64-bit
+pseudo register containing the number of 64-bit chunks in svl.  @samp{svcr}
+is a 64-bit state register containing bits 0 (SM) and 1 (ZA).
+
+The rest of the unused bits of @samp{svcr} are undefined and reserved.  They
+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
+@value{GDBN}.
+
 @node ARC Features
 @subsection ARC Features
 @cindex target descriptions, ARC Features
-- 
2.25.1