RFA: GDB manual: document tracepoint packets

RFA: GDB manual: document tracepoint packets

[Jim Blandy]

[-- Attachment #1: Type: text/plain, Size: 206 bytes --]

2005-11-19  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (Tracepoint Packets): New node.
	(General Query Packets): Add entries for the tracepoint packets,
	referring to the "Tracepoint Packets" node.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: jimb.gdb-doc-remote-protocol-tracepoints.patch --]
[-- Type: text/x-patch; name="jimb.gdb-doc-remote-protocol-tracepoints.patch", Size: 8277 bytes --]

Index: gdb/doc/ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/doc/ChangeLog,v
retrieving revision 1.536
diff -c -p -r1.536 ChangeLog
*** gdb/doc/ChangeLog	18 Nov 2005 22:17:09 -0000	1.536
--- gdb/doc/ChangeLog	19 Nov 2005 20:30:28 -0000
***************
*** 1,3 ****
--- 1,9 ----
+ 2005-11-19  Jim Blandy  <jimb@redhat.com>
+ 
+ 	* gdb.texinfo (Tracepoint Packets): New node.
+ 	(General Query Packets): Add entries for the tracepoint packets,
+ 	referring to the "Tracepoint Packets" node.
+ 
  2005-11-18  Kevin Buettner  <kevinb@redhat.com>
  
  	* gdb.texinfo (set remotebreak): Add anchor.
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.295
diff -c -p -r1.295 gdb.texinfo
*** gdb/doc/gdb.texinfo	18 Nov 2005 22:17:09 -0000	1.295
--- gdb/doc/gdb.texinfo	19 Nov 2005 20:30:33 -0000
*************** Show the current setting of the target w
*** 22017,22022 ****
--- 22017,22023 ----
  * Stop Reply Packets::
  * General Query Packets::
  * Register Packet Format::
+ * Tracepoint Packets::
  * Interrupts::
  * Examples::
  * File-I/O remote protocol extension::
*************** encoded).  @value{GDBN} will continue to
*** 23029,23034 ****
--- 23030,23039 ----
  (if available), until the target ceases to request them.
  @end table
  
+ @item QTDP
+ @itemx QTFrame
+ @xref{Tracepoint Packets}.
+ 
  @item qThreadExtraInfo,@var{id}
  @cindex thread attributes info, remote request
  @cindex @samp{qThreadExtraInfo} packet
*************** comprising the printable string containi
*** 23048,23053 ****
--- 23053,23065 ----
  the thread's attributes.
  @end table
  
+ @item QTStart    
+ @itemx QTStop     
+ @itemx QTinit     
+ @itemx QTro       
+ @itemx qTStatus   
+ @xref{Tracepoint Packets}.
+ 
  @end table
  
  @node Register Packet Format
*************** as @code{MIPS32}.
*** 23076,23081 ****
--- 23088,23252 ----
  
  @end table
  
