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

[Eli Zaretskii]

> Date: Thu, 22 Oct 2020 17:00:10 -0300
> From: Luis Machado via Gdb-patches <gdb-patches@sourceware.org>
> Cc: david.spickett@linaro.org
> 
> +Memory tagging is a memory protection technology that uses tags to validate
> +memory accesses through pointers.  The pointer tag must match the memory tag
> +for the memory access to be validated.
                         ^^^^^^^^^^^^^^^
I guess "to be valid" is more clear, as "validated" can be interpreted
as the process of validation, not its result.

> +There are two types of tags: logical and allocation.  A logical tag is
> +stored in the pointers themselves.  A allocation tag is the tag associated
                                       ^                   ^^^
"An" and "a"

Also, this text fails to explain that (AFAIU) these 2 types of tags
work together to allow the access validation.  IOW, both types need to
be present for the mechanism to work.  I originally interpreted the
text as meaning that tags come in 2 flavors, depending on how the
hardware implemented the facility.

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

> +@item mtag setatag @var{starting_address} @var{length} @var{tag_bytes}
> +Set the allocation tag(s) for memory range @r{[}@var{starting_address},
> +@var{starting_address} + @var{length}@r{)} to @var{tag_bytes}.

This is what I'd expect from setltag to do.

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

Thanks.