[17/17,gdb/docs] sme: Document SME registers and features
Commit Message
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(+)
Comments
> 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>
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>
@@ -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.
* Removed targets and native configurations
@@ -26038,6 +26038,61 @@ but the lengths of the @code{z} and @code{p} registers will not change. This
is a known limitation of @value{GDBN} and does not affect the execution of the
target process.
+@subsubsection AArch64 SME.
+@cindex AArch64 SME.
+
+When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix
+Extension (SME) is present, then @value{GDBN} will provide the @code{za}
+register. @value{GDBN} will also provide the @code{svg} pseudo register and
+the @code{svcr} pseudo register.
+
+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.
+
+The @code{svg} vector is the streaming vector granule for the current thread
+and represents the number of 64-bit chunks in one dimension of the @code{za}
+register.
+
+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.
+
+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. 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.
+
+If the @code{ZA} bit is 1, it means the @code{ZA} state, and therefore the
+@code{za} register, is being used and has meaningful contents. If the
+@code{ZA} bit is 0, the ZA state is unavailable and the contents of the
+@code{za} register are undefined.
+
+If the @code{ZA} state is 0, the @code{za} register and its pseudo registers
+will read as <unavailable>.
+
+If the streaming vector length changes, then the @code{svg} register will be
+updated, as well as the @code{za} register.
+
+The possible values for @code{svg} are 2, 4, 8, 16, 32. These numbers
+correspond to streaming vector length values of 16 bytes, 32 bytes, 64 bytes,
+128 bytes and 256 bytes.
+
+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.
+
+The @code{za} register can also be referenced using tiles and tile 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.
+
+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>.
+
@subsubsection AArch64 Pointer Authentication.
@cindex AArch64 Pointer Authentication.
@anchor{AArch64 PAC}
@@ -48030,6 +48085,19 @@ This restriction may be lifted in the future.
Extra registers are allowed in this feature, but they will not affect
@value{GDBN}.
+The @samp{org.gnu.gdb.aarch64.sme} feature is optional. If present,
+it should contain registers @samp{za}, @samp{svg} and @samp{svcr}.
+
+@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).
+
+The rest of the unused bits of @samp{svcr} are undefined and reserved. They
+should not be used and may be defined by future extensions of the architecture.
+
+Extra registers are allowed in this feature, but they will not affect
+@value{GDBN}.
+
@node ARC Features
@subsection ARC Features
@cindex target descriptions, ARC Features