2010-03-12 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.

2 files changed, 78 insertions, 4 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index daa7c26..7a9590e 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,10 @@
+2010-03-12  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.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a1f3a78..53989bb 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9352,6 +9352,7 @@ conditions and actions.
 * Tracepoint Actions::
 * Listing Tracepoints::
 * Starting and Stopping Trace Experiments::
+* Tracepoint Restrictions::
 @end menu
 
 @node Create and Delete Tracepoints
@@ -9668,10 +9669,10 @@ action were used.
 
 @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):
+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
@@ -9835,6 +9836,72 @@ which to specify that tracepoint.  This matching-up process is
 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
+
+@cindex tracepoint restrictions
+There are a number of restrictions on the use of tracepoints.  As
+described above, tracepoint data gathering occurs on the target
+without interaction from @value{GDBN}.  Thus the full capabilities of
+the debugger are not available during data gathering, and then at data
+examination time, you will be limited by only having what was
+collected.  The following items describe some common problems, but it
+is not exhaustive, and you may run into additional difficulties not
+mentioned here.
+
+@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).  Some language features may implicitly call
+functions (for instance Objective-C fields with accessors), and therefore
+cannot be collected either.
+
+@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.  Note that
+if you ask for a block so large that it goes past the bottom of the
+stack, the target agent may report an error trying to read from an
+invalid address.
+
+@end itemize
+
 @node Analyze Collected Data
 @section Using the Collected Data