[PATCH 19/23] Documentation for the new mtag commands

[Eli Zaretskii]

> From: Luis Machado <luis.machado@linaro.org>
> Cc: gdb-patches@sourceware.org, Alan.Hayward@arm.com,
>  catalin.marinas@arm.com, david.spickett@linaro.org
> Date: Fri, 17 Jul 2020 11:20:17 -0300
> 
> The pointer tag must match the memory tag. The physical address space 
> reference was to make it clear that the allocation tag was associated 
> with the memory itself.
> 
> I've rephrased this as the following now...
> 
> "The pointer tag and the memory tag must match for the memory access to 
> be validated."
> 
> How does it look?

It's okay, but I like this even better:

  The pointer tag must match the memory tag for the memory access to 
  be validated.

(I stole the beginning from your explanation above ;-)

> >> +If the underlying architecture supports memory tagging, like AArch64,
> >                                                             ^^^^^^^^^^^^
> > "like AArch64 does"
> > 
> 
> How about "... like AArch64 MTE or SPARC ADI..."?

Fine with me.

> >> +@item mtag setltag @var{address_expression} @var{tag_bytes}
> >> +Print the resulting pointer from evaluating the argument expression with a
> >> +logical tag of @var{tag_bytes}.
> > 
> > I don't understand what "print the resulting point" means in this
> > context, and the sentence confused me, perhaps for this very reason.
> > can you elaborate what this means?
> > 
> 
> The goal of the command is to modify a particular address/pointer to 
> include the specified logical tag.
> 
> It will, therefore, print a modified version of the address given by 
> @var{address_expression}, but containing the specified tag.
> 
> So it doesn't "set" anything at the moment, it just prints what the 
> pointer would look like with the user-passed tag. This may change based 
> on reviews.
> 
> How about the following?
> 
> "Print the address given by @var{address_expression}, augmented with a 
> logical tag of @var{tag_bytes}."

That's okay, but since it is unusual for a "set" command to not set
anything, I think we should add to the manual some of the explanations
you gave above.

> "Check that the logical tag stored at the address given by
> @var{address_expression} matches the allocation tag for the same address."

SGTM, thanks.

> >> +When @value{GDBN} is debugging the AArch64 architecture, the program is
> >> +using the v8.5-A feature Memory Tagging Extension (MTE) and there is support
> >> +in the kernel for MTE, @value{GDBN} will make memory tagging functionality
> >> +available for inspection and editing of logical and allocation tags.
> > 
> > Please add here a cross-reference to "Memory Tagging" subsection.
> > 
> 
> Like this?
> 
> @cindex Memory Tagging

No, @cindex produces an index entry.  I meant @xref or @pxref.

Thanks.