+ @node Tracepoint Packets
+ @section Tracepoint Packets
+ 
+ Here we describe the packets @value{GDBN} uses to implement
+ tracepoints (@pxref{Tracepoints}).
+ 
+ @table @samp
+ 
+ @item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}@r{[}-@r{]}
+ Create a new tracepoint, number @var{n}, at @var{addr}.  If @var{ena}
+ is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
+ the tracepoint is disabled.  @var{step} is the tracepoint's step
+ count, and @var{pass} is its pass count.  If the trailing @samp{-} is
+ present, further @samp{QTDP} packets will follow to specify this
+ tracepoint's actions.
+ 
+ Replies:
+ @table @samp
+ @item OK
+ The packet was understood and carried out.
+ @item 
+ The packet was not recognized.
+ @end table
+ 
+ @item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
+ Define actions to be taken when a tracepoint is hit.  @var{n} and
+ @var{addr} must be the same as in the initial @samp{QTDP} packet for
+ this tracepoint.  This packet may only be sent immediately after
+ another @samp{QTDP} packet that ended with a @samp{-}.  If the
+ trailing @samp{-} is present, further @samp{QTDP} packets will follow,
+ specifying more actions for this tracepoint.
+ 
+ In the series of action packets for a given tracepoint, at most one
+ can have an @samp{S} before its first @var{action}.  If such a packet
+ is sent, it and the following packets define ``while-stepping''
+ actions.  Any prior packets define ordinary actions --- that is, those
+ taken when the tracepoint is first hit.  If no action packet has an
+ @samp{S}, then all the packets in the series specify ordinary
+ tracepoint actions.
+ 
+ The @samp{@var{action}@dots{}} portion of the packet is a series of
+ actions, concatenated without separators.  Each action has one of the
+ following forms:
+ 
+ @table @samp
+ 
+ @item R @var{mask}
+ Collect the registers whose bits are set in @var{mask}.  @var{mask} is
+ a hexidecimal number whose @var{i}'th bit is set if register number
+ @var{i} should be collected.  (The least significant bit is numbered
+ zero.)  Note that @var{mask} may be any number of digits long; it may
+ not fit in a 32-bit word.
+ 
+ @item M @var{basereg},@var{offset},@var{len}
+ Collect @var{len} bytes of memory starting at the address in register
+ number @var{basereg}, plus @var{offset}.  If @var{basereg} is
+ @samp{-1}, then the range has a fixed address: @var{offset} is the
+ address of the lowest byte to collect.  The @var{basereg},
+ @var{offset}, and @var{len} parameters are all unsigned hexidecimal
+ values (the @samp{-1} value for @var{basereg} is a special case).
+ 
+ @item X @var{len},@var{expr}
+ Evaluate @var{expr}, whose length is @var{len}, and collect memory as
+ it directs.  @var{expr} is an agent expression, as described in
+ @ref{Agent Expressions}.  Each byte of the expression is encoded as a
+ two-digit hex number in the packet; @var{len} is the number of bytes
+ in the expression (and thus one-half the number of hex digits in the
+ packet).
+ 
+ @end table
+ 
+ Any number of actions may be packed together in a single @samp{QTDP}
+ packet, as long as the packet does not exceed the maximum packet
+ length (400 bytes, for many stubs).
+ 
+ Replies:
+ @table @samp
+ @item OK
+ The packet was understood and carried out.
+ @item 
+ The packet was not recognized.
+ @end table
+ 
+ @item QTFrame:@var{n}
+ Select the @var{n}'th tracepoint frame from the buffer, and use the
+ register and memory contents recorded there to answer subsequent
+ request packets from @value{GDBN}.
+ 
+ A successful reply from the stub and indicates that the stub has found
+ the requested frame.  The response is a series of parts, concatenated
+ without separators, describing the frame we selected.  Each part has
+ one of the following forms:
+ 
+ @table @samp
+ @item F @var{f}
+ The selected frame is number @var{n} in the trace frame buffer;
+ @var{f} is a hexidecimal number.  If @var{f} is @samp{-1}, then there
+ was no frame matching the criteria in the request packet.
+ 
+ @item T @var{t}
+ The selected trace frame records a hit of tracepoint number @var{t};
+ @var{t} is a hexidecimal number.
+ 
+ @end table
+ 
+ @item QTFrame:pc:@var{addr}
+ Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+ currently selected frame whose PC is @var{addr};
+ @var{addr} is a hexidecimal number.
+ 
+ @item QTFrame:tdp:@var{t}
+ Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+ currently selected frame that is a hit of tracepoint @var{t}; @var{t}
+ is a hexidecimal number.
+ 
+ @item QTFrame:range:@var{start}:@var{end}
+ Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+ currently selected frame whose PC is between @var{start} (inclusive)
+ and @var{end} (exclusive); @var{start} and @var{end} are hexidecimal
+ numbers.
+ 
+ @item QTFrame:outside:@var{start}:@var{end}
+ Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
+ frame @emph{outside} the given range of addresses.
+ 
+ @item QTStart
+ Begin the tracepoint experiment.  Begin collecting data from tracepoint
+ hits in the trace frame buffer.
+ 
+ @item QTStop
+ End the tracepoint experiment.  Stop collecting trace frames.
+ 
+ @item QTinit
+ Clear the table of tracepoints, and empty the trace frame buffer.
+ 
+ @item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
+ Establish the given ranges of memory as ``transparent''.  The stub
+ will answer requests for these ranges from memory's current contents,
+ if they were not collected as part of the tracepoint hit.
+ 
+ @value{GDBN} uses this to mark read-only regions of memory, like those
+ containing program code.  Since these areas never change, they should
+ still have the same contents they did when the tracepoint was hit, so
+ there's no reason for the stub to refuse to provide their contents.
+ 
+ @item qTStatus
+ Ask the stub if there is a trace experiment running right now.
+ 
+ Replies:
+ @table @samp
+ @item T0
+ There is no trace experiment running.
+ @item T1
+ There is a trace experiment running.
+ @end table
+ 
+ @end table
+ 
+ 
  @node Interrupts
  @section Interrupts
  @cindex interrupts (remote protocol)

