[binutils-gdb] gdb: Document qIsAddressTagged packet

[binutils-gdb] gdb: Document qIsAddressTagged packet

[Luis Machado]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=0e6747d2a638693ad2f20e7929c8364913c87279

commit 0e6747d2a638693ad2f20e7929c8364913c87279
Author: Gustavo Romero <gustavo.romero@linaro.org>
Date:   Thu Apr 18 20:10:39 2024 +0000

    gdb: Document qIsAddressTagged packet
    
    This commit documents the qIsAddressTagged packet.
    
    Signed-off-by: Gustavo Romero <gustavo.romero@linaro.org>
    Reviewed-by: Eli Zaretskii <eliz@gnu.org>
    Approved-By: Eli Zaretskii <eliz@gnu.org>

Diff:
---
 gdb/NEWS            | 10 ++++++++++
 gdb/doc/gdb.texinfo | 37 ++++++++++++++++++++++++++++++++++---
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 942453c7064..050f6f96e62 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -196,6 +196,16 @@ QThreadOptions in qSupported
   QThreadOptions packet, and the qSupported response can contain the
   set of thread options the remote stub supports.
 
+qIsAddressTagged
+  This new packet allows GDB to query the stub about a given address to check
+  if it is tagged or not.  Many memory tagging-related GDB commands need to
+  perform this check before they read/write the allocation tag related to an
+  address.  Currently, however, this is done through a 'vFile' request to read
+  the file /proc/<PID>/smaps and check if the address is in a region reported
+  as memory tagged.  Since not all targets have a notion of what the smaps
+  file is about, this new packet provides a more generic way to perform such
+  a check.
+
 *** Changes in GDB 14
 
 * GDB now supports the AArch64 Scalable Matrix Extension 2 (SME2), which
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 82a617e9ad3..31a531ee992 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -44093,6 +44093,35 @@ 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
 
+@cindex check if a given address is in a memory tagged region
+@cindex @samp{qIsAddressTagged} packet
+@item qIsAddressTagged:@var{address}
+@anchor {qIsAddressTagged}
+Check if address @var{address} is in a memory tagged region; if it is, it's
+said to be @dfn{tagged}.  The target is responsible for checking it, as this
+is architecture-specific.
+
+@var{address} is the address to be checked.
+
+Reply:
+@table @samp
+Replies to this packet should all be in two hex digit format, as follows:
+
+@item @samp{01}
+Address @var{address} is tagged.
+
+@item @samp{00}
+Address @var{address} is not tagged.
+
+@item E @var{nn}
+An error occurred whose code is @var{nn}.  This means that address could not
+be checked for some reason.
+
+@item @w{}
+An empty reply indicates that @samp{qIsAddressTagged} is not supported by the
+stub.
+@end table
+
 @item QMemTags:@var{start address},@var{length}:@var{type}:@var{tag bytes}
 @anchor{QMemTags}
 @cindex store memory tags
@@ -45141,9 +45170,11 @@ The remote stub supports and implements the required memory tagging
 functionality and understands the @samp{qMemTags} (@pxref{qMemTags}) and
 @samp{QMemTags} (@pxref{QMemTags}) packets.
 
-For AArch64 GNU/Linux systems, this feature also requires access to the
-@file{/proc/@var{pid}/smaps} file so memory mapping page flags can be inspected.
-This is done via the @samp{vFile} requests.
+For AArch64 GNU/Linux systems, this feature can require access to the
+@file{/proc/@var{pid}/smaps} file so memory mapping page flags can be
+inspected, if @samp{qIsAddressTagged} (@pxref{qIsAddressTagged}) packet
+is not supported by the stub.  Access to the @file{/proc/@var{pid}/smaps}
+file is done via @samp{vFile} requests.
 
 @end table