[PATCH v2 07/24] Documentation for memory tagging remote packets

[Luis Machado]

On 10/23/20 11:33 AM, Eli Zaretskii wrote:
>> Cc: gdb-patches@sourceware.org, david.spickett@linaro.org
>> From: Luis Machado <luis.machado@linaro.org>
>> Date: Fri, 23 Oct 2020 11:07:48 -0300
>>
>>>> +@var{type} is the type of tag, a signed integer, the request wants to fetch.
>>>
>>> This is ambiguous: does "the request wants to fetch" refer to the tag
>>> or to the "signed integer" part?  Suggest to move the "a signed
>>> integer" part to the end of the sentence.
>>
>> Yeah. It reads a bit funny. How about the following?
>>
>> @var{type} is the type of tag the request wants to fetch.  The type is a
>> signed integer.
> 
> Fine, thanks.
> 
>>>> +If the number of memory tags, @var{nt}, is greater than or equal to the
>>>> +number of memory tag granules, @var{ng}, only @var{ng} tags will be
>>>> +stored.
>>>
>>> It is not clear here how NT and NG are related to the parameters of
>>> the packet.  Can you add something that explains the relation?
>>>
>>
>> How about the following?
>>
>> NT is the number of memory tags contained in @var{tag bytes}.  Only
>> target-specific code can determine this value.  For example, AArch64's
>> tags are stored 1 per byte.
>>
>> NG is the number of memory tag granules in the memory range
>> @w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}.
>> Only target-specific can determine this value.  For example, AArch64 has
>> a tag granule size of 16 bytes.  That is, it has one memory for every 16
>> bytes of memory.
> 
> This is okay, but I think you in fact had already explained that, in
> this text:
> 

Indeed.

>> +The interpretation of how many tags should be written to how many memory tag
>> +granules is also architecture-specific.  The behavior is
>> +implementation-specific, but the following is suggested. >
> So I think the only change you need to do is to mention @var{nt} and
> @var{ng} in that text:
> 
>    The interpretation of how many tags (@var{nt}) should be written to
>    how many memory tag granules (@var{ng}) is also
>    architecture-specific.  The behavior is implementation-specific, but
>    the following is suggested.
> 
> WDYT?
> 

That works fine for me. Thanks!

>> I did...
>>
>> "The remote stub supports and implements the required memory tagging
>> functionality and understands the @samp{qMemTags} (@pxref{qMemTags}) and
>> @samp{QMemTags} (@pxref{QMemTags}) packets."
>>
>> And I've added a couple anchors to the packets.
>>
>> Is that what you had in mind?
> 
> Yes, thanks.
> 

Great. I'll include the changes in v3.