Re: RFA: GDB manual: document tracepoint packets

[Eli Zaretskii]

> Date: Sat, 19 Nov 2005 12:31:20 -0800
> From: Jim Blandy <jimb@red-bean.com>
> 
> 2005-11-19  Jim Blandy  <jimb@redhat.com>
> 
> 	* gdb.texinfo (Tracepoint Packets): New node.
> 	(General Query Packets): Add entries for the tracepoint packets,
> 	referring to the "Tracepoint Packets" node.

Thanks.  My comments are below.

> + @node Tracepoint Packets
> + @section Tracepoint Packets

Suggest a @cindex entry here, something like "tracepoint packets".

> + Here we describe the packets @value{GDBN} uses to implement
> + tracepoints (@pxref{Tracepoints}).

I think it would be good to have an @xref from the "Tracepoints" node
to here as well.

> + Replies:
> + @table @samp
> + @item OK
> + The packet was understood and carried out.
> + @item 

Does this @item really need to be empty?  If so, why, and what do we
want to appear here in print?

> + @item 
> + The packet was not recognized.

Same here.

> + A successful reply from the stub and indicates that the stub has found
                                     ^^^
That "and" seems extraneous.

Other than that, this can go in.  Thanks again for working on this.

Re: RFA: GDB manual: document tracepoint packets

[Jim Blandy]

On 11/19/05, Eli Zaretskii <eliz@gnu.org> wrote:
> > + @node Tracepoint Packets
> > + @section Tracepoint Packets
>
> Suggest a @cindex entry here, something like "tracepoint packets".

D'oh.  Of course.

> > + Here we describe the packets @value{GDBN} uses to implement
> > + tracepoints (@pxref{Tracepoints}).
>
> I think it would be good to have an @xref from the "Tracepoints" node
> to here as well.

Added.

> > + Replies:
> > + @table @samp
> > + @item OK
> > + The packet was understood and carried out.
> > + @item
>
> Does this @item really need to be empty?  If so, why, and what do we
> want to appear here in print?

It does.  This appears as a pair of matched single quotes enclosing
nothing in both the Info and printable manuals.  The remote stub
returns an empty packet to indicate that it didn't understand the
command.  Blank @items are used elsewhere in the manual for this
purpose.

> > + A successful reply from the stub and indicates that the stub has found
>                                      ^^^
> That "and" seems extraneous.

It is.

> Other than that, this can go in.  Thanks again for working on this.

I'll commit it.  Thanks very much for your prompt review!

Re: RFA: GDB manual: document tracepoint packets

[Jim Blandy]

[-- Attachment #1: Type: text/plain, Size: 45 bytes --]

I've attached the patch actually committed.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: jimb.gdb-doc-remote-protocol-tracepoints.patch --]
[-- Type: text/x-patch; name="jimb.gdb-doc-remote-protocol-tracepoints.patch", Size: 9080 bytes --]

gdb/doc/ChangeLog:
2005-11-19  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (Tracepoint Packets): New node.
	(General Query Packets): Add entries for the tracepoint packets,
	referring to the "Tracepoint Packets" node.
	(Tracepoints): Add reference to "Tracepoint Packets".

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.295
diff -c -p -r1.295 gdb.texinfo
*** gdb/doc/gdb.texinfo	18 Nov 2005 22:17:09 -0000	1.295
--- gdb/doc/gdb.texinfo	20 Nov 2005 05:47:11 -0000
*************** values without interacting with you, it 
*** 7126,7135 ****
  unobtrusively, hopefully not disturbing the program's behavior.
  
  The tracepoint facility is currently available only for remote
! targets.  @xref{Targets}.  In addition, your remote target must know how
! to collect trace data.  This functionality is implemented in the remote
! stub; however, none of the stubs distributed with @value{GDBN} support
! tracepoints as of this writing.
  
  This chapter describes the tracepoint commands and features.
  
--- 7126,7137 ----
  unobtrusively, hopefully not disturbing the program's behavior.
  
  The tracepoint facility is currently available only for remote
! targets.  @xref{Targets}.  In addition, your remote target must know
! how to collect trace data.  This functionality is implemented in the
! remote stub; however, none of the stubs distributed with @value{GDBN}
! support tracepoints as of this writing.  The format of the remote
! packets used to implement tracepoints are described in @ref{Tracepoint
! Packets}.
  
  This chapter describes the tracepoint commands and features.
  
*************** Show the current setting of the target w
*** 22017,22022 ****
--- 22019,22025 ----
  * Stop Reply Packets::
  * General Query Packets::
  * Register Packet Format::
+ * Tracepoint Packets::
  * Interrupts::
  * Examples::
  * File-I/O remote protocol extension::
*************** encoded).  @value{GDBN} will continue to
*** 23029,23034 ****
--- 23032,23041 ----
  (if available), until the target ceases to request them.
  @end table
  
