[PATCH] Document tracepoint restrictions

[Stan Shebs <stan@codesourcery.com>]

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

While the savvy GDB hacker can use sekrit GDB internals knowledge to 
surmise what will and won't work with tracepoints, normal users can 
benefit from it being spelled out more explicitly.  This patch adds a 
new section to the manual that explains some of the gotchas our new 
generation of tracepoint users has experienced already.

Stan

2010-03-11  Stan Shebs  <stan@codesourcery.com>
        Nathan Sidwell  <nathan@codesourcery.com>

    * gdb.texinfo (Tracepoint Actions): Clarify that while-stepping is
    doing instruction stepping.
    (Tracepoint Restrictions): New node.


[-- Attachment #2: restrict-patch-1 --]
[-- Type: text/plain, Size: 5038 bytes --]

Index: ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/doc/ChangeLog,v
retrieving revision 1.1021
diff -p -r1.1021 ChangeLog
*** ChangeLog	10 Mar 2010 18:20:07 -0000	1.1021
--- ChangeLog	12 Mar 2010 02:33:51 -0000
***************
*** 1,3 ****
--- 1,10 ----
+ 2010-03-11  Stan Shebs  <stan@codesourcery.com>
+ 	    Nathan Sidwell  <nathan@codesourcery.com>
+ 
+ 	* gdb.texinfo (Tracepoint Actions): Clarify that while-stepping is
+ 	doing instruction stepping.
+ 	(Tracepoint Restrictions): New node.
+ 
  2010-03-10  Tom Tromey  <tromey@redhat.com>
  
  	* gdbint.texinfo (Symbol Handling): Update.
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.679
diff -p -r1.679 gdb.texinfo
*** gdb.texinfo	8 Mar 2010 19:20:38 -0000	1.679
--- gdb.texinfo	12 Mar 2010 02:33:52 -0000
*************** conditions and actions.
*** 9352,9357 ****
--- 9352,9358 ----
  * Tracepoint Actions::
  * Listing Tracepoints::
  * Starting and Stopping Trace Experiments::
+ * Tracepoint Restrictions::
  @end menu
  
  @node Create and Delete Tracepoints
*************** action were used.
*** 9668,9677 ****
  
  @kindex while-stepping @r{(tracepoints)}
  @item while-stepping @var{n}
! Perform @var{n} single-step traces after the tracepoint, collecting
! new data at each step.  The @code{while-stepping} command is
! followed by the list of what to collect while stepping (followed by
! its own @code{end} command):
  
  @smallexample
  > while-stepping 12
--- 9669,9678 ----
  
  @kindex while-stepping @r{(tracepoints)}
  @item while-stepping @var{n}
! Perform @var{n} single-step instruction traces after the tracepoint,
! collecting new data at each instruction.  The @code{while-stepping}
! command is followed by the list of what to collect while stepping
! (followed by its own @code{end} command):
  
  @smallexample
  > while-stepping 12
*************** which to specify that tracepoint.  This 
*** 9835,9840 ****
--- 9836,9900 ----
  necessarily heuristic, and it may result in useless tracepoints being
  created; you may simply delete them if they are of no use.
  
+ @node Tracepoint Restrictions
+ @subsection Tracepoint Restrictions
+ 
+ There are a number of restrictions on the use of tracepoints.
+ 
+ @itemize @bullet
+ 
+ @item
+ Tracepoint expressions are intended to gather objects (lvalues).  Thus
+ the full flexibility of GDB's expression evaluator is not available.
+ You cannot call functions, cast objects to aggregate types, access
+ convenience variables or modify values (except by assignment to trace
+ state variables).  Objective-C and Objective-C++ features are not
+ supported.
+ 
+ @item
+ Collection of local variables, either individually or in bulk with
+ @code{$locals} or @code{$args}, during @code{while-stepping} may
+ behave erratically.  The stepping action may enter a new scope (for
+ instance by stepping into a function), or the location of the variable
+ may change (for instance it is loaded into a register).  The
+ tracepoint data recorded uses the location information for the
+ variables that is correct for the tracepoint location.  When the
+ tracepoint is created, it is not possible, in general, to determine
+ where the steps of a @code{while-stepping} sequence will advance the
+ program -- particularly if a conditional branch is stepped.
+ 
+ @item
+ Collection of an incompletely-initialized or partially-destroyed object
+ may result in something that @value{GDBN} cannot display, or displays
+ in a misleading way.
+ 
+ @item
+ When @value{GDBN} displays a pointer to character it automatically
+ dereferences the pointer to also display characters of the string
+ being pointed to.  However, collecting the pointer during tracing does
+ not automatically collect the string.  You need to explicitly
+ dereference the pointer and provide size information if you want to
+ collect not only the pointer, but the memory pointed to.  For example
+ @code{*ptr@@50} can be used to collect the 50 element array pointed to
+ by @code{ptr}.
+ 
+ @item
+ It is not possible to collect a complete stack backtrace at a
+ tracepoint.  Instead you may collect the registers and a few hundred
+ bytes from the stack pointer with something like @code{*$esp@@300}
+ (adjust to use the name of the actual stack pointer register on your
+ target architecture, and the amount of stack you wish to capture).
+ Then the @code{backtrace} command will show a partial backtrace when
+ using a trace frame.  The number of stack frames that can be examined
+ depends on the sizes of the frames in the collected stack.
+ 
+ @end itemize
+ 
+ The above is not intended as an exhaustive list of restrictions.  As
+ described above, tracepoint data gathering occurs on the target
+ without interaction from GDB.  Thus the full capabilities of GDB are
+ not available during data gathering.
+ 
  @node Analyze Collected Data
  @section Using the Collected Data