13.1.1 Create and Delete Tracepoints

trace location

The trace command is very similar to the break command.
Its argument location can be a source line, a function name, or
an address in the target program. See 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 (see 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 (see disconnected tracing), pending tracepoints can not be resolved (and downloaded to
the remote stub) while gdb is disconnected.

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.
See 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.
See 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:

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. See Tracepoint Action Lists.

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.