Next: , Previous: Architecture-Specific Protocol Details, Up: Remote Protocol


D.6 Tracepoint Packets

Here we describe the packets gdb uses to implement tracepoints (see Tracepoints).

QTDP:n:addr:ena:step:pass[:Fflen][:Xlen,bytes][-]
Create a new tracepoint, number n, at addr. If ena is ‘E’, then the tracepoint is enabled; if it is ‘D’, then the tracepoint is disabled. step is the tracepoint's step count, and pass is its pass count. If an ‘F’ is present, then the tracepoint is to be a fast tracepoint, and the flen is the number of bytes that the target should copy elsewhere to make room for the tracepoint. If an ‘X’ is present, it introduces a tracepoint condition, which consists of a hexadecimal length, followed by a comma and hex-encoded bytes, in a manner similar to action encodings as described below. If the trailing ‘-’ is present, further ‘QTDP’ packets will follow to specify this tracepoint's actions.

Replies:

OK
The packet was understood and carried out.
The packet was not recognized.

QTDP:-n:addr:[S]action...[-]
Define actions to be taken when a tracepoint is hit. n and addr must be the same as in the initial ‘QTDP’ packet for this tracepoint. This packet may only be sent immediately after another ‘QTDP’ packet that ended with a ‘-’. If the trailing ‘-’ is present, further ‘QTDP’ packets will follow, specifying more actions for this tracepoint.

In the series of action packets for a given tracepoint, at most one can have an ‘S’ before its first action. If such a packet is sent, it and the following packets define “while-stepping” actions. Any prior packets define ordinary actions — that is, those taken when the tracepoint is first hit. If no action packet has an ‘S’, then all the packets in the series specify ordinary tracepoint actions.

The ‘action...’ portion of the packet is a series of actions, concatenated without separators. Each action has one of the following forms:

R mask
Collect the registers whose bits are set in mask. mask is a hexadecimal number whose i'th bit is set if register number i should be collected. (The least significant bit is numbered zero.) Note that mask may be any number of digits long; it may not fit in a 32-bit word.
M basereg,offset,len
Collect len bytes of memory starting at the address in register number basereg, plus offset. If basereg is ‘-1’, then the range has a fixed address: offset is the address of the lowest byte to collect. The basereg, offset, and len parameters are all unsigned hexadecimal values (the ‘-1’ value for basereg is a special case).
X len,expr
Evaluate expr, whose length is len, and collect memory as it directs. expr is an agent expression, as described in Agent Expressions. Each byte of the expression is encoded as a two-digit hex number in the packet; len is the number of bytes in the expression (and thus one-half the number of hex digits in the packet).

Any number of actions may be packed together in a single ‘QTDP’ packet, as long as the packet does not exceed the maximum packet length (400 bytes, for many stubs). There may be only one ‘R’ action per tracepoint, and it must precede any ‘M’ or ‘X’ actions. Any registers referred to by ‘M’ and ‘X’ actions must be collected by a preceding ‘R’ action. (The “while-stepping” actions are treated as if they were attached to a separate tracepoint, as far as these restrictions are concerned.)

Replies:

OK
The packet was understood and carried out.
The packet was not recognized.

QTDV:n:value
Create a new trace state variable, number n, with an initial value of value, which is a 64-bit signed integer. Both n and value are encoded as hexadecimal values. gdb has the option of not using this packet for initial values of zero; the target should simply create the trace state variables as they are mentioned in expressions.
QTFrame:n
Select the n'th tracepoint frame from the buffer, and use the register and memory contents recorded there to answer subsequent request packets from gdb.

A successful reply from the stub indicates that the stub has found the requested frame. The response is a series of parts, concatenated without separators, describing the frame we selected. Each part has one of the following forms:

F f
The selected frame is number n in the trace frame buffer; f is a hexadecimal number. If f is ‘-1’, then there was no frame matching the criteria in the request packet.
T t
The selected trace frame records a hit of tracepoint number t; t is a hexadecimal number.

QTFrame:pc:addr
Like ‘QTFrame:n’, but select the first tracepoint frame after the currently selected frame whose PC is addr; addr is a hexadecimal number.
QTFrame:tdp:t
Like ‘QTFrame:n’, but select the first tracepoint frame after the currently selected frame that is a hit of tracepoint t; t is a hexadecimal number.
QTFrame:range:start:end
Like ‘QTFrame:n’, but select the first tracepoint frame after the currently selected frame whose PC is between start (inclusive) and end (inclusive); start and end are hexadecimal numbers.
QTFrame:outside:start:end
Like ‘QTFrame:range:start:end’, but select the first frame outside the given range of addresses (exclusive).
QTStart
Begin the tracepoint experiment. Begin collecting data from tracepoint hits in the trace frame buffer.
QTStop
End the tracepoint experiment. Stop collecting trace frames.
QTinit
Clear the table of tracepoints, and empty the trace frame buffer.
QTro:start1,end1:start2,end2:...
Establish the given ranges of memory as “transparent”. The stub will answer requests for these ranges from memory's current contents, if they were not collected as part of the tracepoint hit.

gdb uses this to mark read-only regions of memory, like those containing program code. Since these areas never change, they should still have the same contents they did when the tracepoint was hit, so there's no reason for the stub to refuse to provide their contents.

QTDisconnected:value
Set the choice to what to do with the tracing run when gdb disconnects from the target. A value of 1 directs the target to continue the tracing run, while 0 tells the target to stop tracing if gdb is no longer in the picture.
qTStatus
Ask the stub if there is a trace experiment running right now.

Replies:

T0
There is no trace experiment running.
T1
There is a trace experiment running.

qTV:var
Ask the stub for the value of the trace state variable number var.

Replies:

Vvalue
The value of the variable is value. This will be the current value of the variable if the user is examining a running target, or a saved value if the variable was collected in the trace frame that the user is looking at. Note that multiple requests may result in different reply values, such as when requesting values while the program is running.
U
The value of the variable is unknown. This would occur, for example, if the user is examining a trace frame in which the requested variable was not collected.

qTfP
qTsP
These packets request data about tracepoints that are being used by the target. gdb sends qTfP to get the first piece of data, and multiple qTsP to get additional pieces. Replies to these packets generally take the form of the QTDP packets that define tracepoints. (FIXME add detailed syntax)
qTfV
qTsV
These packets request data about trace state variables that are on the target. gdb sends qTfV to get the first vari of data, and multiple qTsV to get additional variables. Replies to these packets follow the syntax of the QTDV packets that define trace state variables.
QTSave:filename
This packet directs the target to save trace data to the file name filename in the target's filesystem. filename is encoded as a hex string; the interpretation of the file name (relative vs absolute, wild cards, etc) is up to the target.
qTBuffer:offset,len
Return up to len bytes of the current contents of trace buffer, starting at offset. The trace buffer is treated as if it were a contiguous collection of traceframes, as per the trace file format. The reply consists as many hex-encoded bytes as the target can deliver in a packet; it is not an error to return fewer than were asked for. A reply consisting of just l indicates that no bytes are available.