Tracepoints documentation

[Elena Zannoni <ezannoni at cygnus dot com>]

Eli, 

I retireved from my dusty mailbox some tracepoint documentation that
was written some time back (when the tracepoints were originally
implemented) (1998, that is).  I reformatted it from a .doc file. This
should be suitable for inclusion in the gdb user's manual.

The texinfo/info formatting is not very well done. I'll leave that to
you. :-)

I believe Michael Snyder is the original author of the documentation,
which was revised by our tech writers and probably other people (like
David Taylor, Jim Blandy and me).

Hope it is useful. Unfortunately there isn't a remote target that
supports tracepoints at the moment, so we cannot verify that all works
as claimed.

Elena


\input texinfo
@setfilename tracepoints.info
@include gdb-cfg.texi
@ifinfo
@format
@end format
@end ifinfo

@setchapternewpage off
@settitle @value{GDBN} Tracepoints

@titlepage
@title @value{GDBN} Tracepoints
@end titlepage

@c TeX can handle the contents at the start but makeinfo 3.12 can not
@iftex
@contents
@end iftex

@menu
* Tracepoints::
@end menu


@chapter Tracepoints

For remote targets, @value{GDBN} allows "tracepoints" to be set. A
tracepoint is similar to a breakpoint. However, when the remote
machine hits a tracepoint, instead of stopping and sending a signal to
@value{GDBN}, it makes an entry into an internal buffer and continues
program execution. This can be done very quickly (i.e.  without
slowing down the program very much). @value{GDBN} can examine the
"trace buffer" later, to analyze what took place at the tracepoint
after-the-fact.

Before running a trace experiment, an arbitrary number of tracepoints
can be set. For each tracepoint, you can specify, in advance, some
arbitrary set of data that you want the target to collect and throw
into the trace buffer when it hits the tracepoint. This can include
registers, local variables, or global data. Later @value{GDBN} can see
what values these data had at the time the tracepoint was hit.

@section Tracepoint Commands
@subsection Setting Up Tracing
@table @code
@item trace

The @code{trace} command is very similar to the @code{break} command. Its
argument can be a source line, a function name, or an address in the
target program. This command defines a tracepoint, which is a point in
the target program where the debugger will briefly stop, collect some
data, and then allow the program to continue.

@smallexample
trace foo.c:121		// a source file and line number 
 
trace my_function	// first source line of function 
 
trace *my_function	// EXACT start address of function 
 
trace *0x2117c4		// an address
@end smallexample

@item info trace <optional_tracepoint_number>

Show a list of the tracepoints defined so far, or show information
about one particular tracepoint.

@smallexample
(@value{GDBP}) @b{info trace}
Num Enb Address    PassC StepC What 
1   y   0x002117c4 0     0     <gdb_asm> 
2   y   0x0020dc64 0     0     in gdb_test at gdb_test.c:375 
3   y   0x0020b1f4 0     0     in collect_data at ../foo.c:1741 
(@value{GDBP})
@end smallexample


@item delete tracepoint <optional_tracepoint_numbers>

Permanently delete one or more tracepoint(s). With no argument, the
default is to delete all tracepoints.
@smallexample
delete trace 1 2 3	// remove three tracepoints 
 
delete trace		// remove all tracepoints
@end smallexample

@item passcount <count> <optional_tracepoint_number>

Set the "passcount" for a tracepoint. The passcount is a way to
automatically stop a trace experiment once it is started. If a
tracepoint's passcount is N, then the trace experiment will be
automatically stopped on the Nth time that tracepoint is hit. The
default tracepoint is the one most recently defined. If no passcount
is given, the trace experiment will run until stopped explicitly by
the user.

@smallexample
passcount 5 2   // Stop tracing on the 5th execution of tracepoint 2 
 
passcount 12    // Stop on the 12th execution of the most recently  
                // defined tracepoint.
trace foo 
pass 3 
trace bar 
pass 2 
trace baz 
pass 1         // Stop tracing when foo has been executed 3 times 
               // OR when bar has been executed 2 times 
               // OR when baz has been executed 1 time.
@end smallexample

@item actions <optional_tracepoint_number>

