[PATCH] docs: Clarify gdb remote protocol AArch64 SVE and SME handling

[Peter Maydell <peter.maydell@linaro.org>]

The documentation of the AArch64 target features for the gdb remote
protocol has some areas where it is unclear about SVE and SME:

 * it doesn't say what to do if the target has only SME

 * it isn't clear about what the org.gnu.gdb.aarch64.sve vector
   register size should be when both SME and SVE are present

Clarify/correct the documentation:

 * org.gnu.gdb.aarch64.sve is effectively "the feature for the z
   vector registers", and must be provided even when the target only
   implements SME (because the z registers exist in an SME only CPU)

 * the z register size and the 'vg' pseudoregister in
   org.gnu.gdb.aarch64.sve follow the architectural "effective SVE
   vector length", which might be either the non-streaming SVE vector
   length or the streaming SVE vector length

Reviewed-by: Thiago Jung Bauermann <thiago.bauermann@linaro.org>
---
 gdb/doc/gdb.texinfo | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 80f49e21b7e..711a45435ef 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -49742,7 +49742,8 @@ Extra registers are allowed in this feature, but they will not affect
 @subsubsection AArch64 SVE registers feature
 
 The @samp{org.gnu.gdb.aarch64.sve} feature is optional.  If present,
-it means the target supports the Scalable Vector Extension and must contain
+it means the target supports either the Scalable Vector Extension (SVE) or
+the Scalable Matrix Extension (SME) and must contain
 the following registers:
 
 @itemize @minus
@@ -49780,6 +49781,14 @@ vector registers from the @samp{org.gnu.gdb.aarch64.fpu} feature.
 The first 128 bits of the @samp{z} registers overlap the 128 bits of the
 @samp{v} registers, so changing one will trigger a change to the other.
 
+@samp{vg} represents the size of the @samp{z} registers, and is what
+the Arm architecture defines as the ``Effective SVE vector length''. That
+means that if the target implements SME and is in streaming vector mode,
+it is the streaming vector length. If the target implements only SME and
+not SVE, and is not in streaming vector mode, then @samp{vg} is 2
+(indicating 128-bit vectors) and the @samp{z} registers match the @samp{v}
+FPU registers.
+
 For the types of the @samp{z}, @samp{p} and @samp{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.
@@ -49793,6 +49802,9 @@ 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
 @value{GDBN}.
 
+The @samp{org.gnu.gdb.aarch64.sve} feature is required when the target also
+reports support for the @samp{org.gnu.gdb.aarch64.sme} feature.
+
 @subsubsection AArch64 Pointer Authentication registers feature
 
 The @samp{org.gnu.gdb.aarch64.pauth} optional feature was introduced so
@@ -49948,6 +49960,10 @@ extensions of the architecture.
 Extra registers are allowed in this feature, but they will not affect
 @value{GDBN}.
 
+Note that a target with only SME but not SVE support must still
+provide the @samp{org.gnu.gdb.aarch64.sve} feature, to expose the
+@samp{z} vector registers.
+
 The @samp{org.gnu.gdb.aarch64.sme} feature is required when the target also
 reports support for the @samp{org.gnu.gdb.aarch64.sme2} feature.
 
-- 
2.43.0