[PATCH v6 23/25] Document new "x" and "print" memory tagging extensions

[Luis Machado <luis.machado@linaro.org>]

Updates on v6

- Document the new memory-tag-violation print option.

--

Document the changes to the "print" and "x" commands to support memory
tagging.

gdb/doc/ChangeLog:

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

	* gdb.texinfo (Data): Document memory tagging changes to the "print"
	command.
	(Examining Memory): Document memory tagging changes to the "x"
	command.
	(Memory Tagging): Update with more information on changes to the "x"
	and "print" commands.
---
 gdb/doc/gdb.texinfo | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d976325e695..dbf878cdbc3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9951,6 +9951,10 @@ If you omit @var{expr}, @value{GDBN} displays the last value again (from the
 conveniently inspect the same value in an alternative format.
 @end table
 
+If the architecture supports memory tagging, the @code{print} command will
+display pointer/memory tag mismatches if what is being printed is a pointer
+or reference type. @xref{Memory Tagging}.
+
 A more low-level way of examining data is with the @code{x} command.
 It examines data in memory at a specified address and prints it in a
 specified format.  @xref{Memory, ,Examining Memory}.
@@ -10718,7 +10722,8 @@ number is specified, memory is examined backward from @var{addr}.
 @item @var{f}, the display format
 The display format is one of the formats used by @code{print}
 (@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
-@samp{f}, @samp{s}), and in addition @samp{i} (for machine instructions).
+@samp{f}, @samp{s}), @samp{i} (for machine instructions) and
+@samp{m} (for displaying memory tags).
 The default is @samp{x} (hexadecimal) initially.  The default changes
 each time you use either @code{x} or @code{print}.
 
@@ -10813,6 +10818,22 @@ counter is shown with a @code{=>} marker. For example:
    0x804838c <main+24>: call   0x80482d4 <puts@@plt>
 @end smallexample
 
+If the architecture supports memory tagging, the tags can be displayed by
+using @samp{m}.  @xref{Memory Tagging}.
+
+The information will be displayed once per granule size
+(the amount of bytes a particular memory tag covers).  For example, AArch64
+has a granule size of 16 bytes, so it will display a tag every 16 bytes.
+
+Due to the way @value{GDBN} prints information with the @code{x} command (not
+aligned to a particular boundary), the tag information will refer to the
+initial address displayed on a particular line.  If a memory tag boundary
+is crossed in the middle of a line displayed by the @code{x} command, it
+will be displayed on the next line.
+
+The @samp{m} format doesn't affect any other specified formats that were
+passed to the @code{x} command.
+
 @cindex @code{$_}, @code{$__}, and value history
 The addresses and contents printed by the @code{x} command are not saved
 in the value history because there is often too much of them and they
@@ -10890,8 +10911,9 @@ If the underlying architecture supports memory tagging, like AArch64 MTE
 or SPARC ADI do,  @value{GDBN} can make use of it to validate pointers
 against memory allocation tags.
 
-A command prefix of @code{memory-tag} gives access to the various memory tagging
-commands.
+The @code{print} (@pxref{Data}) and @code{x} (@pxref{Memory}) commands will
+display tag information when appropriate, and a command prefix of
+@code{memory-tag} gives access to the various memory tagging commands.
 
 The @code{memory-tag} commands are the following:
 
@@ -11527,6 +11549,20 @@ language, for most languages @code{@{...@}} is used, but Fortran uses
 Display the current threshold after which nested structures are
 replaces with ellipsis.
 
+@anchor{set print memory-tag-violations}
+@cindex printing memory tag violation information
+@item set print memory-tag-violations
+@itemx set print memory-tag-violations on
+Cause @value{GDBN} to display additional information about memory tag violations
+when printing pointers and addresses.
+
+@item set print memory-tag-violations off
+Stop printing memory tag violation information.
+
+@item show print memory-tag-violations
+Show whether memory tag violation information is displayed when printing
+pointers and addresses.
+
 @anchor{set print null-stop}
 @item set print null-stop
 @cindex @sc{null} elements in arrays
-- 
2.25.1