GDB Tracepoint

1 Introduction

 

---

In some applications, it is not feasible for the debugger to interrupt the program's execution long enough for the developer to learn anything helpful about its behavior. If the program's correctness depends on its real-time behavior, delays introduced by a debugger might cause the program to change its behavior drastically, or perhaps fail, even when the code itself is correct. It is useful to be able to observe the program's behavior without interrupting it.

Using  gdb 's  trace   and  collect   commands, you can specify locations in the program, called  tracepoints , and arbitrary expressions to evaluate when those tracepoints are reached. Later, using the  tfind   command, you can examine the values those expressions had when the program hit the tracepoints. The expressions may also denote objects in memory—structures or arrays, for example—whose values  gdb   should record; while visiting a particular tracepoint, you may inspect those objects as if they were in memory at that moment. However, because  gdb   records these values without interacting with you, it can do so quickly and unobtrusively, hopefully not disturbing the program's behavior.

Before running such a  trace experiment , an arbitrary number of tracepoints can be set. A tracepoint is actually a special type of breakpoint (see  Set Breaks ), so you can manipulate it using standard breakpoint commands . For instance, as with breakpoints, tracepoint numbers are successive integers starting from one, and many of the commands associated with tracepoints take the tracepoint number as their argument, to identify which tracepoint to work on.

For each tracepoint, you can specify, in advance, some arbitrary set of data that you want the target to collect in the trace buffer when it hits that tracepoint . The collected data can include registers, local variables, or global data. Later, you can use  gdb   commands to examine the values these data had at the time the tracepoint was hit .

Regular and fast tracepoints are dynamic tracing facilities , meaning that they can be used to insert tracepoints at (almost) any location in the target. Some targets may also support controlling static tracepoints from gdb . With static tracing, a set of instrumentation points, also known as markers , are embedded in the target program, and can be activated or deactivated by name or address. These are usually placed at locations which facilitate investigating what the target is actually doing. gdb 's support for static tracing includes being able to list instrumentation points, and attach them with gdb defined high level tracepoints that expose the whole range of convenience of gdb 's tracepoints support. Namelly, support for collecting registers values and values of global or local (to the instrumentation point) variables; tracepoint conditions and trace state variables. The act of installing a gdb static tracepoint on an instrumentation point, or marker, is referred to as probing a static tracepoint marker.

2 Set Tracepoints

---

create and delete tracepoints

http://sourceware.org/gdb/current/onlinedocs/gdb/Create-and-Delete-Tracepoints.html#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 doesn'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.

 

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

ftrace location [ if cond ]
strace location [ if cond ]
delete tracepoint [ num ]( abbreviate this command as del tr )

Enable and Disable Tracepoints

disable tracepoint [ num ] enable tracepoint [ num ]

Tracepoint Passcounts

passcount [ n [ num ]]

Set the passcount of a tracepoint. The passcount is a way to automatically stop a trace experiment. If a tracepoint's passcount is n , then the trace experiment will be automatically stopped on the n 'th time that tracepoint is hit. If the tracepoint number num is not specified, the passcount command sets the passcount of the most recently defined tracepoint. If no passcount is given, the trace experiment will run until stopped explicitly by the user.

Tracepoint Action Lists

http://sourceware.org/gdb/current/onlinedocs/gdb/Tracepoint-Actions.html#Tracepoint-Actions

actions [ num ]

This command will prompt for a list of actions to be taken when the tracepoint is hit. If the tracepoint number num is not specified, this command sets the actions for the one that was most recently defined (so that you can define a tracepoint and then say actions without bothering about its number). You specify the actions themselves on the following lines, one action at a time, and terminate the actions list with a line containing just end . So far, the only defined actions are collect , teval , and while-stepping .

To remove all actions from a tracepoint, type ` actions num ' and follow it immediately with ` end '.

collect expr1 , expr2 , ...

Collect values of the given expressions when the tracepoint is hit.

teval expr1 , expr2 , ...

Evaluate the given expressions when the tracepoint is hit.

while-stepping n

Perform n single-step instruction traces after the tracepoint, collecting new data after each step.

set default-collect expr1 , expr2 , ...

This variable is a list of expressions to collect at each tracepoint hit.

show default-collect

Show the list of expressions that are collected by default at each tracepoint hit.

Listing Tracepoints

http://sourceware.org/gdb/current/onlinedocs/gdb/Listing-Tracepoints.html#Listing-Tracepoints
info tracepoints [ num ]

Display information about the tracepoint num . If you don't specify a tracepoint number, displays information about all the tracepoints defined so far. This command can be abbreviated info tp .

Listing Static Tracepoint Markers

info static-tracepoint-markers

Display information about all static tracepoint markers defined in the program.

Starting and Stopping Trace Experiments

http://sourceware.org/gdb/current/onlinedocs/gdb/Starting-and-Stopping-Trace-Experiments.html#Starting-and-Stopping-Trace-Experiments

