27.15 gdb/mi Tracepoint Commands

The commands defined in this section implement MI support for tracepoints. For detailed introduction, see Tracepoints.

The -trace-find Command

Synopsis
      -trace-find mode [parameters...]

Find a trace frame using criteria defined by mode and parameters. The following table lists permissible modes and their parameters. For details of operation, see tfind.

none
No parameters are required. Stops examining trace frames.
frame-number
An integer is required as parameter. Selects tracepoint frame with that index.
tracepoint-number
An integer is required as parameter. Finds next trace frame that corresponds to tracepoint with the specified number.
pc
An address is required as parameter. Finds next trace frame that corresponds to any tracepoint at the specified address.
pc-inside-range
Two addresses are required as parameters. Finds next trace frame that corresponds to a tracepoint at an address inside the specified range. Both bounds are considered to be inside the range.
pc-outside-range
Two addresses are required as parameters. Finds next trace frame that corresponds to a tracepoint at an address outside the specified range. Both bounds are considered to be inside the range.
line
Line specification is required as parameter. See Specify Location. Finds next trace frame that corresponds to a tracepoint at the specified location.

If none was passed as mode, the response does not have fields. Otherwise, the response may have the following fields:

found
This field has either 0 or 1 as the value, depending on whether a matching tracepoint was found.
traceframe
The index of the found traceframe. This field is present iff the found field has value of 1.
tracepoint
The index of the found tracepoint. This field is present iff the found field has value of 1.
frame
The information about the frame corresponding to the found trace frame. This field is present only if a trace frame was found. See GDB/MI Frame Information, for description of this field.
gdb Command

The corresponding gdb command is tfind.

-trace-define-variable

Synopsis
      -trace-define-variable name [ value ]

Create trace variable name if it does not exist. If value is specified, sets the initial value of the specified trace variable to that value. Note that the name should start with the $ character.

gdb Command

The corresponding gdb command is tvariable.

-trace-list-variables

Synopsis
      -trace-list-variables

Return a table of all defined trace variables. Each element of the table has the following fields:

name
The name of the trace variable. This field is always present.
initial
The initial value. This is a 64-bit signed integer. This field is always present.
current
The value the trace variable has at the moment. This is a 64-bit signed integer. This field is absent iff current value is not defined, for example if the trace was never run, or is presently running.
gdb Command

The corresponding gdb command is tvariables.

Example
     (gdb)
     -trace-list-variables
     ^done,trace-variables={nr_rows="1",nr_cols="3",
     hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"},
          {width="11",alignment="-1",col_name="initial",colhdr="Initial"},
          {width="11",alignment="-1",col_name="current",colhdr="Current"}],
     body=[variable={name="$trace_timestamp",initial="0"}
           variable={name="$foo",initial="10",current="15"}]}
     (gdb)

-trace-save

Synopsis
      -trace-save [-r ] filename

Saves the collected trace data to filename. Without the -r option, the data is downloaded from the target and saved in a local file. With the -r option the target is asked to perform the save.

gdb Command

The corresponding gdb command is tsave.

-trace-start

Synopsis
      -trace-start

Starts a tracing experiments. The result of this command does not have any fields.

gdb Command

The corresponding gdb command is tstart.

-trace-status

Synopsis
      -trace-status

Obtains the status of a tracing experiment. The result may include the following fields:

supported
May have a value of either 0, when no tracing operations are supported, 1, when all tracing operations are supported, or file when examining trace file. In the latter case, examining of trace frame is possible but new tracing experiement cannot be started. This field is always present.
running
May have a value of either 0 or 1 depending on whether tracing experiement is in progress on target. This field is present if supported field is not 0.
stop-reason
Report the reason why the tracing was stopped last time. This field may be absent iff tracing was never stopped on target yet. The value of request means the tracing was stopped as result of the -trace-stop command. The value of overflow means the tracing buffer is full. The value of disconnection means tracing was automatically stopped when gdb has disconnected. The value of passcount means tracing was stopped when a tracepoint was passed a maximal number of times for that tracepoint. This field is present if supported field is not 0.
stopping-tracepoint
The number of tracepoint whose passcount as exceeded. This field is present iff the stop-reason field has the value of passcount.
frames
frames-created
The frames field is a count of the total number of trace frames in the trace buffer, while frames-created is the total created during the run, including ones that were discarded, such as when a circular trace buffer filled up. Both fields are optional.
buffer-size
buffer-free
These fields tell the current size of the tracing buffer and the remaining space. These fields are optional.
circular
The value of the circular trace buffer flag. 1 means that the trace buffer is circular and old trace frames will be discarded if necessary to make room, 0 means that the trace buffer is linear and may fill up.
disconnected
The value of the disconnected tracing flag. 1 means that tracing will continue after gdb disconnects, 0 means that the trace run will stop.
gdb Command

The corresponding gdb command is tstatus.

-trace-stop

Synopsis
      -trace-stop

Stops a tracing experiment. The result of this command has the same fields as -trace-status, except that the supported and running fields are not output.

gdb Command

The corresponding gdb command is tstop.