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

[Luis Machado]

On 5/19/23 12:20, Eli Zaretskii wrote:
>> Date: Fri, 19 May 2023 11:25:08 +0100
>> From: Luis Machado via Gdb-patches <gdb-patches@sourceware.org>
>>
>> Updates since v2:
>>
>> - More adjustments based on reviews.
>> - Fixed incorrect number of tile pseudo-registers.
>> - Fixed naming of tile slice pseudo-registers.
>> - More detail about SME and how gdb implements it.
>> - Attempted to clarify the text a bit more.
>>
>> Updates since v1:
>>
>> - Made SME text more thorough.
>> - Adjusted text based on upstream reviews.
>> - Fixed documentation errors (missing itemization for SME registers).
>>
>> Provide documentation for the SME feature and other information that
>> should be useful for users that need to debug a SME-capable target.
> 
> Thanks.  This part of the patch has numerous inconsistencies in
> letter-case and markup of register names, see below.
> 

Thanks. I think I've addressed all of them now. I'll send a v3 of the series.

>> +The @code{za} register state can be either active or inactive, if it is not in
>> +use.
> 
> "@code{ZA}", upper-case.
> 
>> +@var{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 @var{svl} by @var{svl}.
> 
> Same here.
> 
>> +The @code{za} register is a 2-dimensional square @var{svl} by @var{svl}
> 
> And here.
> 
>> +If the user wants to index the @code{za} register as a matrix, it is possible
>> +to reference @code{za} as @code{za[@var{i}][@var{j}]}, where @var{i} is the
>> +row number and @var{j} is the column number.
> 
> And here.
> 
>> +The @var{svg} register always contains the streaming vector granule
>        ^^^^^^^^^
> "@code{SVG}"
> 
>> +(@var{svg}) for the current thread.  From @var{svg} we can easily derive
> 
> Same here.
> 
>> +The @code{svcr} pseudo-register (streaming vector control register) is a status
> 
> Same here: "@code{SVCR}"
> 
>> +If the @sc{za} bit is 1, it means the @code{za} register is being used and
>                                          ^^^^^^^^^
> "@code{ZA}", upper-case.
> 
>> +For convenience and simplicity, if the @sc{za} bit is 0, the @code{za}
>> +register and all of its pseudo-registers will read as zero.
> 
> Same here.
> 
>> +If @var{svl} changes during the execution of a program, then the @code{za}
>> +register size and the bits in the @code{svcr} pseudo-register will be updated
>> +to reflect it.
> 
> And here.
> 
>> +It is possible for users to change @var{svl} during the execution of a
>> +program by modifying the @var{svg} register value.
>                             ^^^^^^^^^
> "@code{SVG}"
> 
>> +Whenever the @var{svg} register is modified with a new value, the
> 
> Same here.
> 
>> +@item The @code{za} register will have a new size and its state will be
> 
> "@code{ZA}"
> 
>> +@sc{sm} bit was 0 prior to modifying the @var{svg} register, there will be no
>                                             ^^^^^^^^^
> "@code{SVG}"
> 
>> +The possible values for the @var{svg} register are 2, 4, 8, 16, 32.  These
> 
> Same here.
> 
>> +The minimum size of the @code{za} register is 16 x 16 (256) bytes, and the
> 
> "@code{ZA}"
> 
>> +maximum size is 256 x 256 (65536) bytes.  In streaming mode, with bit @sc{sm}
>> +set, the size of the @code{za} register is the size of all the SVE @code{z}
> 
> Same here, and also "@code{Z}", upper-case.
> 
>> +The @code{za} register can also be accessed using tiles and tile slices.
> 
> "@code{ZA}"
> 
>> +Tile pseudo-registers are square, 2-dimensional sub-arrays of elements within
>> +the @code{za} register.
> 
> Same here.
> 
>> +There is a total of 31 @code{za} tile pseudo-registers.  They are
>> +@code{za0b}, @code{za0h} through @code{za1h}, @code{zas0} through @code{zas3},
>> +@code{zad0} through @code{zad7} and @code{zaq0} through @code{zaq15}.
> 
> Same here: all the register names should be in upper-case.
> 
>> +Tile slice pseudo-registers are vectors of horizontally or vertically
>> +contiguous elements within the @code{za} register.
> 
> "@code{ZA}"
> 
>> +The tile slice pseudo-registers have the following naming pattern:
>> +@code{za<@var{tile number}><@var{direction}><@var{qualifier}>
>> +<@var{slice number}>}.
> 
> Same here.
> 
>> +When listing all the available registers, users will see the
>> +currently-available @code{za} pseudo-registers.  Pseudo-registers that don't
> 
> And here.
> 
>> +account the @code{svcr} pseudo-register bits nor the @code{za} register
> 
> And here.
> 
>> +contents. @xref{Calling}
>            ^^
> Two spaces there.
> 
>> +The @url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst#the-za-lazy-saving-scheme,
>> +lazy saving scheme} involving the @code{tpidr2} register is not yet supported
>> +by @value{GDBN}, though the @code{tpidr2} register is known and supported
>> +by @value{GDBN}.
> 
> Please up-case the names of the registers here.
> 
>> +@value{GDBN} showing incorrect values for the @code{za} register and
> 
> "@code{ZA}"
> 
>> +The @samp{org.gnu.gdb.aarch64.sme} feature is optional.  If present,
>> +it should contain registers @samp{za}, @samp{svg} and @samp{svcr}.
> 
> Since you use @code, not @samp, for register markup elsewhere, please
> use @code here as well.  Also, please up-case the names of the
> registers.
> 
>> +@samp{za} is a register represented by a vector of @var{svl}x@var{svl}
>    ^^^^^^^^^
> "@code{ZA}"
> 
>> +@samp{svg} is a 64-bit register containing the value of @var{svg}.  @xref{svg}.
>    ^^^^^^^^^^
> "@code{SVG}"
> 
>> +@samp{svcr} is a 64-bit status pseudo-register with two valid bits.  Bit 0
>    ^^^^^^^^^^^
> "@code{SVCR}"
> 
>> +Bit 1 (@sc{za}) shows whether the @code{za} register state is active (in use) or
>                                      ^^^^^^^^^
> "@code{ZA}"
> 
>> +The rest of the unused bits of the @samp{svcr} pseudo-register is undefined
>                                       ^^^^^^^^^^^
> "@code{SVCR}"
> 
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>