| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There may be occasions when you need to know something about the protocol--for example, if there is only one serial port to your target machine, you might want your program to do something special if it recognizes a packet meant for GDB.
In the examples below, `->' and `<-' are used to indicate transmitted and received data, respectively.
All GDB commands and responses (other than acknowledgments and notifications, see E.9 Notification Packets) are sent as a packet. A packet is introduced with the character `$', the actual packet-data, and the terminating character `#' followed by a two-digit checksum:
|
The two-digit checksum is computed as the modulo 256 sum of all characters between the leading `$' and the trailing `#' (an eight bit unsigned checksum).
Implementors should note that prior to GDB 5.0 the protocol specification also included an optional two-digit sequence-id:
|
That sequence-id was appended to the acknowledgment. GDB has never output sequence-ids. Stubs that handle packets added since GDB 5.0 must not accept sequence-id.
When either the host or the target machine receives a packet, the first response expected is an acknowledgment: either `+' (to indicate the package was received correctly) or `-' (to request retransmission):
-> |
The `+'/`-' acknowledgments can be disabled once a connection is established. See section E.11 Packet Acknowledgment, for details.
The host (GDB) sends commands, and the target (the debugging stub incorporated in your program) sends a response. In the case of step and continue commands, the response is only sent when the operation has completed, and the target has again stopped all threads in all attached processes. This is the default all-stop mode behavior, but the remote protocol also supports GDB's non-stop execution mode; see E.10 Remote Protocol Support for Non-Stop Mode, for details.
packet-data consists of a sequence of characters with the exception of `#' and `$' (see `X' packet for additional exceptions).
Fields within the packet should be separated using `,' `;' or `:'. Except where otherwise noted all numbers are represented in HEX with leading zeros suppressed.
Implementors should note that prior to GDB 5.0, the character `:' could not appear as the third character in a packet (as it would potentially conflict with the sequence-id).
Binary data in most packets is encoded either as two hexadecimal digits per byte of binary data. This allowed the traditional remote protocol to work over connections which were only seven-bit clean. Some packets designed more recently assume an eight-bit clean connection, and use a more efficient encoding to send and receive binary data.
The binary data representation uses 7d (ASCII `}')
as an escape character. Any escaped byte is transmitted as the escape
character followed by the original character XORed with 0x20.
For example, the byte 0x7d would be transmitted as the two
bytes 0x7d 0x5d. The bytes 0x23 (ASCII `#'),
0x24 (ASCII `$'), and 0x7d (ASCII
`}') must always be escaped. Responses sent by the stub
must also escape 0x2a (ASCII `*'), so that it
is not interpreted as the start of a run-length encoded sequence
(described next).
Response data can be run-length encoded to save space.
Run-length encoding replaces runs of identical characters with one
instance of the repeated character, followed by a `*' and a
repeat count. The repeat count is itself sent encoded, to avoid
binary characters in data: a value of n is sent as
n+29. For a repeat count greater or equal to 3, this
produces a printable ASCII character, e.g. a space (ASCII
code 32) for a repeat count of 3. (This is because run-length
encoding starts to win for counts 3 or more.) Thus, for example,
`0* ' is a run-length encoding of "0000": the space character
after `*' means repeat the leading 0 32 - 29 =
3 more times.
The printable characters `#' and `$' or with a numeric value greater than 126 must not be used. Runs of six repeats (`#') or seven repeats (`$') can be expanded using a repeat count of only five (`"'). For example, `00000000' can be encoded as `0*"00'.
The error response returned for some packets includes a two character error number. That number is not well defined.
For any command not supported by the stub, an empty response (`$#00') should be returned. That way it is possible to extend the protocol. A newer GDB can tell if a packet is supported based on that response.
At a minimum, a stub is required to support the `g' and `G' commands for register access, and the `m' and `M' commands for memory access. Stubs that only control single-threaded targets can implement run control with the `c' (continue), and `s' (step) commands. Stubs that support multi-threading targets should support the `vCont' command. All other commands are optional.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following table provides a complete list of all currently defined commands and their corresponding response data. See section E.13 File-I/O Remote Protocol Extension, for details about the File I/O extension of the remote protocol.
Each packet's description has a template showing the packet's overall syntax, followed by an explanation of the packet's meaning. We include spaces in some of the templates for clarity; these are not part of the packet's syntax. No GDB packet uses spaces to separate its components. For example, a template like `foo bar baz' describes a packet beginning with the three ASCII bytes `foo', followed by a bar, followed directly by a baz. GDB does not transmit a space character between the `foo' and the bar, or between the bar and the baz.
Several packets and replies include a thread-id field to identify a thread. Normally these are positive numbers with a target-specific interpretation, formatted as big-endian hex strings. A thread-id can also be a literal `-1' to indicate all threads, or `0' to pick any thread.
In addition, the remote protocol supports a multiprocess feature in which the thread-id syntax is extended to optionally include both process and thread ID fields, as `ppid.tid'. The pid (process) and tid (thread) components each have the format described above: a positive number with target-specific interpretation formatted as a big-endian hex string, literal `-1' to indicate all processes or threads (respectively), or `0' to indicate an arbitrary process or thread. Specifying just a process, as `ppid', is equivalent to `ppid.-1'. It is an error to specify all processes but a specific thread, such as `p-1.tid'. Note that the `p' prefix is not used for those packets and replies explicitly documented to include a process ID, rather than a thread-id.
The multiprocess thread-id syntax extensions are only used if both GDB and the stub report support for the `multiprocess' feature using `qSupported'. See multiprocess extensions, for more information.
Note that all packet forms beginning with an upper- or lower-case letter, other than those described here, are reserved for future use.
Here are the packet descriptions.
Reply:
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
argv[] array passed into program. arglen
specifies the number of bytes in the hex encoded byte stream
arg. See gdbserver for more details.
Reply:
JTC: When does the transport layer state change? When it's received, or after the ACK is transmitted. In either case, there are problems if the command or the acknowledgment packet is dropped.
Stan: If people really wanted to add something like this, and get it working for the first time, they ought to modify ser-unix.c to send some kind of out-of-band message to a specially-setup stub and have the switch happen "in between" packets, so that from remote protocol's point of view, nothing actually happened.
Don't use this packet. Use the `Z' and `z' packets instead (see insert breakpoint or watchpoint packet).
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
This packet is deprecated for multi-threading support. See vCont packet.
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
This packet is deprecated for multi-threading support. See vCont packet.
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
Don't use this packet; instead, define a general set packet (see section E.4 General Query Packets).
detach command.
The second form, including a process ID, is used when multiprocess protocol extensions are enabled (see multiprocess extensions), to detach only a specific process. The pid is specified as a big-endian hex string.
Reply:
Reply:
DEPRECATED_REGISTER_RAW_SIZE and gdbarch_register_name. The
specification of several standard `g' packets is specified below.
When reading registers from a trace frame (see section Using the Collected Data), the stub may also return a string of literal `x''s in place of the register data digits, to indicate that the corresponding register has not been collected, thus its value is unavailable. For example, for an architecture with 4 registers of 4 bytes each, the following reply indicates to GDB that registers 0 and 2 have not been collected, while registers 1 and 3 have been collected, and both have zero value:
-> |
Reply:
Reply:
FIXME: There is no description of how to operate when a specific thread context has been selected (i.e. does 'k' kill only that thread?).
The stub need not use any particular size or alignment when gathering data from memory for the response; even if addr is word-aligned and length is a multiple of the word size, the stub is free to use byte accesses, or not. For this reason, this packet may not be suitable for accessing memory-mapped I/O devices.
Reply:
Reply:
Reply:
Reply:
Don't use this packet; use the `R' packet instead.
The `R' packet has no reply.
This packet is deprecated for multi-threading support. See vCont packet.
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
This packet is deprecated for multi-threading support. See vCont packet.
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
Reply:
This packet is only available in extended mode (see extended mode).
Reply:
Currently supported actions are:
The optional argument addr normally associated with the `c', `C', `s', and `S' packets is not supported in `vCont'.
The `t' action is only relevant in non-stop mode (see section E.10 Remote Protocol Support for Non-Stop Mode) and may be ignored by the stub otherwise. A stop reply should be generated for any affected thread not already stopped. When a thread is stopped by means of a `t' action, the corresponding stop reply should indicate that the thread has stopped with signal `0', regardless of whether the target uses some other signal as an implementation detail.
Reply: See section E.3 Stop Reply Packets, for the reply specifications.
Reply:
The stub must support `vCont' if it reports support for multiprocess extensions (see multiprocess extensions). Note that in this case `vCont' actions can be specified to apply to all threads in a process by using the `ppid.-1' form of the thread-id.
Reply:
Reply:
Reply:
This packet is only available in extended mode (see extended mode).
Reply:
In non-stop mode (see section E.10 Remote Protocol Support for Non-Stop Mode), acknowledge a previous stop reply and prompt for the stub to report another one.
Reply:
Reply:
Each breakpoint and watchpoint packet type is documented separately.
Implementation notes: A remote target shall return an empty string for an unrecognized breakpoint or watchpoint packet type. A remote target shall support either both or neither of a given `Ztype...' and `ztype...' packet pair. To avoid potential problems with duplicate packets, the operations should be implemented in an idempotent way.
A memory breakpoint is implemented by replacing the instruction at addr with a software breakpoint or trap instruction. The kind is target-specific and typically indicates the size of the breakpoint in bytes that should be inserted. E.g., the ARM and MIPS can insert either a 2 or 4 byte breakpoint. Some architectures have additional meanings for kind; see E.5 Architecture-Specific Protocol Details.
Implementation note: It is possible for a target to copy or move code that contains memory breakpoints (e.g., when implementing overlays). The behavior of this packet, in the presence of such a target, is not defined.
Reply:
A hardware breakpoint is implemented using a mechanism that is not dependant on being able to modify the target's memory. kind has the same meaning as in `Z0' packets.
Implementation note: A hardware breakpoint is not affected by code movement.
Reply:
Reply:
Reply:
Reply:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?' packets can receive any of the below as a reply. Except for `?' and `vStopped', that reply is only returned when the target halts. In the below the exact meaning of signal number is defined by the header `include/gdb/signals.h' in the GDB source code.
As in the description of request packets, we include spaces in the reply templates for clarity; these are not part of the reply packet's syntax. No GDB stop reply packet uses spaces to separate its components.
The currently defined stop reasons are:
The second form of the response, including the process ID of the exited process, can be used only when GDB has reported support for multiprocess protocol extensions; see multiprocess extensions. The pid is formatted as a big-endian hex string.
The second form of the response, including the process ID of the terminated process, can be used only when GDB has reported support for multiprocess protocol extensions; see multiprocess extensions. The pid is formatted as a big-endian hex string.
`parameter...' is a list of parameters as defined for this very system call.
The target replies with this packet when it expects GDB to call a host system call on behalf of the target. GDB replies with an appropriate `F' packet and keeps up waiting for the next reply packet from the target. The latest `C', `c', `S' or `s' action is expected to be continued. See section E.13 File-I/O Remote Protocol Extension, for more details.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Packets starting with `q' are general query packets; packets starting with `Q' are general set packets. General query and set packets are a semi-unified form for retrieving and sending information to and from the stub.
The initial letter of a query or set packet is followed by a name indicating what sort of thing the packet applies to. For example, GDB may use a `qSymbol' packet to exchange symbol definitions with the stub. These packet names follow some conventions:
The name of a query or set packet should be separated from any parameters by a `:'; the parameters themselves should be separated by `,' or `;'. Stubs must be careful to match the full packet name, and check for a separator or the end of the packet, in case two packet names share a common prefix. New packets should not begin with `qC', `qP', or `qL'(15).
Like the descriptions of the other packets, each description here has a template showing the packet's overall syntax, followed by an explanation of the packet's meaning. We include spaces in some of the templates for clarity; these are not part of the packet's syntax. No GDB packet uses spaces to separate its components.
Here are the currently defined query and set packets:
Reply:
0xffffffff is used to ensure leading zeros affect the CRC.
Note: This is the same CRC used in validating separate debug files (see section Debugging Information in Separate Files). However the algorithm is slightly different. When validating separate debug files, the CRC is computed taking the least significant bit of each byte first, and the final result is inverted to detect trailing zeros.
Reply:
This packet is only available in extended mode (see extended mode).
Reply:
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported). This should only be done on targets that actually support disabling address space randomization.
NOTE: This packet replaces the `qL' query (see below).
Reply:
In response to each query, the target will reply with a list of one or more thread IDs, separated by commas. GDB will respond to each reply with a request for more thread ids (using the `qs' form of the query), until the target responds with `l' (lower-case ell, for last). Refer to thread-id syntax, for the format of the thread-id fields.
thread-id is the thread ID associated with the thread for which to fetch the TLS address. See thread-id syntax.
offset is the (big endian, hex encoded) offset associated with the thread local variable. (This offset is obtained from the debug information associated with the variable.)
lm is the (big endian, hex encoded) OS/ABI-specific encoding of the load module associated with the thread local storage. For example, a GNU/Linux system will pass the link map address of the shared object associated with the thread local storage under consideration. Other operating environments may choose to represent the load module differently, so the precise meaning of this parameter will vary.
Reply:
thread-id is the thread ID associated with the thread.
Reply:
Don't use this packet; use the `qfThreadInfo' query instead (see above).
Reply:
remote.c:parse_threadlist_response().
Reply:
Text section by xxx from its original address.
Relocate the Data section by yyy from its original address.
If the object file format provides segment information (e.g. ELF
`PT_LOAD' program headers), GDB will relocate entire
segments by the supplied offsets.
Note: while a Bss offset may be included in the response,
GDB ignores this and instead applies the Data offset
to the Bss section.
Don't use this packet; use the `qThreadExtraInfo' query instead (see below).
Reply: see remote.c:remote_unpack_thread_info_response().
Reply:
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate `qSupported' response (see qSupported).
Use of this packet is controlled by the set non-stop command;
see section 5.5.2 Non-Stop Mode.
Reply:
Use of this packet is controlled by the set remote pass-signals
command (see section set remote pass-signals).
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate `qSupported' response (see qSupported).
Reply:
(Note that the qRcmd packet's name is separated from the
command by a `,', not a `:', contrary to the naming
conventions above. Please don't use this packet as a model for new
packets.)
Reply:
Reply:
Reply:
The allowed forms for each feature (either a gdbfeature in the `qSupported' packet, or a stubfeature in the response) are:
Whenever the stub receives a `qSupported' request, the supplied set of GDB features should override any previous request. This allows GDB to put the stub in a known state, even if the stub had previously been communicating with a different version of GDB.
The following values of gdbfeature (for the packet sent by GDB) are defined:
Stubs should ignore any unknown values for gdbfeature. Any GDB which sends a `qSupported' packet supports receiving packets of unlimited length (earlier versions of GDB may reject overly long responses). Additional values for gdbfeature may be defined in the future to let the stub take advantage of new features in GDB, e.g. incompatible improvements in the remote protocol--the `multiprocess' feature is an example of such a feature. The stub's reply should be independent of the gdbfeature entries sent by GDB; first GDB describes all the features it supports, and then the stub replies with all the features it supports.
Similarly, GDB will silently ignore unrecognized stub feature responses, as long as each response uses one of the standard forms.
Some features are flags. A stub which supports a flag feature should respond with a `+' form response. Other features require values, and the stub should respond with an `=' form response.
Each feature has a default value, which GDB will use if `qSupported' is not available or if the feature is not mentioned in the `qSupported' response. The default values are fixed; a stub is free to omit any feature responses that match the defaults.
Not all features can be probed, but for those which can, the probing mechanism is useful: in some cases, a stub's internal architecture may not allow the protocol layer to know some information about the underlying target in advance. This is especially common in stubs which may be configured for multiple targets.
These are the currently defined stub features and their properties:
| Feature Name | Value Required | Default | Probe Allowed |
| `PacketSize' | Yes | `-' | No |
| `qXfer:auxv:read' | No | `-' | Yes |
| `qXfer:features:read' | No | `-' | Yes |
| `qXfer:libraries:read' | No | `-' | Yes |
| `qXfer:memory-map:read' | No | `-' | Yes |
| `qXfer:sdata:read' | No | `-' | Yes |
| `qXfer:spu:read' | No | `-' | Yes |
| `qXfer:spu:write' | No | `-' | Yes |
| `qXfer:siginfo:read' | No | `-' | Yes |
| `qXfer:siginfo:write' | No | `-' | Yes |
| `qXfer:threads:read' | No | `-' | Yes |
| `qXfer:traceframe-info:read' | No | `-' | Yes |
| `qXfer:fdpic:read' | No | `-' | Yes |
| `QNonStop' | No | `-' | Yes |
| `QPassSignals' | No | `-' | Yes |
| `QStartNoAckMode' | No | `-' | Yes |
| `multiprocess' | No | `-' | No |
| `ConditionalTracepoints' | No | `-' | No |
| `ReverseContinue' | No | `-' | No |
| `ReverseStep' | No | `-' | No |
| `TracepointSource' | No | `-' | No |
| `QAllow' | No | `-' | No |
| `QDisableRandomization' | No | `-' | No |
| `EnableDisableTracepoints' | No | `-' | No |
| `tracenz' | No | `-' | No |
These are the currently defined stub features, in more detail:
Reply:
sym_name (hex encoded) is the name of a symbol whose value the target has previously requested.
sym_value (hex) is the value for symbol sym_name. If GDB cannot supply a value for sym_name, then this field will be empty.
Reply:
See section E.6 Tracepoint Packets.
info threads display. Some
examples of possible thread extra info strings are `Runnable', or
`Blocked on Mutex'.
Reply:
(Note that the qThreadExtraInfo packet's name is separated from
the command by a `,', not a `:', contrary to the naming
conventions above. Please don't use this packet as a model for new
packets.)
Here are the specific requests of this form defined so far. All `qXfer:object:read:...' requests use the same reply formats, listed below.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
Targets which maintain a list of libraries in the program's memory do not need to implement this packet; it is designed for platforms where the operating system manages the list of loaded libraries.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
This packet is optional for better performance on SVR4 targets. GDB uses memory read packets to read the SVR4 library list otherwise.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
Read contents of the extra collected static tracepoint marker information. The annex part of the generic `qXfer' packet must be empty (see qXfer read). See section Tracepoint Action Lists.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
spufs file on the target system. The
annex specifies which file to read; it must be of the form
`id/name', where id specifies an SPU context ID
in the target process, and name identifes the spufs file
in that context to be accessed.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
Return a description of the current traceframe's contents. See section E.18 Traceframe Info Format. The annex part of the generic `qXfer' packet must be empty (see qXfer read).
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
loadmaps on the target system. The
annex, either `exec' or `interp', specifies which loadmap,
executable loadmap or interpreter loadmap to read.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
Reply:
errno value.
Here are the specific requests of this form defined so far. All `qXfer:object:write:...' requests use the same reply formats, listed below.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
spufs file on the target system. The
annex specifies which file to write; it must be of the form
`id/name', where id specifies an SPU context ID
in the target process, and name identifes the spufs file
in that context to be accessed.
This packet is not probed by default; the remote stub must request it, by supplying an appropriate `qSupported' response (see qSupported).
Reply:
errno value.
This query is used, for example, to know whether the remote process
should be detached or killed when a GDB session is ended with
the quit command.
Reply:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes how the remote protocol is applied to specific target architectures. Also see G.4 Standard Target Features, for details of XML target descriptions for each architecture.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These breakpoint kinds are defined for the `Z0' and `Z1' packets.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following g/G packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
sixty-four bits. Those registers should be zero/sign extended (which?)
to fill the space allocated. Register bytes are transferred in target
byte order. The two nibbles within a register byte are transferred
most-significant - least-significant.
All registers are transferred as thirty-two bit quantities in the order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point registers; fsr; fir; fp.
All registers are transferred as sixty-four bit quantities (including
thirty-two bit registers such as sr). The ordering is the same
as MIPS32.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here we describe the packets GDB uses to implement tracepoints (see section 13. Tracepoints).
Replies:
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.)
Replies:
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 section E.4 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 be found.
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:
Replies:
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:
1 if the trace is presently
running, or 0 if 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.
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.
1 means that
tracing will continue after GDB disconnects, 0 means
that the trace run will stop.
Replies:
while-stepping steps are not counted as separate hits, but the
steps' space consumption is added into the usage number.
Replies:
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 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.
qTfSTM to get the
first piece of data, and multiple qTsSTM to get additional
pieces. Replies to these packets take the following form:
Reply:
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 last).
qTsSTM packets that list static
tracepoint markers.
l indicates that no bytes are
available.
user, notes, and tstop, the
text fields are arbitrary strings, hex-encoded.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
This requests GDB to copy instruction at address from to address to, possibly adjusted so that executing the instruction at to has the same effect as executing it at from. GDB writes the adjusted instruction to target memory starting at to.
Replies:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Host I/O packets allow GDB to perform I/O operations on the far side of a remote link. For example, Host I/O is used to upload and download files to a remote target with its own filesystem. Host I/O uses the same constant values and data structure layout as the target-initiated File-I/O protocol. However, the Host I/O packets are structured differently. The target-initiated protocol relies on target memory to store parameters and buffers. Host I/O requests are initiated by GDB, and the target's memory is not involved. See section E.13 File-I/O Remote Protocol Extension, for more details on the target-initiated protocol.
The Host I/O request packets all encode a single operation along with its arguments. They have this format:
The valid responses to Host I/O packets are:
These are the supported Host I/O operations:
The data read should be returned as a binary attachment on success. If zero bytes were read, the response should include an empty binary attachment (i.e. a trailing semicolon). The return value is the number of target bytes read; the binary attachment may be longer if some characters were escaped.
write system calls, there is no
separate count argument; the length of data in the
packet is used. `vFile:write' returns the number of bytes written,
which may be shorter than the length of data, or -1 if an
error occurred.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When a program on the remote target is running, GDB may
attempt to interrupt it by sending a `Ctrl-C', BREAK or
a BREAK followed by g,
control of which is specified via GDB's `interrupt-sequence'.
The precise meaning of BREAK is defined by the transport
mechanism and may, in fact, be undefined. GDB does not
currently define a BREAK mechanism for any of the network
interfaces except for TCP, in which case GDB sends the
telnet BREAK sequence.
`Ctrl-C', on the other hand, is defined and implemented for all
transport mechanisms. It is represented by sending the single byte
0x03 without any of the usual packet overhead described in
the Overview section (see section E.1 Overview). When a 0x03 byte is
transmitted as part of a packet, it is considered to be packet data
and does not represent an interrupt. E.g., an `X' packet
(see X packet), used for binary downloads, may include an unescaped
0x03 as part of its packet.
BREAK followed by g is also known as Magic SysRq g.
When Linux kernel receives this sequence from serial port,
it stops execution and connects to gdb.
Stubs are not required to recognize these interrupt mechanisms and the precise meaning associated with receipt of the interrupt is implementation defined. If the target supports debugging of multiple threads and/or processes, it should attempt to interrupt all currently-executing threads and processes. If the stub is successful at interrupting the running program, it should send one of the stop reply packets (see section E.3 Stop Reply Packets) to GDB as a result of successfully stopping the program in all-stop mode, and a stop reply for each stopped thread in non-stop mode. Interrupts received while the program is stopped are discarded.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The GDB remote serial protocol includes notifications, packets that require no acknowledgment. Both the GDB and the stub may send notifications (although the only notifications defined at present are sent by the stub). Notifications carry information without incurring the round-trip latency of an acknowledgment, and so are useful for low-impact communications where occasional packet loss is not a problem.
A notification packet has the form `% data # checksum', where data is the content of the notification, and checksum is a checksum of data, computed and formatted as for ordinary GDB packets. A notification's data never contains `$', `%' or `#' characters. Upon receiving a notification, the recipient sends no `+' or `-' to acknowledge the notification's receipt or to report its corruption.
Every notification's data begins with a name, which contains no colon characters, followed by a colon character.
Recipients should silently ignore corrupted notifications and notifications they do not understand. Recipients should restart timeout periods on receipt of a well-formed notification, whether or not they understand it.
Senders should only send the notifications described here when this protocol description specifies that they are permitted. In the future, we may extend the protocol to permit existing notifications in new contexts; this rule helps older senders avoid confusing newer recipients.
(Older versions of GDB ignore bytes received until they see the `$' byte that begins an ordinary packet, so new stubs may transmit notifications without fear of confusing older clients. There are no notifications defined for GDB to send at the moment, but we assume that most older stubs would ignore them, as well.)
The following notification packets from the stub to GDB are defined:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB's remote protocol supports non-stop debugging of multi-threaded programs, as described in 5.5.2 Non-Stop Mode. If the stub supports non-stop mode, it should report that to GDB by including `QNonStop+' in its `qSupported' response (see qSupported).
GDB typically sends a `QNonStop' packet only when establishing a new connection with the stub. Entering non-stop mode does not alter the state of any currently-running threads, but targets must stop all threads in any already-attached processes when entering all-stop mode. GDB uses the `?' packet as necessary to probe the target state after a mode change.
In non-stop mode, when an attached process encounters an event that would otherwise be reported with a stop reply, it uses the asynchronous notification mechanism (see section E.9 Notification Packets) to inform GDB. In contrast to all-stop mode, where all threads in all processes are stopped when a stop reply is sent, in non-stop mode only the thread reporting the stop event is stopped. That is, when reporting a `S' or `T' response to indicate completion of a step operation, hitting a breakpoint, or a fault, only the affected thread is stopped; any other still-running threads continue to run. When reporting a `W' or `X' response, all running threads belonging to other attached processes continue to run.
Only one stop reply notification at a time may be pending; if additional stop events occur before GDB has acknowledged the previous notification, they must be queued by the stub for later synchronous transmission in response to `vStopped' packets from GDB. Because the notification mechanism is unreliable, the stub is permitted to resend a stop reply notification if it believes GDB may not have received it. GDB ignores additional stop reply notifications received before it has finished processing a previous notification and the stub has completed sending any queued stop events.
Otherwise, GDB must be prepared to receive a stop reply notification at any time. Specifically, they may appear when GDB is not otherwise reading input from the stub, or when GDB is expecting to read a normal synchronous response or a `+'/`-' acknowledgment to a packet it has sent. Notification packets are distinct from any other communication from the stub so there is no ambiguity.
After receiving a stop reply notification, GDB shall acknowledge it by sending a `vStopped' packet (see vStopped packet) as a regular, synchronous request to the stub. Such acknowledgment is not required to happen immediately, as GDB is permitted to send other, unrelated packets to the stub first, which the stub should process normally.
Upon receiving a `vStopped' packet, if the stub has other queued stop events to report to GDB, it shall respond by sending a normal stop reply response. GDB shall then send another `vStopped' packet to solicit further responses; again, it is permitted to send other, unrelated packets as well which the stub should process normally.
If the stub receives a `vStopped' packet and there are no additional stop events to report, the stub shall return an `OK' response. At this point, if further stop events occur, the stub shall send a new stop reply notification, GDB shall accept the notification, and the process shall be repeated.
In non-stop mode, the target shall respond to the `?' packet as follows. First, any incomplete stop reply notification/`vStopped' sequence in progress is abandoned. The target must begin a new sequence reporting stop events for all stopped threads, whether or not it has previously reported those events to GDB. The first stop reply is sent as a synchronous reply to the `?' packet, and subsequent stop replies are sent as responses to `vStopped' packets using the mechanism described above. The target must not send asynchronous stop reply notifications until the sequence is complete. If all threads are running when the target receives the `?' packet, or if the target is not attached to any process, it shall respond `OK'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, when either the host or the target machine receives a packet, the first response expected is an acknowledgment: either `+' (to indicate the package was received correctly) or `-' (to request retransmission). This mechanism allows the GDB remote protocol to operate over unreliable transport mechanisms, such as a serial line.
In cases where the transport mechanism is itself reliable (such as a pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It may be desirable to disable them in that case to reduce communication overhead, or for other reasons. This can be accomplished by means of the `QStartNoAckMode' packet; see QStartNoAckMode.
When in no-acknowledgment mode, neither the stub nor GDB shall send or expect `+'/`-' protocol acknowledgments. The packet and response format still includes the normal checksum, as described in E.1 Overview, but the checksum may be ignored by the receiver.
If the stub supports `QStartNoAckMode' and prefers to operate in
no-acknowledgment mode, it should report that to GDB
by including `QStartNoAckMode+' in its response to `qSupported';
see qSupported.
If GDB also supports `QStartNoAckMode' and it has not been
disabled via the set remote noack-packet off command
(see section 20.4 Remote Configuration),
GDB may then send a `QStartNoAckMode' packet to the stub.
Only then may the stub actually turn off packet acknowledgments.
GDB sends a final `+' acknowledgment of the stub's `OK'
response, which can be safely ignored by the stub.
Note that set remote noack-packet command only affects negotiation
between GDB and the stub when subsequent connections are made;
it does not affect the protocol acknowledgment state for any current
connection.
Since `+'/`-' acknowledgments are enabled by default when a
new connection is established,
there is also no protocol request to re-enable the acknowledgments
for the current connection, once disabled.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Example sequence of a target being re-started. Notice how the restart does not get any direct output:
-> |
Example sequence of a target being stepped by a single instruction:
-> |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The File I/O remote protocol extension (short: File-I/O) allows the target to use the host's file system and console I/O to perform various system calls. System calls on the target system are translated into a remote protocol packet to the host system, which then performs the needed actions and returns a response packet to the target system. This simulates file system operations even on targets that lack file systems.
The protocol is defined to be independent of both the host and target systems. It uses its own internal representation of datatypes and values. Both GDB and the target's GDB stub are responsible for translating the system-dependent value representations into the internal protocol representations when data is transmitted.
The communication is synchronous. A system call is possible only when GDB is waiting for a response from the `C', `c', `S' or `s' packets. While GDB handles the request for a system call, the target is stopped to allow deterministic access to the target's memory. Therefore File-I/O is not interruptible by target signals. On the other hand, it is possible to interrupt File-I/O by a user interrupt (`Ctrl-C') within GDB.
The target's request to perform a host system call does not finish the latest `C', `c', `S' or `s' action. That means, after finishing the system call, the target returns to continuing the previous activity (continue, step). No additional continue or step request from GDB is required.
(gdb) continue <- target requests 'system call X' target is stopped, GDB executes system call -> GDB returns result ... target continues, GDB returns to wait for the target <- target hits breakpoint and sends a Txx packet |
The protocol only supports I/O on the console and to regular files on the host file system. Character or block special devices, pipes, named pipes, sockets or any other communication method on the host system are not supported by this protocol.
File I/O is not supported in non-stop mode.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The File-I/O protocol uses the F packet as the request as well
as reply packet. Since a File-I/O system call can only occur when
GDB is waiting for a response from the continuing or stepping target,
the File-I/O request is a reply that GDB has to expect as a result
of a previous `C', `c', `S' or `s' packet.
This F packet contains all information needed to allow GDB
to call the appropriate host system call:
At this point, GDB has to perform the following actions.
m packet request. This additional communication has to be
expected by the target implementation and is handled as any other m
packet.
M or X packet. This packet has to be expected
by the target implementation and is handled as any other M or X
packet.
Eventually GDB replies with another F packet which contains all
necessary information for the target to continue. This at least contains
errno, if has been changed by the system call.
After having done the needed type and value coercion, the target continues the latest continue or step action.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
F Request Packet
The F request packet has the following format:
call-id is the identifier to indicate the host system call to be called. This is just the name of the function.
parameter... are the parameters to the system call. Parameters are hexadecimal integer values, either the actual values in case of scalar datatypes, pointers to target buffer space in case of compound datatypes and unspecified memory areas, or pointer/length pairs in case of string parameters. These are appended to the call-id as a comma-delimited list. All values are transmitted in ASCII string representation, pointer/length pairs separated by a slash.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
F Reply Packet
The F reply packet has the following format:
retcode is the return code of the system call as hexadecimal value.
errno is the errno set by the call, in protocol-specific
representation.
This parameter can be omitted if the call was successful.
Ctrl-C flag is only sent if the user requested a break. In this case, errno must be sent as well, even if the call was successful. The Ctrl-C flag itself consists of the character `C':
F0,0,C |
or, if the call was interrupted before the host call has been performed:
F-1,4,C |
assuming 4 is the protocol-specific representation of EINTR.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If the `Ctrl-C' flag is set in the GDB
reply packet (see section E.13.4 The F Reply Packet),
the target should behave as if it had
gotten a break message. The meaning for the target is "system call
interrupted by SIGINT". Consequentially, the target should actually stop
(as with a break message) and return to GDB with a T02
packet.
It's important for the target to know in which state the system call was interrupted. There are two possible cases:
These two states can be distinguished by the target by the value of the
returned errno. If it's the protocol representation of EINTR, the system
call hasn't been performed. This is equivalent to the EINTR handling
on POSIX systems. In any other case, the target may presume that the
system call has been finished -- successfully or not -- and should behave
as if the break message arrived right after the system call.
GDB must behave reliably. If the system call has not been called
yet, GDB may send the F reply immediately, setting EINTR as
errno in the packet. If the system call on the host has been finished
before the user requests a break, the full action must be finished by
GDB. This requires sending M or X packets as necessary.
The F packet may only be sent when either nothing has happened
or the full action has been completed.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default and if not explicitly closed by the target system, the file
descriptors 0, 1 and 2 are connected to the GDB console. Output
on the GDB console is handled as any other file output operation
(write(1, ...) or write(2, ...)). Console input is handled
by GDB so that after the target read request from file descriptor
0 all following typing is buffered until either one of the following
conditions is met:
read
system call is treated as finished.
If the user has typed more characters than fit in the buffer given to
the read call, the trailing characters are buffered in GDB until
either another read(0, ...) is requested by the target, or debugging
is stopped at the user's request.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
open close read write lseek rename unlink stat/fstat gettimeofday isatty system
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int open(const char *pathname, int flags); int open(const char *pathname, int flags, mode_t mode); |
flags is the bitwise OR of the following values:
O_CREAT
O_EXCL
O_CREAT, if the file already exists it is
an error and open() fails.
O_TRUNC
O_RDWR or O_WRONLY is given) it will be
truncated to zero length.
O_APPEND
O_RDONLY
O_WRONLY
O_RDWR
Other bits are silently ignored.
mode is the bitwise OR of the following values:
S_IRUSR
S_IWUSR
S_IRGRP
S_IWGRP
S_IROTH
S_IWOTH
Other bits are silently ignored.
open returns the new file descriptor or -1 if an error
occurred.
EEXIST
O_CREAT and O_EXCL were used.
EISDIR
EACCES
ENAMETOOLONG
ENOENT
ENODEV
EROFS
EFAULT
ENOSPC
EMFILE
ENFILE
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int close(int fd); |
close returns zero on success, or -1 if an error occurred.
EBADF
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int read(int fd, void *buf, unsigned int count); |
EBADF
EFAULT
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int write(int fd, const void *buf, unsigned int count); |
EBADF
EFAULT
EFBIG
ENOSPC
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
long lseek (int fd, long offset, int flag); |
flag is one of:
SEEK_SET
SEEK_CUR
SEEK_END
EBADF
ESPIPE
EINVAL
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int rename(const char *oldpath, const char *newpath); |
EISDIR
EEXIST
EBUSY
EINVAL
ENOTDIR
EFAULT
EACCES
ENAMETOOLONG
oldpath or newpath was too long.
ENOENT
EROFS
ENOSPC
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int unlink(const char *pathname); |
EACCES
EPERM
EBUSY
EFAULT
ENAMETOOLONG
ENOENT
ENOTDIR
EROFS
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); |
EBADF
ENOENT
ENOTDIR
EFAULT
EACCES
ENAMETOOLONG
EINTR
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int gettimeofday(struct timeval *tv, void *tz); |
EINVAL
EFAULT
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int isatty(int fd); |
EINTR
Note that the isatty call is treated as a special case: it returns
1 to the target if the file descriptor is attached
to the GDB console, 0 otherwise. Implementing through system calls
would require implementing ioctl and would be more complex than
needed.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
int system(const char *command); |
system
return value by calling WEXITSTATUS(retval). In case
`/bin/sh' could not be executed, 127 is returned.
EINTR
GDB takes over the full task of calling the necessary host calls
to perform the system call. The return value of system on
the host is simplified before it's returned
to the target. Any termination signal information from the child process
is discarded, and the return value consists
entirely of the exit status of the called command.
Due to security concerns, the system call is by default refused
by GDB. The user has to allow this call explicitly with the
set remote system-call-allowed 1 command.
set remote system-call-allowed
system calls in the File I/O
protocol for the remote target. The default is zero (disabled).
show remote system-call-allowed
system calls are allowed in the File I/O
protocol.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Integral Datatypes Pointer Values Memory Transfer struct stat struct timeval
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The integral datatypes used in the system calls are int,
unsigned int, long, unsigned long,
mode_t, and time_t.
int, unsigned int, mode_t and time_t are
implemented as 32 bit values in this protocol.
long and unsigned long are implemented as 64 bit types.
See section Limits, for corresponding MIN and MAX values (similar to those in `limits.h') to allow range checking on host and target.
time_t datatypes are defined as seconds since the Epoch.
All integral datatypes transferred as part of a memory read or write of a
structured datatype e.g. a struct stat have to be given in big endian
byte order.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Pointers to target data are transmitted as they are. An exception is made for pointers to buffers for which the length isn't transmitted as part of the function call, namely strings. Strings are transmitted as a pointer/length pair, both as hex values, e.g.
|
which is a pointer to data of length 18 bytes at position 0x1aaf.
The length is defined as the full string length in bytes, including
the trailing null byte. For example, the string "hello world"
at address 0x123456 is transmitted as
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Structured data which is transferred using a memory read or write (for
example, a struct stat) is expected to be in a protocol-specific format
with all scalar multibyte datatypes being big endian. Translation to
this representation needs to be done both by the target before the F
packet is sent, and by GDB before
it transfers memory to the target. Transferred pointers to structured
data should point to the already-coerced data at any time.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The buffer of type struct stat used by the target and GDB
is defined as follows:
struct stat {
unsigned int st_dev; /* device */
unsigned int st_ino; /* inode */
mode_t st_mode; /* protection */
unsigned int st_nlink; /* number of hard links */
unsigned int st_uid; /* user ID of owner */
unsigned int st_gid; /* group ID of owner */
unsigned int st_rdev; /* device type (if inode device) */
unsigned long st_size; /* total size, in bytes */
unsigned long st_blksize; /* blocksize for filesystem I/O */
unsigned long st_blocks; /* number of blocks allocated */
time_t st_atime; /* time of last access */
time_t st_mtime; /* time of last modification */
time_t st_ctime; /* time of last change */
};
|
The integral datatypes conform to the definitions given in the appropriate section (see Integral Datatypes, for details) so this structure is of size 64 bytes.
The values of several fields have a restricted meaning and/or range of values.
st_dev
st_ino
st_mode
st_uid
st_gid
st_rdev
st_atime
st_mtime
st_ctime
The target gets a struct stat of the above representation and is
responsible for coercing it to the target representation before
continuing.
Note that due to size differences between the host, target, and protocol
representations of struct stat members, these members could eventually
get truncated on the target.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The buffer of type struct timeval used by the File-I/O protocol
is defined as follows:
struct timeval {
time_t tv_sec; /* second */
long tv_usec; /* microsecond */
};
|
The integral datatypes conform to the definitions given in the appropriate section (see Integral Datatypes, for details) so this structure is of size 8 bytes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following values are used for the constants inside of the protocol. GDB and target are responsible for translating these values before and after the call as needed.
Open Flags mode_t Values Errno Values Lseek Flags Limits
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in hexadecimal representation.
O_RDONLY 0x0 O_WRONLY 0x1 O_RDWR 0x2 O_APPEND 0x8 O_CREAT 0x200 O_TRUNC 0x400 O_EXCL 0x800 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in octal representation.
S_IFREG 0100000 S_IFDIR 040000 S_IRUSR 0400 S_IWUSR 0200 S_IXUSR 0100 S_IRGRP 040 S_IWGRP 020 S_IXGRP 010 S_IROTH 04 S_IWOTH 02 S_IXOTH 01 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in decimal representation.
EPERM 1 ENOENT 2 EINTR 4 EBADF 9 EACCES 13 EFAULT 14 EBUSY 16 EEXIST 17 ENODEV 19 ENOTDIR 20 EISDIR 21 EINVAL 22 ENFILE 23 EMFILE 24 EFBIG 27 ENOSPC 28 ESPIPE 29 EROFS 30 ENAMETOOLONG 91 EUNKNOWN 9999 |
EUNKNOWN is used as a fallback error value if a host system returns
any error value not in the list of supported error numbers.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
SEEK_SET 0 SEEK_CUR 1 SEEK_END 2 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in decimal representation.
INT_MIN -2147483648 INT_MAX 2147483647 UINT_MAX 4294967295 LONG_MIN -9223372036854775808 LONG_MAX 9223372036854775807 ULONG_MAX 18446744073709551615 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Example sequence of a write call, file descriptor 3, buffer is at target address 0x1234, 6 bytes should be written:
<- |
Example sequence of a read call, file descriptor 3, buffer is at target address 0x1234, 6 bytes should be read:
<- |
Example sequence of a read call, call fails on the host due to invalid
file descriptor (EBADF):
<- |
Example sequence of a read call, user presses Ctrl-c before syscall on host is called:
<- |
Example sequence of a read call, user presses Ctrl-c after syscall on host is called:
<- |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
On some platforms, a dynamic loader (e.g. `ld.so') runs in the same process as your application to manage libraries. In this case, GDB can use the loader's symbol table and normal memory operations to maintain a list of shared libraries. On other platforms, the operating system manages loaded libraries. GDB can not retrieve the list of currently loaded libraries through memory operations, so it uses the `qXfer:libraries:read' packet (see qXfer library list read) instead. The remote stub queries the target's operating system and reports which libraries are loaded.
The `qXfer:libraries:read' packet returns an XML document which lists loaded libraries and their offsets. Each library has an associated name and one or more segment or section base addresses, which report where the library was loaded in memory.
For the common case of libraries that are fully linked binaries, the library should have a list of segments. If the target supports dynamic linking of a relocatable object file, its library XML element should instead include a list of allocated sections. The segment or section bases are start addresses, not relocation offsets; they do not depend on the library's link-time base addresses.
GDB must be linked with the Expat library to support XML library lists. See Expat.
A simple memory map, with one loaded library relocated by a single offset, looks like this:
<library-list>
<library name="/lib/libc.so.6">
<segment address="0x10000000"/>
</library>
</library-list>
|
Another simple memory map, with one loaded library with three allocated sections (.text, .data, .bss), looks like this:
<library-list>
<library name="sharedlib.o">
<section address="0x10000000"/>
<section address="0x20000000"/>
<section address="0x30000000"/>
</library>
</library-list>
|
The format of a library list is described by this DTD:
<!-- library-list: Root element with versioning --> <!ELEMENT library-list (library)*> <!ATTLIST library-list version CDATA #FIXED "1.0"> <!ELEMENT library (segment*, section*)> <!ATTLIST library name CDATA #REQUIRED> <!ELEMENT segment EMPTY> <!ATTLIST segment address CDATA #REQUIRED> <!ELEMENT section EMPTY> <!ATTLIST section address CDATA #REQUIRED> |
In addition, segments and section descriptors cannot be mixed within a single library element, and you must supply at least one segment or section for each library.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g. `ld.so') and normal memory operations to maintain a list of shared libraries. Still a special library list provided by this packet is more efficient for the GDB remote protocol.
The `qXfer:libraries-svr4:read' packet returns an XML document which lists loaded libraries and their SVR4 linker parameters. For each library on SVR4 target, the following parameters are reported:
name, the absolute file name from the l_name field of
struct link_map.
lm with address of struct link_map used for TLS
(Thread Local Storage) access.
l_addr, the displacement as read from the field l_addr of
struct link_map. For prelinked libraries this is not an absolute
memory address. It is a displacement of absolute memory address against
address the file was prelinked to during the library load.
l_ld, which is memory address of the PT_DYNAMIC segment
Additionally the single main-lm attribute specifies address of
struct link_map used for the main executable. This parameter is used
for TLS access and its presence is optional.
GDB must be linked with the Expat library to support XML SVR4 library lists. See Expat.
A simple memory map, with two loaded libraries (which do not use prelink), looks like this:
<library-list-svr4 version="1.0" main-lm="0xe4f8f8">
<library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
l_ld="0xe4eefc"/>
<library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
l_ld="0x152350"/>
</library-list-svr>
|
The format of an SVR4 library list is described by this DTD:
<!-- library-list-svr4: Root element with versioning --> <!ELEMENT library-list-svr4 (library)*> <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0"> <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED> <!ELEMENT library EMPTY> <!ATTLIST library name CDATA #REQUIRED> <!ATTLIST library lm CDATA #REQUIRED> <!ATTLIST library l_addr CDATA #REQUIRED> <!ATTLIST library l_ld CDATA #REQUIRED> |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To be able to write into flash memory, GDB needs to obtain a memory map from the target. This section describes the format of the memory map.
The memory map is obtained using the `qXfer:memory-map:read' (see qXfer memory map read) packet and is an XML document that lists memory regions.
GDB must be linked with the Expat library to support XML memory maps. See Expat.
The top-level structure of the document is shown below:
<?xml version="1.0"?>
<!DOCTYPE memory-map
PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
"http://sourceware.org/gdb/gdb-memory-map.dtd">
<memory-map>
region...
</memory-map>
|
Each region can be either:
<memory type="ram" start="addr" length="length"/> |
<memory type="rom" start="addr" length="length"/> |
<memory type="flash" start="addr" length="length"> <property name="blocksize">blocksize</property> </memory> |
Regions must not overlap. GDB assumes that areas of memory not covered by the memory map are RAM, and uses the ordinary `M' and `X' packets to write to addresses in such ranges.
The formal DTD for memory map format is given below:
<!-- ................................................... -->
<!-- Memory Map XML DTD ................................ -->
<!-- File: memory-map.dtd .............................. -->
<!-- .................................... .............. -->
<!-- memory-map.dtd -->
<!-- memory-map: Root element with versioning -->
<!ELEMENT memory-map (memory | property)>
<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
<!ELEMENT memory (property)>
<!-- memory: Specifies a memory region,
and its type, or device. -->
<!ATTLIST memory type CDATA #REQUIRED
start CDATA #REQUIRED
length CDATA #REQUIRED
device CDATA #IMPLIED>
<!-- property: Generic attribute tag -->
<!ELEMENT property (#PCDATA | property)*>
<!ATTLIST property name CDATA #REQUIRED>
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To efficiently update the list of threads and their attributes, GDB issues the `qXfer:threads:read' packet (see qXfer threads read) and obtains the XML document with the following structure:
<?xml version="1.0"?>
<threads>
<thread id="id" core="0">
... description ...
</thread>
</threads>
|
Each `thread' element must have the `id' attribute that identifies the thread (see thread-id syntax). The `core' attribute, if present, specifies which processor core the thread was last executing on. The content of the of `thread' element is interpreted as human-readable auxilliary information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To be able to know which objects in the inferior can be examined when inspecting a tracepoint hit, GDB needs to obtain the list of memory ranges, registers and trace state variables that have been collected in a traceframe.
This list is obtained using the `qXfer:traceframe-info:read' (see qXfer traceframe info read) packet and is an XML document.
GDB must be linked with the Expat library to support XML traceframe info discovery. See Expat.
The top-level structure of the document is shown below:
<?xml version="1.0"?>
<!DOCTYPE traceframe-info
PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
"http://sourceware.org/gdb/gdb-traceframe-info.dtd">
<traceframe-info>
block...
</traceframe-info>
|
Each traceframe block can be either:
<memory start="addr" length="length"/> |
The formal DTD for the traceframe info format is given below:
<!ELEMENT traceframe-info (memory)* >
<!ATTLIST traceframe-info version CDATA #FIXED "1.0">
<!ELEMENT memory EMPTY>
<!ATTLIST memory start CDATA #REQUIRED
length CDATA #REQUIRED>
|
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |