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

[Eli Zaretskii]

> Date: Wed, 15 Jul 2020 16:45:09 -0300
> From: Luis Machado via Gdb-patches <gdb-patches@sourceware.org>
> Cc: catalin.marinas@arm.com, david.spickett@linaro.org
> 
> 	* gdb.textinfo (Memory Tagging): New subsection.
> 	(AArch64 Memory Tagging Extension): New subsection.

gdb.texinfo (without the "t").  Also, we usually combine functions and
sections that have the same change description, as in

	* gdb.texinfo (Memory Tagging, AArch64 Memory Tagging Extension):
	 New subsections.

> +Memory tagging is a memory protection technology that validates accesses
> +through pointers via a tag.

The "via a tag" part is ambiguous: it is not clear whether it refers
to the access or to the protection.  Suggest a slight rewording:

  Memory tagging is a memory protection technology that uses tags to
  validate memory accesses through pointers.

>                           Both the pointer tag and the memory tag in the
> +physical address space must match for the memory access to be validated.

Here, it is unclear what should match what.  Do you mean that the
pointer tag must match the memory tag? or do you mean something else?
If the former, then where does the "physical address space" part come
into the picture?

> +There are two types of tags: logical and allocation.  The logical tag is
                                                         ^^^^^^^^^^^^^^^
"A logical tag"

> +stored in the pointers themselves.  The allocation tag is the tag associated
                                       ^^^^^^^^^^^^^^^^^^
Ditto.

> +with the physical address space, against which the logical tags from pointers
> +are validated.

"Validated" or "compared"?  The latter is much less vague, so if it's
accurate, I think we should prefer it.

> +If the underlying architecture supports memory tagging, like AArch64,
                                                           ^^^^^^^^^^^^
"like AArch64 does"

> +@item mtag showltag @var{address_expression}
> +Show the logical tag contained in the pointer resulting from evaluating the
> +argument expression.

This is slightly better, IMO:

  Show the logical tag stored at the address given by
  @var{address_expression}.

It avoids two words in a row that end in "ing", which makes it a
mouthful.

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

> +@item mtag showatag @var{address_expression}
> +Show the allocation tag from the memory address pointed to by the evaluation
> +of the argument expression.

See above: I'd rephrase this similarly to showltag.

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

So setatag _sets_ a tag, but setltag _prints_ something?  Isn't that
inconsistent?

> +@item mtag check @var{address_expression}
> +Given the pointer resulting from evaluating the argument expression,  check that
> +the logical tag and the allocation tags match.

Which logical tag and which allocation tag are being tested for a
match here?

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

> +To aid debugging, @value{GDBN} will output additional information when SIGSEGV
> +signals are generated as a result of memory tag failures.

Can you add some minimal description of the additional information?

> +A new register, @code{tag_ctl}, is made available through the

In what sense is this register "new"?  Perhaps you mean "special"?

Thanks.