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

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

Hi Eli,

Thanks for the quick feedback.

On 4/11/23 08:08, Eli Zaretskii wrote:
>> Date: Tue, 11 Apr 2023 05:26:58 +0100
>> From: Luis Machado via Gdb-patches <gdb-patches@sourceware.org>
>>
>> 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(+)
> 
> Thanks.
> 
>> 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.
> 
> This part is OK.
> 
>> +@subsubsection AArch64 SME.
>> +@cindex AArch64 SME.
> 
> Please also add a @cindex entry with the full name: scalable matrix
> extension.
> 
>> +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.
> 
> I suggest to rephrase:
> 
>     The @code{za} register is a 2-dimensional rectangular
>     @code{@var{n}x@var{n}} matrix of bytes, where @var{n} is the
>     streaming vector length.
> 
> Should the text also explain what is this "streaming vector", its
> length and "granule"?  The text seems to use these terms all over
> assuming the reader knows what they mean.
> 
>> +The @code{svg} vector is the streaming vector granule for the current thread
>                    ^^^^^^
> "register", not "vector", right?
> 
>> +and represents the number of 64-bit chunks in one dimension of the @code{za}
>> +register.
> 
> What do you mean by "represents the number"? how can one "represent" a
> number?
> 
> Also, it sounds like the @var{n} I suggested to use above is related
> to this register, in which case the description of ZA should make that
> relation explicit.  (I can suggest how once I understand the subject
> well enough, see the questions above.)
> 
>> +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.
> 
> I suggest to use @sc{sm} and @sc{za} here, instead of @code{SM} and
> @code{ZA}.  Try that in PDF and see which you like better.  (Note that
> @sc has its effect only on lower-case characters of its argument.)
> 
>> +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.
> 
> What does it mean for "the SVE registers will have their sizes based
> on the @code{svg} register"?  The text should explain this more
> explicitly, IMO.
> 
>>            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.
> 
> This refers to stuff explained elsewhere (the 'vg' register), so a
> cross-reference is in order.
> 
>> +If the @code{ZA} state is 0, the @code{za} register and its pseudo registers
>> +will read as <unavailable>.
> 
> What are the pseudo registers of the ZA register?  I don't think they
> were described earlier in the text.
> 
>> +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.
> 
> By "The size of the @code{za} register" do you mean the number of
> bytes in the matrix?  That is, if ZA is 16 x 16, then its size is
> 16*16=256 bytes, or is it 16 bytes?
> 
>> +The @code{za} register can also be referenced using tiles and tile slices.
> 
> Referenced how?  Should the text say anything specific about this
> slice referencing, before talking (below) about the number of 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.
> 
> This should probably preceded by something like
> 
>    A @dfn{tile} of the @code{za} register is a pseudo-register which
>    can be used to... <add here what these tiles are used for>".
> 
>> +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>.
> 
> Likewise here: there should be a short explanation of what are tile
> slices and how to use them.
> 
> All in all, I find this description rather terse and almost
> impenetrable.  I guess only those who are already familiar with this
> architecture will fully understand it.  Maybe this is the assumption
> for the readers of this stuff, but then perhaps include a reference to
> some external description of the architecture, and just say that GDB
> supports this and that registers and pseudo-registers, without going
> into any details regarding the meaning and purpose of each one of
> them.

As is usually the case, developers tend to assume some of the subject matter is already understood by
whoever is developing software using a particular architectural feature. :-)

I agree the current documentation is a bit on the light side. Let me try to fill the gaps in v2.

Hopefully that will make the description of how SME is being used in gdb a bit more clear.

> 
>> +@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).
> 
> This again mentions "svl" without saying anything about it.
> 
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>