|Debugging with GDB|
Here we describe the packets gdb uses to implement tracepoints (see Tracepoints).
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:
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.)
start is the offset of the bytes within the overall source string, while slen is the total length of the source string. This is intended for handling source strings that are longer than will fit in a single packet.
The available string types are ‘at’ for the location, ‘cond’ for the conditional, and ‘cmd’ for an action command. gdb sends a separate packet for each command in the action list, in the same order in which the commands are stored in the list.
The target does not need to do anything with source strings except report them back as part of the replies to the ‘qTfP’/‘qTsP’ query packets.
Although this packet is optional, and gdb will only send it
if the target replies with ‘TracepointSource’ See General Query Packets, it makes both disconnected tracing and trace files
much easier to use. Otherwise the user must be careful that the
tracepoints in effect while looking at trace frames are identical to
the ones in effect during the trace run; even a small discrepancy
could cause ‘tdump’ not to work, or a particular trace frame not
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:
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.
The reply has the form:
1if the trace is presently running, or
0if not. It is followed by semicolon-separated optional fields that an agent may use to report additional status.
If the trace is not running, the agent may report any of several explanations as one of the optional fields:
Additional optional fields supply statistical and other information. Although not required, they are extremely useful for users monitoring the progress of a trace run. If a trace has stopped, and these numbers are reported, they must reflect the state of the just-stopped trace.
1means that the trace buffer is circular and old trace frames will be discarded if necessary to make room,
0means that the trace buffer is linear and may fill up.
1means that tracing will continue after gdb disconnects,
0means that the trace run will stop.
while-steppingsteps are not counted as separate hits, but the steps' space consumption is added into the usage number.
qTfPto get the first piece of data, and multiple
qTsPto get additional pieces. Replies to these packets generally take the form of the
QTDPpackets that define tracepoints. (FIXME add detailed syntax)
qTfVto get the first vari of data, and multiple
qTsVto get additional variables. Replies to these packets follow the syntax of the
QTDVpackets that define trace state variables.
qTfSTMto get the first piece of data, and multiple
qTsSTMto get additional pieces. Replies to these packets take the following form:
The address is encoded in hex; id and extra are strings encoded in hex.
In response to each query, the target will reply with a list of one or
more markers, separated by commas. gdb will respond to each
reply with a request for more markers (using the ‘qs’ form of the
query), until the target responds with ‘l’ (lower-case ell, for
qTsSTMpackets that list static tracepoint markers.
lindicates that no bytes are available.
-1tells the target to use whatever size it prefers.
tstop, the text fields are arbitrary strings, hex-encoded.
When installing fast tracepoints in memory, the target may need to relocate the instruction currently at the tracepoint address to a different address in memory. For most instructions, a simple copy is enough, but, for example, call instructions that implicitly push the return address on the stack, and relative branches or other PC-relative instructions require offset adjustment, so that the effect of executing the instruction at a different address is the same as if it had executed in the original location.
In response to several of the tracepoint packets, the target may also respond with a number of intermediate ‘qRelocInsn’ request packets before the final result packet, to have gdb handle this relocation operation. If a packet supports this mechanism, its documentation will explicitly say so. See for example the above descriptions for the ‘QTStart’ and ‘QTDP’ packets. The format of the request is: