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.
This commit is contained in:
Stan Shebs 2010-03-12 19:15:52 +00:00
parent 9cad29ac31
commit c942923237
2 changed files with 78 additions and 4 deletions

View file

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

View file

@ -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