[19/23] Documentation for the new mtag commands

Message ID 20200715194513.16641-20-luis.machado@linaro.org
State New
Headers show
Series
  • Memory Tagging Support + AArch64 Linux implementation
Related show

Commit Message

Eli Zaretskii via Gdb-patches July 15, 2020, 7:45 p.m.
Document the new "mtag" command prefix and all of its subcommands.

gdb/doc/ChangeLog:

YYYY-MM-DD  Luis Machado  <luis.machado@linaro.org>

	* gdb.textinfo (Memory Tagging): New subsection.
	(AArch64 Memory Tagging Extension): New subsection.
---
 gdb/doc/gdb.texinfo | 60 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

-- 
2.17.1

Comments

Eli Zaretskii July 17, 2020, 6:11 a.m. | #1
> 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.
Eli Zaretskii via Gdb-patches July 17, 2020, 2:20 p.m. | #2
On 7/17/20 3:11 AM, Eli Zaretskii wrote:
>> 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.

> 


Fixed now.

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

> 


That sounds better. Thanks.

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

> 


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?

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

> 


Fixed both.

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

> 


Compared really. I've changed it.

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

>                                                             ^^^^^^^^^^^^

> "like AArch64 does"

> 


How about "... like AArch64 MTE or SPARC ADI..."?

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

> 


I agree. I wanted to convey the idea that the result value is treated as 
a pointer, but it may not be worth it.

I went with your suggestion.

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

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

> 


Right. So this is how it reads now...

"Show the allocation tag associated with the memory address given by
@var{address_expression}."

It has a subtle difference to make it clear that the allocation tag is 
not related to the pointer, but with the memory address.

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

> 


A little, and this is something we need to address during reviews.

The reason behind this inconsistency is that we can't always modify the 
user-passed argument to contain the specified logical tag, but we can 
always print that information. Whichever is most useful is debatable.

The user can always use the "set" command to modify values, and can use 
"setltag" to see what the tagged pointer would look like before 
modifying a particular value.

For allocation tags, on the other hand, we can always modify them. Those 
tags are set in memory and are not part of pointers.

Does that make things slightly more clear?

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

> 


The logical tag from the address/pointer given by 
@var{address_expression} is compared to the allocation tag for the same 
address.

How about the following?

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


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

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

> 


Done now. I've added a couple small examples.

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

> 

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

> 

> Thanks.

> 


It is a new register set the kernel exposes to GDB when MTE is 
available. It is also a pseudo register that mimics a prctl setting. So 
it doesn't map 1:1 to a real register.

I agree it is a special register, and it is more meaningful than "new". 
In a few years, it won't be new anymore.
Eli Zaretskii July 17, 2020, 2:29 p.m. | #3
> 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.
Eli Zaretskii via Gdb-patches July 17, 2020, 3:08 p.m. | #4
On 7/17/20 11:29 AM, Eli Zaretskii wrote:
>> 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 ;-)

> 


Fair enough. That does read better. Thanks.

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

>>>                                                              ^^^^^^^^^^^^

>>> "like AArch64 does"

>>>

>>

>> How about "... like AArch64 MTE or SPARC ADI..."?

> 

> Fine with me.

> 


I realized I missed the point of the comment. I've made it...

"... like AArch64 MTE or SPARC ADI do ..."

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

> 


Right. I'll hold until we have some more consensus about that particular 
command. Then I'll update the documentation accordingly.

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

> 


Ah! I've never used that. That's good to know. I've added those 
cross-references locally now. They'll be in v2.

Thanks!

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index bc610e44cd..4156d1d70a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -10806,6 +10806,49 @@  target supports computing the CRC checksum of a block of memory
 (@pxref{qCRC packet}).
 @end table
 
+@subsection Memory Tagging
+
+Memory tagging is a memory protection technology that validates accesses
+through pointers via a tag.  Both the pointer tag and the memory tag in the
+physical address space must match for the memory access to be validated.
+
+There are two types of tags: logical and allocation.  The logical tag is
+stored in the pointers themselves.  The allocation tag is the tag associated
+with the physical address space, against which the logical tags from pointers
+are validated.
+
+If the underlying architecture supports memory tagging, like AArch64,
+@value{GDBN} can make use of it to validate addresses and pointers against
+memory allocation tags.
+
+A command prefix of @code{mtag} gives access to the various memory tagging
+commands.
+
+The @code{mtag} commands are the following:
+
+@table @code
+@kindex mtag showltag
+@item mtag showltag @var{address_expression}
+Show the logical tag contained in the pointer resulting from evaluating the
+argument expression.
+@kindex mtag setltag
+@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}.
+@kindex mtag showatag
+@item mtag showatag @var{address_expression}
+Show the allocation tag from the memory address pointed to by the evaluation
+of the argument expression.
+@kindex mtag setatag
+@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}.
+@kindex mtag check
+@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.
+@end table
+
 @node Auto Display
 @section Automatic Display
 @cindex automatic display
@@ -24846,6 +24889,23 @@  When GDB prints a backtrace, any addresses that required unmasking will be
 postfixed with the marker [PAC].  When using the MI, this is printed as part
 of the @code{addr_flags} field.
 
+@subsubsection AArch64 Memory Tagging Extension.
+@cindex AArch64 Memory Tagging Extension.
+
+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.
+
+To aid debugging, @value{GDBN} will output additional information when SIGSEGV
+signals are generated as a result of memory tag failures.
+
+A new register, @code{tag_ctl}, is made available through the
+@code{org.gnu.gdb.aarch64.mte} feature.  This register exposes some
+options that can be controlled at runtime and emulates the @code{prctl}
+option @code{PR_SET_TAGGED_ADDR_CTRL}.  For further information, see the
+documentation in the Linux kernel.
+
 @node i386
 @subsection x86 Architecture-specific Issues