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

[Eli Zaretskii <eliz@gnu.org>]

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

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