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

[Eli Zaretskii via Gdb-patches <gdb-patches@sourceware.org>]

> From: Luis Machado <luis.machado@arm.com>
> Date: Mon, 17 Apr 2023 18:19:45 +0100
> 
> 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 | 249 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 260 insertions(+)

Thanks.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 54b5da21245..e3ce7d7e881 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.
> +
>  * The AArch64 'org.gnu.gdb.aarch64.pauth' Pointer Authentication feature string
>    has been deprecated in favor of the 'org.gnu.gdb.aarch64.pauth_v2' feature
>    string.

This part is OK.

> +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.

I thought we agreed to use @var{vl}, @var{vq}, etc., instead of
@code{VL} etc.?  These are meta-syntactic parameters, they stand for
something else, not literally for themselves, so @var is more
appropriate.

Also, you place @cindex between @item and the text of the @item -- did
you verify that typing "i VQ" in an Info reader goes to the beginning
of the item's line?  I think @cindex should be before @item.

> +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

Elsewhere you use @code{za}, lower-case, for the register.  Please be
consistent in the capitalization of the register names.

> +(@code{SVL} for short). @xref{VL} @xref{SVL}
                         ^^
Two spaces there.

> +@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}}.
> +
> +When streaming mode is enabled, it defines the size of the @acronym{SVE}
> +registers as well.
> +
> +@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.

Likewise here: I thought we agreed on using @var{svl} etc., not
@code{SVL}.

> +The @code{za} register is a 2-dimensional square @code{@var{SVL}x@var{SVL}}

And here you actually use @var (which is correct), but with an
upper-case argument, which is sub-optimal.  The argument of @var
should be in lower-case.

> +@item
> +@samp{za} is a register represented by a vector of @code{SVL} x @code{SVL}
                                                      ^^^^^^^^^^^^^^^^^^^^^^^
This should use @var, not @code.  Also, I'd remove the whitespace
around "x".

Reviewed-By: Eli Zaretskii <eliz@gnu.org>