[PATCH] doc of pre-defined or builtin trace state variables

[PATCH] doc of pre-defined or builtin trace state variables

[David Taylor]

Our tracepoint users want certain capabilities for which 'pre-defined' or
'builtin' trace state variables seem like they would be a good fit.  So,
I started looking into what it would take to modify both GDB and our GDB
stub to support them.

Imagine my surprise to discover that GDB already supports them, but it
is not documented!

Here's a patch.  The pdf, html, and info targets build without
complaint.  The modified paragraph in the pdf file looks okay.

gdb/doc/ChangeLog:

2015-02-12  David Taylor  <dtaylor@emc.com>

	* gdb.texinfo (Tracepoint Packets): Document the builtin and name
	fields of the QTDV packet.

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index b8e1f7f..62726ff 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2015-02-12  David Taylor  <dtaylor@emc.com>
+
+	* gdb.texinfo (Tracepoint Packets): Document the builtin and name
+	fields of the QTDV packet.
+
 2015-02-09  Markus Metzger  <markus.t.metzger@intel.com>
 
 	* gdb.texinfo (Branch Trace Configuration Format): Add size.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d1f22de..c4f03b2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -36812,7 +36812,7 @@ the ones in effect during the trace run; even a small discrepancy
 could cause @samp{tdump} not to work, or a particular trace frame not
 be found.
 
-@item QTDV:@var{n}:@var{value}
+@item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name}
 @cindex define trace state variable, remote request
 @cindex @samp{QTDV} packet
 Create a new trace state variable, number @var{n}, with an initial
@@ -36820,7 +36820,12 @@ value of @var{value}, which is a 64-bit signed integer.  Both @var{n}
 and @var{value} are encoded as hexadecimal values. @value{GDBN} has
 the option of not using this packet for initial values of zero; the
 target should simply create the trace state variables as they are
-mentioned in expressions.
+mentioned in expressions.  The value @var{builtin} should be 1 (one)
+if the trace state variable is builtin and 0 (zero) if it is not builtin.
+@value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or
+@samp{qTsV} packet had it set.  The contents of @var{name} is the
+hex-encoded name (without the leading @samp{$}) of the trace state
+variable.
 
 @item QTFrame:@var{n}
 @cindex @samp{QTFrame} packet

Re: [PATCH] doc of pre-defined or builtin trace state variables

[Eli Zaretskii]

> From: David Taylor <dtaylor@emc.com>
> Date: Thu, 12 Feb 2015 10:49:05 -0500
> 
> Our tracepoint users want certain capabilities for which 'pre-defined' or
> 'builtin' trace state variables seem like they would be a good fit.  So,
> I started looking into what it would take to modify both GDB and our GDB
> stub to support them.
> 
> Imagine my surprise to discover that GDB already supports them, but it
> is not documented!
> 
> Here's a patch.  The pdf, html, and info targets build without
> complaint.  The modified paragraph in the pdf file looks okay.
> 
> gdb/doc/ChangeLog:
> 
> 2015-02-12  David Taylor  <dtaylor@emc.com>
> 
> 	* gdb.texinfo (Tracepoint Packets): Document the builtin and name
> 	fields of the QTDV packet.

Thanks, this is OK.

Re: [PATCH] doc of pre-defined or builtin trace state variables

[David Taylor]

Eli Zaretskii <eliz@gnu.org> wrote:

> > From: David Taylor <dtaylor@emc.com>
> > Date: Thu, 12 Feb 2015 10:49:05 -0500
> > 
> > Our tracepoint users want certain capabilities for which 'pre-defined' or
> > 'builtin' trace state variables seem like they would be a good fit.  So,
> > I started looking into what it would take to modify both GDB and our GDB
> > stub to support them.
> > 
> > Imagine my surprise to discover that GDB already supports them, but it
> > is not documented!
> > 
> > Here's a patch.  The pdf, html, and info targets build without
> > complaint.  The modified paragraph in the pdf file looks okay.
> > 
> > gdb/doc/ChangeLog:
> > 
> > 2015-02-12  David Taylor  <dtaylor@emc.com>
> > 
> > 	* gdb.texinfo (Tracepoint Packets): Document the builtin and name
> > 	fields of the QTDV packet.
> 
> Thanks, this is OK.

Thanks.  Will someone commit it for me?  (I don't have commit privs.)

Re: [PATCH] doc of pre-defined or builtin trace state variables

[Eli Zaretskii]

> cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> Date: Thu, 12 Feb 2015 12:15:26 -0500
> From: David Taylor <dtaylor@usendtaylorx2l.lss.emc.com>
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > > From: David Taylor <dtaylor@emc.com>
> > > Date: Thu, 12 Feb 2015 10:49:05 -0500
> > > 
> > > Our tracepoint users want certain capabilities for which 'pre-defined' or
> > > 'builtin' trace state variables seem like they would be a good fit.  So,
> > > I started looking into what it would take to modify both GDB and our GDB
> > > stub to support them.
> > > 
> > > Imagine my surprise to discover that GDB already supports them, but it
> > > is not documented!
> > > 
> > > Here's a patch.  The pdf, html, and info targets build without
> > > complaint.  The modified paragraph in the pdf file looks okay.
> > > 
> > > gdb/doc/ChangeLog:
> > > 
> > > 2015-02-12  David Taylor  <dtaylor@emc.com>
> > > 
> > > 	* gdb.texinfo (Tracepoint Packets): Document the builtin and name
> > > 	fields of the QTDV packet.
> > 
> > Thanks, this is OK.
> 
> Thanks.  Will someone commit it for me?  (I don't have commit privs.)

Done.

Should this be cherry-picked to the 7.9 branch?