D.6 Tracepoint Packets

Here we describe the packets No value for GDBN uses to implement tracepoints (see section Tracepoints).

‘QTDP:n:addr:ena:step:pass[-]’

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 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 The GDB Agent Expression Mechanism. 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.

‘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 No value for GDBN.

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 (exclusive); 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.

‘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.

No value for GDBN 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.

‘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.