gdb: Create and Delete Tracepoints
13.1.1 Create and Delete Tracepoints
------------------------------------
'trace LOCATION'
The 'trace' command is very similar to the 'break' command. Its
argument LOCATION can be any valid location. Specify
Location. The 'trace' 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. Setting
a tracepoint or changing its actions takes effect immediately if
the remote stub supports the 'InstallInTrace' feature (
install tracepoint in tracing). If remote stub doesn't support
the 'InstallInTrace' feature, all these changes don't take effect
until the next 'tstart' command, and once a trace experiment is
running, further changes will not have any effect until the next
trace experiment starts. In addition, GDB supports "pending
tracepoints"--tracepoints whose address is not yet resolved. (This
is similar to pending breakpoints.) Pending tracepoints are not
downloaded to the target and not installed until they are resolved.
The resolution of pending tracepoints requires GDB support--when
debugging with the remote target, and GDB disconnects from the
remote stub (disconnected tracing), pending tracepoints can
not be resolved (and downloaded to the remote stub) while GDB is
disconnected.
Here are some examples of using the 'trace' command:
(gdb) trace foo.c:121 // a source file and line number
(gdb) trace +2 // 2 lines forward
(gdb) trace my_function // first source line of function
(gdb) trace *my_function // EXACT start address of function
(gdb) trace *0x2117c4 // an address
You can abbreviate 'trace' as 'tr'.
'trace LOCATION if COND'
Set a tracepoint with condition COND; evaluate the expression COND
each time the tracepoint is reached, and collect data only if the
value is nonzero--that is, if COND evaluates as true.
Tracepoint Conditions Tracepoint Conditions, for more information
on tracepoint conditions.
'ftrace LOCATION [ if COND ]'
The 'ftrace' command sets a fast tracepoint. For targets that
support them, fast tracepoints will use a more efficient but
possibly less general technique to trigger data collection, such as
a jump instruction instead of a trap, or some sort of hardware
support. It may not be possible to create a fast tracepoint at the
desired location, in which case the command will exit with an
explanatory message.
GDB handles arguments to 'ftrace' exactly as for 'trace'.
On 32-bit x86-architecture systems, fast tracepoints normally need
to be placed at an instruction that is 5 bytes or longer, but can
be placed at 4-byte instructions if the low 64K of memory of the
target program is available to install trampolines. Some Unix-type
systems, such as GNU/Linux, exclude low addresses from the
program's address space; but for instance with the Linux kernel it
is possible to let GDB use this area by doing a 'sysctl' command to
set the 'mmap_min_addr' kernel parameter, as in
sudo sysctl -w vm.mmap_min_addr=32768
which sets the low address to 32K, which leaves plenty of room for
trampolines. The minimum address should be set to a page boundary.
'strace LOCATION [ if COND ]'
The 'strace' command sets a static tracepoint. For targets that
support it, setting a static tracepoint probes a static
instrumentation point, or marker, found at LOCATION. It may not be
possible to set a static tracepoint at the desired location, in
which case the command will exit with an explanatory message.
GDB handles arguments to 'strace' exactly as for 'trace', with the
addition that the user can also specify '-m MARKER' as LOCATION.
This probes the marker identified by the MARKER string identifier.
This identifier depends on the static tracepoint backend library
your program is using. You can find all the marker identifiers in
the 'ID' field of the 'info static-tracepoint-markers' command
output. Listing Static Tracepoint Markers Listing Static
Tracepoint Markers. For example, in the following small program
using the UST tracing engine:
main ()
{
trace_mark(ust, bar33, "str %s", "FOOBAZ");
}
the marker id is composed of joining the first two arguments to the
'trace_mark' call with a slash, which translates to:
(gdb) info static-tracepoint-markers
Cnt Enb ID Address What
1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22
Data: "str %s"
[etc...]
so you may probe the marker above with:
(gdb) strace -m ust/bar33
Static tracepoints accept an extra collect action -- 'collect
$_sdata'. This collects arbitrary user data passed in the probe
point call to the tracing library. In the UST example above,
you'll see that the third argument to 'trace_mark' is a printf-like
format string. The user data is then the result of running that
formating string against the following arguments. Note that 'info
static-tracepoint-markers' command output lists that format string
in the 'Data:' field.
You can inspect this data when analyzing the trace buffer, by
printing the $_sdata variable like any other variable available to
GDB. Tracepoint Action Lists Tracepoint Actions.
The convenience variable '$tpnum' records the tracepoint number of
the most recently set tracepoint.
'delete tracepoint [NUM]'
Permanently delete one or more tracepoints. With no argument, the
default is to delete all tracepoints. Note that the regular
'delete' command can remove tracepoints also.
Examples:
(gdb) delete trace 1 2 3 // remove three tracepoints
(gdb) delete trace // remove all tracepoints
You can abbreviate this command as 'del tr'.