[PATCH v2 20/24] Documentation for the new mtag commands

[Eli Zaretskii]

> Cc: gdb-patches@sourceware.org, david.spickett@linaro.org
> From: Luis Machado <luis.machado@linaro.org>
> Date: Fri, 23 Oct 2020 11:33:36 -0300
> 
> But, in general, there will always be a memory-side tag against which a 
> logical tag (contained in a pointer, for example) will be matched against.

This is the crucial aspect that should be stated, IMO.

> >> +@kindex mtag setltag
> >> +@item mtag setltag @var{address_expression} @var{tag_bytes}
> >> +Print the address given by @var{address_expression}, augmented with a logical
> > 
> > It is strange for a command whose name is "set..." to print
> > something.  I'd expect it to set something instead.  is the above
> > description correct?
> > 
> 
> Yes. This is one area that I'd welcome some discussion/feedback.
> 
> We don't always have a modifiable value as an argument to the "mtag 
> setltag" command. We could have a constant value, a read-only value, 
> some reference or some expression containing multiple pointers.
> 
> Plus, the most natural way to modify a value in GDB is through the 
> existing "set variable" command.
> 
> The main goal is to be able to augment a particular address with a given 
> logical tag. That augmented value can then be used to set a particular 
> pointer or value. It will be stored in the history anyway, so that's 
> already a value that you can use.
> 
> There won't be much reason to set logical tags other than if you're 
> chasing bugs and trying to cause one. It is one additional knob so that 
> you won't need to craft the tagged pointer by hand.

Maybe the command should be called something other than "set...",
then?

> >> +@kindex mtag check
> >> +@item mtag check @var{address_expression}
> >> +Check that the logical tag stored at the address given by
> >> +@var{address_expression} matches the allocation tag for the same address.
> > 
> > This test should say that this check performs the same validation as
> > is done in hardware when memory is accessed through a pointer.  Saying
> > that (assuming I understood correctly) will go a long way towards
> > causing this facility to make much more sense to the reader.
> 
> Does it make it more clear if I add the following:
> 
> "This essentially emulates the hardware validation that is done when 
> tagged memory is accessed through a pointer, but does not cause a memory 
> fault as it would during hardware validation.
> 
> It can be used to inspect potential memory tagging violations in the 
> running process, before any faults get triggered."

Yes, this is a good addition, thanks.