This command will prompt for a list of actions to be taken when the
tracepoint is hit.  The default tracepoint is the one that was most
recently defined (so that you can define a tracepoint and then say
@code{actions} without needing to know its number). So far, the only
defined actions are @code{collect}, @code{while-stepping}, and @code{end}.

@smallexample
collect <data>       // collect some data 
 
while-stepping <n>   // single-step <n> times and collect data 
 
end                  // signifies the end of actions.
@end smallexample

In the following example, the action list begins with @code{collect}
commands indicating the things to be collected when the tracepoint is
hit. Then, in order to single-step and collect additional data
following the tracepoint, is a @code{while-stepping} command, followed
by the list of things to be collected while stepping. The
@code{while-stepping} command is terminated by its own separate
@code{end} command. Lastly, the action list is terminated by an
@code{end} command.

@smallexample
(@value{GDBP}) trace foo 
(@value{GDBP}) actions 
Enter actions for tracepoint 1, one per line: 
> collect bar,baz,baz
> collect $regs 
> while-stepping 12 
  > collect $fp, $sp 
  > end 
end
@end smallexample

@item collect <comma separated list>

Collect certain data while tracing. This command accepts a
comma-separated list of variable names, register names, or the
following special arguments:

@smallexample
collect $regs		// all registers 
 
collect $args		// all function arguments 
 
collect $locals	// all local variables  
@end smallexample

You can give several consecutive @code{collect} commands with single
arguments, or one @code{collect} command several arguments separated
by commas: it's all the same.

@item while-stepping <n>

Perform @code{<n>} single-step 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 
  > collect $regs, myglobal 
  > end 
>
@end smallexample

@item tstart

Takes no arguments. Start the trace experiment, begin collecting data.

@item tstop
 
Takes no arguments. End the trace experiment, stop collecting data.

@end table 

Here is an example of what we have so far:

@smallexample
(@value{GDBP}) trace gdb_c_test 
 
(@value{GDBP}) actions 
Enter actions for tracepoint #1, one per line. 
> collect $regs,$locals,$args 
> while-stepping 11 
  > collect $regs 
  > end 
> end 
 
(@value{GDBP}) tstart
	[...]
(@value{GDBP}) tstop
@end smallexample


@section Using the collected data

Now, here are the @value{GDBN} commands for examining the trace data
after a trace experiment.  The basic idea is that each tracepoint
collects a trace "frame" every time it is hit and another "frame"
every time it single-steps. All these frames go into a buffer,
consecutively numbered from zero, and we can then examine them later.
The way we examine them is to "focus" on a trace frame. When the stub
is "focused" on a trace frame, it will respond to all @value{GDBN}
requests for memory and registers by reading from that frame buffer,
rather than from "real" memory or registers. This means that ALL
@value{GDBN} commands (@code{print}, @code{info registers},
@code{backtrace}, etc.) will behave as if we were currently debugging
the program state as it was when the tracepoint occurred. Any requests
for data that are not in the buffer will fail.


@subsection @code{tfind <n>}

The basic command for selecting a trace frame from the buffer is
@code {tfind <n>}, which finds trace frame <n>, counting from zero.

@subsection Special arguments to 'tfind'

@table @code
@item tfind start 
Find first frame in the buffer.

@item tfind none 
Stop debugging trace frames, resume "live" debugging.

@item tfind end 
Same as 'none'.

@item tfind 
No argument means "next trace frame".

@item tfind - 
Means "previous trace frame before current one". This permits
retracing earlier steps.

@item tfind tracepoint <n> 
Find the next frame associated with tracepoint <n>. Search proceeds
forward from the last trace frame examined .No argument means, find
the next frame with the same tracepoint as the current frame.

@item tfind pc <x> 
Find the next frame associated with the PC '<x>'. Search proceeds
forward from the last trace frame examined. No argument means, find
the next frame with the same PC as the current frame.

@item tfind line <n> 
Find the next frame associated with the source line '<n>'. Search
proceeds forward from the last trace frame examined. No argument means
next line other than the one currently being examined; thus saying
@code{tfind line} repeatedly can appear to have the same effect as
stepping from line to line in a "live" debugging session.  

@end table

The default arguments for the @code{tfind} commands are specifically
designed to make it easy to scan through the trace buffer. For instance,
@code{tfind} with no argument selects the next trace frame and
@code{tfind -} with no argument selects the previous trace frame. So, by
giving one @code{tfind} command, and then simply hitting return
repeatedly, you can examine each trace frame consecutively. Or, by
saying @code{tfind -} and then hitting return repeatedly, you can
examine them in reverse order.  The @code{tfind line} command with no
argument selects the frame for the next source line executed. The
@code{tfind pc} command with no argument selects the next frame with the
same program counter (PC) as the current frame. The @code{tfind
tracepoint} command with no argument selects the next trace frame
collected by the same tracepoint as the current one.

In addition to letting you scan through the trace buffer manually,
these commands make it easy to construct @value{GDBN} scripts that
scan through the trace buffer and print out whatever collected data
you are interested in.  Thus, if we want to examine the PC, FP, and SP
from each trace frame in the buffer:

@smallexample
(@value{GDBP}) tfind start 
(@value{GDBP}) while ($trace_frame != -1) 
> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 
          $trace_frame, $pc, $sp, $fp 
> tfind 
> end 
 
Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 
Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 
Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 
Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 
Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 
Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 
Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 
Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 
Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 
Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 
Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
@end smallexample

Or, if we want to examine variable 'X' at each source line in the buffer:

@smallexample
(@value{GDBP}) tfind start 
(@value{GDBP}) while ($trace_frame != -1) 
> printf "Frame %d, X == %d\n", $trace_frame, X 
> tfind line 
> end 
 
Frame 0, X = 1 
Frame 7, X = 2 
Frame 13, X = 255
@end smallexample

@subsection @code{tdump}

Takes no argument. Print everything that was collected at the current
trace frame.

@smallexample
(@value{GDBP}) trace 444 
(@value{GDBP}) actions 
Enter actions for tracepoint #2, one per line: 
> collect $regs, $locals, $args, gdb_long_test 
> end 
 
(@value{GDBP}) tstart 
 
(@value{GDBP}) tfind line 444 
#0  gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 
at gdb_test.c:444 
444        printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 
 
(@value{GDBP}) tdump 
Data collected at tracepoint 2, trace frame 1: 
d0             0xc4aa0085       -995491707 
d1             0x18     24 
d2             0x80     128 
d3             0x33     51 
d4             0x71aea3d        119204413 
d5             0x22     34 
d6             0xe0     224 
d7             0x380035 3670069 
a0             0x19e24a 1696330 
a1             0x3000668        50333288 
a2             0x100    256 
a3             0x322000 3284992 
a4             0x3000698        50333336 
a5             0x1ad3cc 1758156 
fp             0x30bf3c 0x30bf3c 
sp             0x30bf34 0x30bf34 
ps             0x0      0 
pc             0x20b2c8 0x20b2c8 
fpcontrol      0x0      0 
fpstatus       0x0      0 
fpiaddr        0x0      0 
p = 0x20e5b4 "gdb-test" 
p1 = (void *) 0x11 
p2 = (void *) 0x22 
p3 = (void *) 0x33 
p4 = (void *) 0x44 
p5 = (void *) 0x55 
p6 = (void *) 0x66 
gdb_long_test = 17 '\021' 
 
(@value{GDBP})
@end smallexample

@subsection @code{save-tracepoints <filename>}

Save all current tracepoint definitions together with their actions
and passcounts, into a file suitable for use in a later debugging
session.


@section Special built-in debugger variables for use in formatted output

@table @code
@item (int) $trace_frame
The current trace frame number

@item (int) $tracepoint
The tracepoint for the current trace frame

@item (int) $trace_line
The line number for the current trace frame

@item (char []) $trace_file
The source file for the current trace frame.
@end table

Note: @code{$trace_file} is not suitable for use in @code{printf},
instead use @code{output}.


@smallexample
(@value{GDBP}) tfind start 
 
(@value{GDBP}) while $trace_frame != 0 
> output $trace_file 
> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 
> tfind 
> end
@end smallexample

@c TeX can handle the contents at the start but makeinfo 3.12 can not
@ifinfo
@contents
@end ifinfo
@ifhtml
@contents
@end ifhtml

@bye