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