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

[Luis Machado via Gdb-patches <gdb-patches@sourceware.org>]

On 4/22/23 10:21, Eli Zaretskii wrote:
>> 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.

Ok. That wasn't completely clear to me. I've made the change now.

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

You're right. Fixed and verified now.

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

All the uses of za should now be lower-case.

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

Fixed.

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

Fixed now.

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

Fixed.

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

Fixed. But I used spaces between "x" and the two @var entries because it gets rendered as a single
block of characters like svlxsvl.

Using @math{x} doesn't look too nice. Suggestions?

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