+ @item QTDP
+ @itemx QTFrame
+ @xref{Tracepoint Packets}.
+ 
  @item qThreadExtraInfo,@var{id}
  @cindex thread attributes info, remote request
  @cindex @samp{qThreadExtraInfo} packet
*************** comprising the printable string containi
*** 23048,23053 ****
--- 23055,23067 ----
  the thread's attributes.
  @end table
  
+ @item QTStart    
+ @itemx QTStop     
+ @itemx QTinit     
+ @itemx QTro       
+ @itemx qTStatus   
+ @xref{Tracepoint Packets}.
+ 
  @end table
  
  @node Register Packet Format
*************** as @code{MIPS32}.
*** 23076,23081 ****
--- 23090,23256 ----
  
  @end table
  
+ @node Tracepoint Packets
+ @section Tracepoint Packets
+ @cindex tracepoint packets
+ @cindex packets, tracepoint
+ 
+ Here we describe the packets @value{GDBN} uses to implement
+ tracepoints (@pxref{Tracepoints}).
+ 
+ @table @samp
+ 
+ @item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}@r{[}-@r{]}
+ Create a new tracepoint, number @var{n}, at @var{addr}.  If @var{ena}
+ is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
+ the tracepoint is disabled.  @var{step} is the tracepoint's step
+ count, and @var{pass} is its pass count.  If the trailing @samp{-} is
+ present, further @samp{QTDP} packets will follow to specify this
+ tracepoint's actions.
+ 
+ Replies:
+ @table @samp
+ @item OK
+ The packet was understood and carried out.
+ @item 
+ The packet was not recognized.
+ @end table
+ 
+ @item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
+ Define actions to be taken when a tracepoint is hit.  @var{n} and
+ @var{addr} must be the same as in the initial @samp{QTDP} packet for
+ this tracepoint.  This packet may only be sent immediately after
+ another @samp{QTDP} packet that ended with a @samp{-}.  If the
+ trailing @samp{-} is present, further @samp{QTDP} packets will follow,
+ specifying more actions for this tracepoint.
+ 
+ In the series of action packets for a given tracepoint, at most one
+ can have an @samp{S} before its first @var{action}.  If such a packet
+ is sent, it and the following packets define ``while-stepping''
+ actions.  Any prior packets define ordinary actions --- that is, those
+ taken when the tracepoint is first hit.  If no action packet has an
+ @samp{S}, then all the packets in the series specify ordinary
+ tracepoint actions.
+ 
+ The @samp{@var{action}@dots{}} portion of the packet is a series of
+ actions, concatenated without separators.  Each action has one of the
+ following forms:
+ 
+ @table @samp
+ 
+ @item R @var{mask}
+ Collect the registers whose bits are set in @var{mask}.  @var{mask} is
+ a hexidecimal number whose @var{i}'th bit is set if register number
+ @var{i} should be collected.  (The least significant bit is numbered
+ zero.)  Note that @var{mask} may be any number of digits long; it may
+ not fit in a 32-bit word.
+ 
+ @item M @var{basereg},@var{offset},@var{len}
+ Collect @var{len} bytes of memory starting at the address in register
+ number @var{basereg}, plus @var{offset}.  If @var{basereg} is
+ @samp{-1}, then the range has a fixed address: @var{offset} is the
+ address of the lowest byte to collect.  The @var{basereg},
+ @var{offset}, and @var{len} parameters are all unsigned hexidecimal
+ values (the @samp{-1} value for @var{basereg} is a special case).
+ 
+ @item X @var{len},@var{expr}
+ Evaluate @var{expr}, whose length is @var{len}, and collect memory as
+ it directs.  @var{expr} is an agent expression, as described in
+ @ref{Agent Expressions}.  Each byte of the expression is encoded as a
+ two-digit hex number in the packet; @var{len} is the number of bytes
+ in the expression (and thus one-half the number of hex digits in the
+ packet).
+ 
+ @end table
+ 
+ Any number of actions may be packed together in a single @samp{QTDP}
+ packet, as long as the packet does not exceed the maximum packet
+ length (400 bytes, for many stubs).
+ 
+ Replies:
+ @table @samp
+ @item OK
+ The packet was understood and carried out.
+ @item 
+ The packet was not recognized.
+ @end table
+ 
+ @item QTFrame:@var{n}
+ Select the @var{n}'th tracepoint frame from the buffer, and use the
+ register and memory contents recorded there to answer subsequent
+ request packets from @value{GDBN}.
+ 
+ A successful reply from the stub indicates that the stub has found the
+ requested frame.  The response is a series of parts, concatenated
+ without separators, describing the frame we selected.  Each part has
+ one of the following forms:
+ 
+ @table @samp
+ @item F @var{f}
+ The selected frame is number @var{n} in the trace frame buffer;
+ @var{f} is a hexidecimal number.  If @var{f} is @samp{-1}, then there
+ was no frame matching the criteria in the request packet.
+ 
+ @item T @var{t}
+ The selected trace frame records a hit of tracepoint number @var{t};
+ @var{t} is a hexidecimal number.
+ 
+ @end table
+ 
+ @item QTFrame:pc:@var{addr}
+ Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+ currently selected frame whose PC is @var{addr};
+ @var{addr} is a hexidecimal number.
+ 
+ @item QTFrame:tdp:@var{t}
+ Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+ currently selected frame that is a hit of tracepoint @var{t}; @var{t}
+ is a hexidecimal number.
+ 
+ @item QTFrame:range:@var{start}:@var{end}
+ Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+ currently selected frame whose PC is between @var{start} (inclusive)
+ and @var{end} (exclusive); @var{start} and @var{end} are hexidecimal
+ numbers.
+ 
+ @item QTFrame:outside:@var{start}:@var{end}
+ Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
+ frame @emph{outside} the given range of addresses.
+ 
+ @item QTStart
+ Begin the tracepoint experiment.  Begin collecting data from tracepoint
+ hits in the trace frame buffer.
+ 
+ @item QTStop
+ End the tracepoint experiment.  Stop collecting trace frames.
+ 
+ @item QTinit
+ Clear the table of tracepoints, and empty the trace frame buffer.
+ 
+ @item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
+ Establish the given ranges of memory as ``transparent''.  The stub
+ will answer requests for these ranges from memory's current contents,
+ if they were not collected as part of the tracepoint hit.
+ 
+ @value{GDBN} uses this to mark read-only regions of memory, like those
+ containing program code.  Since these areas never change, they should
+ still have the same contents they did when the tracepoint was hit, so
+ there's no reason for the stub to refuse to provide their contents.
+ 
+ @item qTStatus
+ Ask the stub if there is a trace experiment running right now.
+ 
+ Replies:
+ @table @samp
+ @item T0
+ There is no trace experiment running.
+ @item T1
+ There is a trace experiment running.
+ @end table
+ 
+ @end table
+ 
+ 
  @node Interrupts
  @section Interrupts
  @cindex interrupts (remote protocol)

