diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 7 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 75 |
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 |