[07/23] Documentation for memory tagging remote packets

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

Commit Message

Hannes Domani via Gdb-patches July 15, 2020, 7:44 p.m.
Document the remote packet changes to support memory tagging.

gdb/doc/ChangeLog:

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

	* gdb.texinfo (General Query Packets): Document qMemTags and
	QMemTags.
	Document the "memory-tagging" feature.
---
 gdb/doc/gdb.texinfo | 84 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

-- 
2.17.1

Comments

Eli Zaretskii July 17, 2020, 5:54 a.m. | #1
> Date: Wed, 15 Jul 2020 16:44:57 -0300

> From: Luis Machado via Gdb-patches <gdb-patches@sourceware.org>

> Cc: catalin.marinas@arm.com, david.spickett@linaro.org

> 

> +If the number of memory tags, @var{N}, is greater than or equal to the number

> +of memory tag granules, @var{G}, only @var{G} tags will be stored.

> +

> +If @var{N} is less than @var{G}, the behavior is that of a fill operation,

> +and the tag bytes will be used as a pattern that will get repeated until

> +@var{G} tags are stored.


The symbols inside @var should be lower-case, per our conventions.
They look better in the printed manual that way.

> +For AArch64 GNU/Linux systems, this feature also requires access to the smaps

> +file in the proc filesystem so memory mapping page flags can be inspected.


"proc" should have the @file markup (and should probably be "/proc"?).

The patch is OK with those nits fixed.

Thanks.
Hannes Domani via Gdb-patches July 17, 2020, 2:20 p.m. | #2
Thanks for reviewing this Eli.

On 7/17/20 2:54 AM, Eli Zaretskii wrote:
>> Date: Wed, 15 Jul 2020 16:44:57 -0300

>> From: Luis Machado via Gdb-patches <gdb-patches@sourceware.org>

>> Cc: catalin.marinas@arm.com, david.spickett@linaro.org

>>

>> +If the number of memory tags, @var{N}, is greater than or equal to the number

>> +of memory tag granules, @var{G}, only @var{G} tags will be stored.

>> +

>> +If @var{N} is less than @var{G}, the behavior is that of a fill operation,

>> +and the tag bytes will be used as a pattern that will get repeated until

>> +@var{G} tags are stored.

> 

> The symbols inside @var should be lower-case, per our conventions.

> They look better in the printed manual that way.


I've made them lower case and updated their names to nt and ng. I also 
updated another offender in the packet description (@var{mXX}).

> 

>> +For AArch64 GNU/Linux systems, this feature also requires access to the smaps

>> +file in the proc filesystem so memory mapping page flags can be inspected.

> 

> "proc" should have the @file markup (and should probably be "/proc"?).

> 

> The patch is OK with those nits fixed.

> 

> Thanks.

> 


I rephrased it to read "...access to the @file{/proc/@var{pid}/smaps} 
file...".

Thanks!

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a002084d5b..bc610e44cd 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -40654,6 +40654,77 @@  is a sequence of thread IDs, @var{threadid} (eight hex
 digits), from the target.  See @code{remote.c:parse_threadlist_response()}.
 @end table
 
+@item qMemTags:@var{start address}:@var{length}
+@cindex fetch memory tags
+@cindex @samp{qMemTags} packet
+Fetch memory tags in the address range @r{[}@var{start address},
+@var{start address} + @var{length}@r{)}.  The target is responsible for
+calculating how many tags will be returned, as this is architecture-specific.
+
+@var{start address} is the starting address of the memory range.
+
+@var{length} is the length, in bytes, of the memory range.
+
+Reply:
+@table @samp
+@item @var{mXX}@dots{}
+Hex encoded sequence of uninterpreted bytes representing the tags found in
+the request memory range.
+
+@item E @var{nn}
+An error occured.  This means that fetching of memory tags failed for some
+reason.
+
+@item @w{}
+An empty reply indicates that @samp{qMemTags} is not supported by the stub,
+although this should not happen given @value{GDBN} will only send this packet
+if the stub has advertised support for memory tagging via @samp{qSupported}.
+@end table
+
+@item QMemTags:@var{start address}:@var{length}:@var{tag bytes}
+@cindex store memory tags
+@cindex @samp{QMemTags} packet
+Store memory tags to the address range @r{[}@var{start address},
+@var{start address} + @var{length}@r{)}.  The target is responsible for
+interpreting the tag bytes and modifying the memory tag granules
+accordingly, given this is architecture-specific.
+
+The interpretation of how many tags should be written to how many memory tag
+granules is also architecture-specific.  The behavior is
+implementation-specific, but the following is suggested.
+
+If the number of memory tags, @var{N}, is greater than or equal to the number
+of memory tag granules, @var{G}, only @var{G} tags will be stored.
+
+If @var{N} is less than @var{G}, the behavior is that of a fill operation,
+and the tag bytes will be used as a pattern that will get repeated until
+@var{G} tags are stored.
+
+@var{start address} is the starting address of the memory range.  The address
+does not have any restriction on alignment or size.
+
+@var{length} is the length, in bytes, of the memory range.
+
+@var{tag bytes} is a sequence of hex encoded uninterpreted bytes which will be
+interpreted by the target.  Each pair of hex digits is interpreted as a
+single byte.
+
+Reply:
+@table @samp
+@item OK
+The request was successful and the memory tag granules were modified
+accordingly.
+
+@item E @var{nn}
+An error occured.  This means that modifying the memory tag granules failed
+for some reason.
+
+@item @w{}
+An empty reply indicates that @samp{QMemTags} is not supported by the stub,
+although this should not happen given @value{GDBN} will only send this packet
+if the stub has advertised support for memory tagging via @samp{qSupported}.
+@end table
+
 @item qOffsets
 @cindex section offsets, remote request
 @cindex @samp{qOffsets} packet
@@ -41321,6 +41392,11 @@  These are the currently defined stub features and their properties:
 @tab @samp{-}
 @tab No
 
+@item @samp{memory-tagging}
+@tab No
+@tab @samp{-}
+@tab No
+
 @end multitable
 
 These are the currently defined stub features, in more detail:
@@ -41535,6 +41611,14 @@  The remote stub understands the @samp{QThreadEvents} packet.
 @item no-resumed
 The remote stub reports the @samp{N} stop reply.
 
+@item memory-tagging
+The remote stub supports and implements the required memory tagging
+functionality and understands the @samp{qMemTags} and @samp{QMemTags} packets.
+
+For AArch64 GNU/Linux systems, this feature also requires access to the smaps
+file in the proc filesystem so memory mapping page flags can be inspected.  This
+is done via the @samp{vFile} requests.
+
 @end table
 
 @item qSymbol::