Re: RFA: GDB manual: document tracepoint packets

[Eli Zaretskii]

> Date: Sat, 19 Nov 2005 21:43:58 -0800
> From: Jim Blandy <jimb@red-bean.com>
> Cc: gdb-patches@sources.redhat.com
> 
> > > + @item OK
> > > + The packet was understood and carried out.
> > > + @item
> >
> > Does this @item really need to be empty?  If so, why, and what do we
> > want to appear here in print?
> 
> It does.  This appears as a pair of matched single quotes enclosing
> nothing in both the Info and printable manuals.  The remote stub
> returns an empty packet to indicate that it didn't understand the
> command.  Blank @items are used elsewhere in the manual for this
> purpose.

Should we perhaps say "(empty)" to prevent readers from thinking it's
a typo?

Re: RFA: GDB manual: document tracepoint packets

[Jim Blandy]

On 11/20/05, Eli Zaretskii <eliz@gnu.org> wrote:
> Should we perhaps say "(empty)" to prevent readers from thinking it's
> a typo?

You'll still get the single quotes around the thing, since it's a
@table @samp.  I think '' is pretty widely recognized.

If you've looked at the way both @item and @item @r{(empty)} look in
print and info, and you prefer the latter, I'd be happy to make the
change.

Re: RFA: GDB manual: document tracepoint packets

[Eli Zaretskii]

> Date: Sun, 20 Nov 2005 13:22:51 -0800
> From: Jim Blandy <jimb@red-bean.com>
> Cc: gdb-patches@sources.redhat.com
> 
> If you've looked at the way both @item and @item @r{(empty)} look in
> print and info, and you prefer the latter, I'd be happy to make the
> change.

If you think it's not needed, let's leave it at that.