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

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

Updates since v1:

- Made SME text more thorough.
- Adjusted text based on upstream reviews.
- Fixed documentation errors (missing itemization for SME registers).

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 | 223 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 234 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 45a0580bc29..ef6dfd02623 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -26045,6 +26045,202 @@ 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.
 
+For SVE, the following definitions are used throughout @value{GDBN}'s source
+code and in this document:
+
+@itemize
+
+@item
+@anchor{VL}
+@cindex VL
+@code{VL}: The vector length, in bytes.  It defines the size of each @code{Z}
+register.
+
+@item
+@anchor{VQ}
+@cindex VQ
+@code{VQ}: The number of 128 bit units in @code{VL}.  This is mostly used
+internally by @value{GDBN} and the Linux Kernel.
+
+@item
+@anchor{VG}
+@cindex VG
+@code{VG}: The number of 64 bit units in @code{VL}.  This is mostly used
+internally by @value{GDBN} and the Linux Kernel.
+
+@end itemize
+
+@subsubsection AArch64 SME.
+@anchor{AArch64 SME}
+@cindex SME
+@cindex AArch64 SME
+@cindex Scalable Matrix Extension
+
+The Scalable Matrix Extension (@url{https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture, @acronym{SME}})
+is an AArch64 architecture extension that expands on the concept of the
+Scalable Vector Extension (@url{https://developer.arm.com/documentation/101726/4-0/Learn-about-the-Scalable-Vector-Extension--SVE-/What-is-the-Scalable-Vector-Extension-, @acronym{SVE}})
+by providing a 2-dimensional square matrix of variable size called @code{ZA},
+just like SVE provides a group of vector registers of variable size, the
+32 @code{Z} registers.
+
+Similarly to SVE, where the size of each @code{Z} register is directly related
+to the vector length (@code{VL} for short), the @acronym{SME} @code{ZA} matrix
+register's size is directly related to the streaming vector length
+(@code{SVL} for short). @xref{VL} @xref{SVL}
+
+For more information about @acronym{SME}, please refer to official
+@url{https://developer.arm.com/documentation/ddi0487/latest, architecture
+documentation}.
+
+The following definitions are used throughout @value{GDBN}'s source code and
+in this document:
+
+@itemize
+
+@item
+@anchor{SVL}
+@cindex SVL
+@code{SVL}: The streaming vector length, in bytes.  It defines the size of each
+dimension of the 2-dimensional square @code{ZA} matrix.  The total size of
+@code{ZA} is therefore @code{@var{SVL}x@var{SVL}}.
+
+@item
+@anchor{SVQ}
+@cindex SVQ
+@code{SVQ}: The number of 128 bit units in @code{SVL}.  This is mostly used
+internally by @value{GDBN} and the Linux Kernel.
+
+@item
+@anchor{SVG}
+@cindex SVG
+@code{SVG}: The number of 64 bit units in @code{SVL}.  This is mostly used
+internally by @value{GDBN} and the Linux Kernel.
+
+@end itemize
+
+When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix
+Extension (@acronym{SME}) is present, then @value{GDBN} will make the @code{za}
+register available.  @value{GDBN} will also make the @code{svg} and @code{svcr}
+pseudo-registers available.
+
+The @code{za} register is a 2-dimensional square @code{@var{n}x@var{n}}
+matrix of bytes, where @var{n} is the streaming vector length (@code{SVL}.  To
+simplify the representation and access to the @code{za} register in
+@value{GDBN}, it is defined as a vector of @code{@var{n}x@var{n}} bytes.
+@xref{SVL}
+
+If the user wants to index the @code{za} register as a matrix, it is possible
+to reference @code{za} as @code{za[i][j]}, where @var{i} is the row number
+and @var{j} is the column number.
+
+The @code{svg} register is the streaming vector granule (@code{SVG}) for the
+current thread. @xref{SVG}
+
+@anchor{aarch64 sme svcr}
+The @code{svcr} register (streaming vector control register) is a status
+register that holds two state bits: @sc{sm} in bit 0 and @sc{za} in bit 1.
+
+If the @sc{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 @sc{sm} bit is 0, the current thread is not in streaming
+mode, and the SVE registers have sizes based on the @code{vg} register.
+@xref{VG}. @xref{SVG}.
+
+If the @sc{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
+@sc{za} bit is 0, the @code{ZA} state is unavailable and the contents of the
+@code{za} register are undefined.
+
+For convenience and simplicity, if the @sc{za} bit is 0, the @code{za}
+register and all of its pseudo-registers will read as zero.
+
+If the streaming vector length changes, then the @code{svg} pseudo-register
+will be updated, as well as the @code{za} register size and the bits in the
+@code{svcr} pseudo-register.
+
+Setting the @code{svg} register to the same value will have no
+effect.  Whenever the @code{svg} register is modified with a new value, the
+following will be observed:
+
+@itemize
+
+@item The @sc{za} and @sc{sm} bits will be cleared in the @code{svcr}
+register.
+
+@item The @code{za} register will have a new size and its state will be
+cleared, forcing its contents and the contents of all of its pseudo-registers
+back to zero.
+
+@item If the @sc{sm} bit was 1, the SVE registers will be reset to having
+their sizes dictated by the @code{vg} register as opposed to the @code{svg}
+register.  If the @sc{sm} bit was 0 prior to modifying @code{svg}, there
+will be no observable effect on the SVE registers.
+
+@end itemize
+
+The possible values for @code{svg} are 2, 4, 8, 16, 32 (1, 2, 4, 8, 16
+for svq).  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 16 x 16 (256) bytes, and the
+maximum size is 256 x 256 (65536) bytes.  In streaming mode, with bit @sc{sm}
+set, 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 accessed using tiles and tile slices.
+
+Tile pseudo-registers are square, 2-dimensional sub-arrays of elements within
+the @code{za} register.
+
+There is a fixed number of @code{za} tile pseudo registers (32).  They are
+@code{za0b}, @code{za0h} through @code{za1h}, @code{zas0} through @code{zas3},
+@code{zad0} through @code{zad7} and @code{zaq0} through @code{zaq15}.
+
+Tile slice pseudo-registers are vectors of horizontally or vertically
+contiguous elements within the @code{za} register.
+
+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<@var{tile number}><@var{orientation}><@var{slice number}>.
+
+There are up to 16 tiles (0 ~ 15), the orientation can be either vertical (v)
+or horizontal (h) and there are up to 256 slices (0 ~ 255) depending on the
+value of @code{svg}.
+
+When listing all the available registers, users will see the
+currently-available @code{za} pseudo-registers.  Pseudo-registers that don't
+exist for a given @code{svg} value will not be displayed.
+
+For more information on @acronym{SME} and its terminology, please refer to the
+@url{https://developer.arm.com/documentation/ddi0616/aa/,
+Arm Architecture Reference Manual Supplement}, The Scalable Matrix Extension
+(@acronym{SME}), for Armv9-A.
+
+Some features are still under development and rely on ACLE and ABI
+definitions, so there are known limitations to the current @acronym{SME}
+support in @value{GDBN}.
+
+One such example is calling functions by hand from @value{GDBN}.  Hand calls
+are not @acronym{SME}-aware and thus don't take into account the @code{svcr}
+bits nor the @code{za} contents.
+
+The lazy saving scheme involving the @code{tpidr2} register is not yet
+supported by @value{GDBN}, though the @code{tpidr2} register is known
+and supported by @value{GDBN}.
+
+Lastly, an important limitation for @code{gdbserver} is its inability to
+communicate changes in the streaming vector length to @value{GDBN}.  This
+means @code{gdbserver}, even though it is capable of adjusting its internal
+caches to reflect a change to @code{svg}, will operate with a potentially
+different @code{svg} value compared to @value{GDBN}.  This can lead to
+@value{GDBN} showing incorrect values for the @code{za} register and
+incorrect values for SVE registers (when the @sc{m} bit is on).
+
+This is the same limitation we have for the SVE registers.
+
 @subsubsection AArch64 Pointer Authentication.
 @cindex AArch64 Pointer Authentication.
 @anchor{AArch64 PAC}
@@ -48037,6 +48233,33 @@ This restriction may be lifted in the future.
 Extra registers are allowed in this feature, but they will not affect
 @value{GDBN}.
 
+@subsubsection AArch64 SME registers feature
+
+The @samp{org.gnu.gdb.aarch64.sme} feature is optional.  If present,
+it should contain registers @samp{za}, @samp{svg} and @samp{svcr}.
+@xref{AArch64 SME}
+
+@itemize @minus
+
+@item
+@samp{za} is a vector of bytes of size svl x svl.
+
+@item
+@samp{svg} is a 64-bit pseudo register containing the number of 64-bit chunks
+in svl. @xref{SVG}
+
+@item
+@samp{svcr} is a 64-bit state register containing bits 0 (@sc{sm}) and
+1 (@sc{za}). @xref{aarch64 sme svcr}
+
+The rest of the unused bits of @samp{svcr} is undefined and reserved.  They
+should not be used and may be defined by future extensions of the architecture.
+
+@end itemize
+
+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