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

Eli Zaretskii via Gdb-patches
2020-10-23T14:33:47Z

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

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

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