This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

RFA: GDB manual: document tracepoint packets


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.
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)

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]