tstart

This command takes no arguments. It starts the trace experiment, and begins collecting data. This has the side effect of discarding all the data collected in the trace buffer during the previous trace experiment.

tstop

This command takes no arguments. It ends the trace experiment, and stops collecting data. Note : a trace experiment and data collection may stop automatically if any tracepoint's passcount is reached (see Tracepoint Passcounts ), or if the trace buffer becomes full.

tstatus

This command displays the status of the current trace data collection.

Here is an example of the commands we described so far:

     (gdb) trace gdb_c_test


     (gdb) actions


     Enter actions for tracepoint #1, one per line.

     > collect $regs,$locals,$args

     > while-stepping 11

       > collect $regs

       > end

     > end

     (gdb) tstart


     	[time passes ...]

     (gdb) tstop

You can choose to continue running the trace experiment even if gdb disconnects from the target, voluntarily or involuntarily. For commands such as detach , the debugger will ask what you want to do with the trace. But for unexpected terminations (gdb crash, network outage), it would be unfortunate to lose hard-won trace data, so the variable disconnected-tracing lets you decide whether the trace should continue running without gdb .

set disconnected-tracing on set disconnected-tracing off

Choose whether a tracing run should continue to run if gdb has disconnected from the target. Note that detach or quit will ask you directly what to do about a running trace no matter what this variable's setting, so the variable is mainly useful for handling unexpected situations, such as loss of the network.

show disconnected-tracing

Show the current choice for disconnected tracing.

When you reconnect to the target, the trace experiment may or may not still be running; it might have filled the trace buffer in the meantime, or stopped for one of the other reasons. If it is running, it will continue after reconnection.

set circular-trace-buffer on set circular-trace-buffer off

Choose whether a tracing run should use a linear or circular buffer for trace data. A linear buffer will not lose any trace data, but may fill up prematurely, while a circular buffer will discard old trace data, but it will have always room for the latest tracepoint hits.

show circular-trace-buffer

Show the current choice for the trace buffer. Note that this may not match the agent's current buffer handling, nor is it guaranteed to match the setting that might have been in effect during a past run, for instance if you are looking at frames from a trace file.

3 Analyze Collected Data

---

After the tracepoint experiment ends, you use gdb commands for examining the trace data. The basic idea is that each tracepoint collects a trace snapshot every time it is hit and another snapshot every time it single-steps. All these snapshots are consecutively numbered from zero and go into a buffer, and you can examine them later. The way you examine them is to focus on a specific trace snapshot. When the remote stub is focused on a trace snapshot, it will respond to all gdb requests for memory and registers by reading from the buffer which belongs to that snapshot, rather than from real memory or registers of the program being debugged. This means that all gdb commands (print , info registers , 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.

• tfind : How to select a trace snapshot
• tdump : How to display all data for a snapshot
• save tracepoints : How to save tracepoints for a future run

  [1] http://sourceware.org/gdb/current/onlinedocs/gdb/Tracepoints.html#Tracepoints

 

4 Convenience Variables for Tracepoints

---

(int) $trace_frame

The current trace snapshot (a.k.a. frame ) number, or -1 if no snapshot is selected.

 

(int) $tracepoint

The tracepoint for the current trace snapshot.

 

(int) $trace_line

The line number for the current trace snapshot.

 

(char []) $trace_file

The source file for the current trace snapshot.

 

(char []) $trace_func

The name of the function containing $tracepoint .

Note: $trace_file is not suitable for use in printf , use output instead.

Here's a simple example of using these convenience variables for stepping through all the trace snapshots and printing some of their data. Note that these are not the same as trace state variables, which are managed by the target.

     (gdb) tfind start


     (gdb) while $trace_frame != -1


     > output $trace_file

     > printf ", line %d (tracepoint #%d)/n", $trace_line, $tracepoint

     > tfind

     > end

5 Using Trace Files

 

---

 

In some situations, the target running a trace experiment may no longer be available; perhaps it crashed, or the hardware was needed for a different activity. To handle these cases, you can arrange to dump the trace data into a file, and later use that file as a source of trace data, via the target tfile command.

tsave [ -r ] filename

Save the trace data to filename . By default, this command assumes that filename refers to the host filesystem, so if necessary gdb will copy raw trace data up from the target and then save it. If the target supports it, you can also supply the optional argument -r (“remote”) to direct the target to save the data directly into filename in its own filesystem, which may be more efficient if the trace buffer is very large. (Note, however, that target tfile can only read from files accessible to the host.)

target tfile filename

Use the file named filename as a source of trace data. Commands that examine data work as they do with a live target, but it is not possible to run any new trace experiments. tstatus will report the state of the trace run at the moment the data was saved, as well as the current trace frame you are examining. filename must be on a filesystem accessible to the host.

 

 

 

Refer:

[1] http://sourceware.org/gdb/current/onlinedocs/gdb/Tracepoints.html#Tracepoints