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 respectfully.
All GDB commands and responses (other than acknowledgments) 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:
$packet-data#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:
$sequence-id:packet-data#checksum
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):
->$packet-data#checksum <-+
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 (the target has again stopped).
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).
Response data can be run-length encoded to save space. A `*'
means that the next character is an ASCII encoding giving a repeat count
which stands for that many repetitions of the character preceding the
`*'. The encoding is n+29, yielding a printable character
where n >=3 (which is where rle starts to win). The printable
characters `$', `#', `+' and `-' or with a numeric
value greater than 126 should not be used.
So:
"0* "
means the same as "0000".
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.
A stub is required to support the `g', `G', `m', `M', `c', and `s' commands. All other commands are optional.
The following table provides a complete list of all currently defined commands and their corresponding response data.
! -- extended mode
? -- last signal
a -- reserved
Aarglen,argnum,arg,... -- set program arguments (reserved)
gdbserver for more details.
Reply:
bbaud -- set baud (deprecated)
Baddr,mode -- set breakpoint (deprecated)
caddr -- continue
Csig;addr -- continue with signal
;addr is omitted, resume at same address.
Reply:
See section Stop Reply Packets, for the reply specifications.
d -- toggle debug (deprecated)
D -- detach
detach command.
Reply:
e -- reserved
E -- reserved
f -- reserved
FRC,EE,CF;XX -- Reply to target's F packet.
F request packet
sent by the target. This is part of the File-I/O protocol extension.
See section File-I/O remote protocol extension, for the specification.
g -- read registers
g packets is specified below.
GXX... -- write regs
h -- reserved
Hct... -- set thread
iaddr,nnn -- cycle step (draft)
,nnn is
present, cycle step nnn cycles. If addr is present, cycle
step starting at that address.
I -- signal then cycle step (reserved)
j -- reserved
J -- reserved
k -- kill request
K -- reserved
l -- reserved
L -- reserved
maddr,length -- read memory
Maddr,length:XX... -- write mem
n -- reserved
N -- reserved
o -- reserved
O -- reserved
pn... -- read reg (reserved)
Pn...=r... -- write register
qquery -- general query
Qvar=val -- general set
r -- reset (deprecated)
RXX -- remote restart
saddr -- step
Ssig;addr -- step with signal
taddr:PP,MM -- search
TXX -- thread alive
u -- reserved
U -- reserved
v -- verbose packet prefix
v are identified by a multi-letter name,
up to the first ; or ? (or the end of the packet).
vCont[;action[:tid]]... -- extended resume
c
Csig
s
Ssig
vCont.
Reply:
See section Stop Reply Packets, for the reply specifications.
vCont? -- extended resume query
vCont packet.
Reply:
vCont[;action]...'
vCont packet is supported. Each action is a supported
command in the vCont packet.
vCont packet is not supported.
V -- reserved
w -- reserved
W -- reserved
x -- reserved
Xaddr,length:XX... -- write mem (binary)
$, #, and 0x7d are
escaped using 0x7d.
Reply:
y -- reserved
Y reserved
ztype,addr,length -- remove breakpoint or watchpoint (draft)
Ztype,addr,length -- insert breakpoint or watchpoint (draft)
Z) or remove (z) a type breakpoint or
watchpoint starting at address address and covering the next
length bytes.
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.
z0,addr,length -- remove memory breakpoint (draft)
Z0,addr,length -- insert memory breakpoint (draft)
Z0) or remove (z0) a memory breakpoint at address
addr of size length.
A memory breakpoint is implemented by replacing the instruction at
addr with a software breakpoint or trap instruction. The
length is used by targets that 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).
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:
z1,addr,length -- remove hardware breakpoint (draft)
Z1,addr,length -- insert hardware breakpoint (draft)
Z1) or remove (z1) a hardware breakpoint at
address addr of size length.
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory.
Implementation note: A hardware breakpoint is not affected by code
movement.
Reply:
z2,addr,length -- remove write watchpoint (draft)
Z2,addr,length -- insert write watchpoint (draft)
Z2) or remove (z2) a write watchpoint.
Reply:
z3,addr,length -- remove read watchpoint (draft)
Z3,addr,length -- insert read watchpoint (draft)
Z3) or remove (z3) a read watchpoint.
Reply:
z4,addr,length -- remove access watchpoint (draft)
Z4,addr,length -- insert access watchpoint (draft)
Z4) or remove (z4) an access watchpoint.
Reply:
The `C', `c', `S', `s' and `?' packets can receive any of the below as a reply. In the case of the `C', `c', `S' and `s' packets, that reply is only returned when the target halts. In the below the exact meaning of `signal number' is poorly defined. In general one of the UNIX signal numbering conventions is used.
TAAn...:r...;n...:r...;n...:r...;'
DEPRECATED_REGISTER_RAW_SIZE; n... = `thread',
r... = thread process ID, this is a hex integer; n... =
(`watch' | `rwatch' | `awatch', r... = data
address, this is a hex integer; n... = other string not starting
with valid hex digit. GDB should ignore this n...,
r... pair and go on to the next. This way we can extend the
protocol.
,parameter...'
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 File-I/O remote protocol extension, for more details.
The following set and query packets have already been defined.
qC -- current thread
QCpid'
qfThreadInfo -- all thread ids
qsThreadInfo
Obtain a list of active thread ids from the target (OS). Since there
may be too many active threads to fit into one reply packet, this query
works iteratively: it may require more than one query/reply sequence to
obtain the entire list of threads. The first query of the sequence will
be the qfThreadInfo query; subsequent queries in the
sequence will be the qsThreadInfo query.
NOTE: replaces the qL query (see below).
Reply:
mid'
mid,id...'
l'
qs form of the query), until the target responds with l
(lower-case el, for 'last').
qThreadExtraInfo,id -- extra thread info
qLstartflagthreadcountnextthread -- query LIST or threadLIST (deprecated)
qfThreadInfo query
(see above).
Reply:
qMcountdoneargthreadthread...'
remote.c:parse_threadlist_response().
qCRC:addr,length -- compute CRC of memory block
ENN'
CCRC32'
qOffsets -- query sect offs
Bss offset is included in the
response, GDB ignores this and instead applies the Data
offset to the Bss section.
Reply:
Text=xxx;Data=yyy;Bss=zzz'
qPmodethreadid -- thread info request
remote.c:remote_unpack_thread_info_response().
qRcmd,command -- remote command
Ooutput console output packets.
Implementors should note that providing access to a stubs's
interpreter may have security implications.
Reply:
ENN'
qSymbol:: -- symbol lookup
OK'
qSymbol:sym_name'
qSymbol:sym_value:sym_name message, described below.
qSymbol:sym_value:sym_name -- symbol value
OK'
qSymbol:sym_name'
qPart:object:read:annex:offset,length -- read special data
object.
Request length bytes starting at offset bytes into the data.
The content and encoding of annex is specific to the object;
it can supply additional details about what data to access.
Here are the specific requests of this form defined so far.
All `qPart:object:read:...'
requests use the same reply formats, listed below.
qPart:auxv:read::offset,length
OK
E00
Enn
errno value.
"" (empty)
qPart:object:write:annex:offset:data...
object,
starting at offset bytes into the data.
data... is the hex-encoded data to be written.
The content and encoding of annex is specific to the object;
it can supply additional details about what data to access.
No requests of this form are presently in use. This specification
serves as a placeholder to document the common format that new
specific request specifications ought to use.
Reply:
E00
Enn
errno value.
"" (empty)
qPart:object:operation:...
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 transfered in target byte order. The two nibbles within a register byte are transfered most-significant - least-significant.
sr). The ordering is the same
as MIPS32.
Example sequence of a target being re-started. Notice how the restart does not get any direct output:
->R00<-+target restarts ->?<-+<-T001:1234123412341234->+
Example sequence of a target being stepped by a single instruction:
->G1445...<-+->s<-+time passes <-T001:1234123412341234->+->g<-+<-1455...->+
The File I/O remote protocol extension (short: File-I/O) allows the target to use the hosts file system and console I/O when calling 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 with an adequate response packet to the target system. This simulates file system operations even on targets that lack file systems.
The protocol is defined host- and target-system independent. It uses it's own independent representation of datatypes and values. Both, GDB and the target's GDB stub are responsible for translating the system dependent values into the unified protocol values when data is transmitted.
The communication is synchronous. A system call is possible only when GDB is waiting for 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 interuptible by target signals. It is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though.
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 is only used for files on the host file system and for I/O on the console. Character or block special devices, pipes, named pipes or sockets or any other communication method on the host system are not supported by this protocol.
The File-I/O protocol uses the F packet, as request as well
as as reply packet. Since a File-I/O system call can only occur when
GDB is waiting for the continuing or stepping target, the
File-I/O request is a reply that GDB has to expect as a result
of a former `C', `c', `S' or `s' packet.
This F packet contains all information needed to allow GDB
to call the appropriate host system call:
At that 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.
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.Fcall-id,parameter...
Parameters are hexadecimal integer values, either the real values in case of scalar datatypes, as pointers to target buffer space in case of compound datatypes and unspecified memory areas or as pointer/length pairs in case of string parameters. These are appended to the call-id, each separated from its predecessor by a comma. All values are transmitted in ASCII string representation, pointer/length pairs separated by a slash.
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 send if the user requested a break. In this case, errno must be send as well, even if the call was successful. The Ctrl-C flag itself consists of the character 'C':Fretcode,errno,Ctrl-C flag;call specific attachment
F0,0,Cor, if the call was interupted before the host call has been performed:
F-1,4,Cassuming 4 is the protocol specific representation of
EINTR.
Structured data which is transferred using a memory read or write as e.g.
a struct stat is expected to be in a protocol specific format with
all scalar multibyte datatypes being big endian. This should be done by
the target before the F packet is sent resp. by GDB before
it transfers memory to the target. Transferred pointers to structured
data should point to the already coerced data at any time.
A special case is, if the Ctrl-C flag is set in the GDB
reply packet. In this case the target should behave, as if it had
gotten a break message. The meaning for the target is "system call
interupted by SIGINT". Consequentially, the target should actually stop
(as with a break message) and return to GDB with a T02
packet. In this case, it's important for the target to know, in which
state the system call was interrupted. Since this action is by design
not an atomic operation, we have to differ between two 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 -- successful or not -- and should behave
as if the break message arrived right after the system call.
GDB must behave reliable. 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 finshed by
GDB. This requires sending M or X packets as they fit.
The F packet may only be send when either nothing has happened
or the full action has been completed.
By default and if not explicitely 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 as 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 on users request.
A special case in this protocol is the library call isatty which
is implemented as it's own call inside of this protocol. It returns
1 to the target if the file descriptor given as parameter is attached
to the GDB console, 0 otherwise. Implementing through system calls
would require implementing ioctl and would be more complex than
needed.
The other special case in this protocol is the system call which
is implemented as it's own call, too. GDB is taking over the full
task of calling the necessary host calls to perform the system
call. The return value of system is simplified before it's returned
to the target. Basically, the only signal transmitted back is EINTR
in case the user pressed Ctrl-C. Otherwise the return value consists
entirely of the exit status of the called command.
Due to security concerns, the system call is refused to be called
by GDB by default. The user has to allow this call explicitly by
entering
set remote system-call-allowed 1'
Disabling the system call is done by
set remote system-call-allowed 0'
The current setting is shown by typing
show remote system-call-allowed'
Synopsis: int open(const char *pathname, int flags); int open(const char *pathname, int flags, mode_t mode); Request: Fopen,pathptr/len,flags,mode
flags is the bitwise or of the following values:
O_CREAT
O_EXCL
O_TRUNC
O_APPEND
O_RDONLY
O_WRONLY
O_RDWR
mode is the bitwise or of the following values:
S_IRUSR
S_IWUSR
S_IRGRP
S_IWGRP
S_IROTH
S_IWOTH
Return value: open returns the new file descriptor or -1 if an error occured. Errors:
EEXIST
EISDIR
EACCES
ENAMETOOLONG
ENOENT
ENODEV
EROFS
EFAULT
ENOSPC
EMFILE
ENFILE
EINTR
Synopsis: int close(int fd); Request: Fclose,fd Return value: close returns zero on success, or -1 if an error occurred. Errors:
EBADF
EINTR
Synopsis: int read(int fd, void *buf, unsigned int count); Request: Fread,fd,bufptr,count Return value: On success, the number of bytes read is returned. Zero indicates end of file. If count is zero, read returns zero as well. On error, -1 is returned. Errors:
EBADF
EFAULT
EINTR
Synopsis: int write(int fd, const void *buf, unsigned int count); Request: Fwrite,fd,bufptr,count Return value: On success, the number of bytes written are returned. Zero indicates nothing was written. On error, -1 is returned. Errors:
EBADF
EFAULT
EFBIG
ENOSPC
EINTR
Synopsis: long lseek (int fd, long offset, int flag); Request: Flseek,fd,offset,flag
flag is one of:
SEEK_SET
SEEK_CUR
SEEK_END
Return value: On success, the resulting unsigned offset in bytes from the beginning of the file is returned. Otherwise, a value of -1 is returned. Errors:
EBADF
ESPIPE
EINVAL
EINTR
Synopsis: int rename(const char *oldpath, const char *newpath); Request: Frename,oldpathptr/len,newpathptr/len Return value: On success, zero is returned. On error, -1 is returned. Errors:
EISDIR
EEXIST
EBUSY
EINVAL
ENOTDIR
EFAULT
EACCES
ENAMETOOLONG
ENOENT
EROFS
ENOSPC
EINTR
Synopsis: int unlink(const char *pathname); Request: Funlink,pathnameptr/len Return value: On success, zero is returned. On error, -1 is returned. Errors:
EACCES
EPERM
EBUSY
EFAULT
ENAMETOOLONG
ENOENT
ENOTDIR
EROFS
EINTR
Synopsis: int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); Request: Fstat,pathnameptr/len,bufptr Ffstat,fd,bufptr Return value: On success, zero is returned. On error, -1 is returned. Errors:
EBADF
ENOENT
ENOTDIR
EFAULT
EACCES
ENAMETOOLONG
EINTR
Synopsis: int gettimeofday(struct timeval *tv, void *tz); Request: Fgettimeofday,tvptr,tzptr Return value: On success, 0 is returned, -1 otherwise. Errors:
EINVAL
EFAULT
Synopsis: int isatty(int fd); Request: Fisatty,fd Return value: Returns 1 if fd refers to the GDB console, 0 otherwise. Errors:
EINTR
Synopsis: int system(const char *command); Request: Fsystem,commandptr/len Return value: The value returned is -1 on error and the return status of the command otherwise. Only the exit status of the command is returned, which is extracted from the hosts system return value by calling WEXITSTATUS(retval). In case /bin/sh could not be executed, 127 is returned. Errors:
EINTR
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.
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.
1aaf/12
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. Example:
``hello, world'' at address 0x123456
is transmitted as
123456/d
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 are conforming to the definitions given in the approriate section (see section 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: 0 file
1 console
st_ino: No valid meaning for the target. Transmitted unchanged.
st_mode: Valid mode bits are described in Appendix C. Any other
bits have currently no meaning for the target.
st_uid: No valid meaning for the target. Transmitted unchanged.
st_gid: No valid meaning for the target. Transmitted unchanged.
st_rdev: No valid meaning for the target. Transmitted unchanged.
st_atime, st_mtime, st_ctime:
These values have a host and file system dependent
accuracy. Especially on Windows hosts the file systems
don't support exact timing values.
The target gets a struct stat of the above representation and is responsible to coerce it to the target representation before continuing.
Note that due to size differences between the host and target representation of stat members, these members could eventually get truncated on the target.
The buffer of type struct timeval used by the target and GDB is defined as follows:
struct timeval {
time_t tv_sec; /* second */
long tv_usec; /* microsecond */
};
The integral datatypes are conforming to the definitions given in the approriate section (see section Integral datatypes, for details) so this structure is of size 8 bytes.
The following values are used for the constants inside of the protocol. GDB and target are resposible to translate these values before and after the call as needed.
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
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
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.
SEEK_SET 0 SEEK_CUR 1 SEEK_END 2
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
Example sequence of a write call, file descriptor 3, buffer is at target address 0x1234, 6 bytes should be written:
<-Fwrite,3,1234,6request memory read from target ->m1234,6<- XXXXXX return "6 bytes written" ->F6
Example sequence of a read call, file descriptor 3, buffer is at target address 0x1234, 6 bytes should be read:
<-Fread,3,1234,6request memory write to target ->X1234,6:XXXXXXreturn "6 bytes read" ->F6
Example sequence of a read call, call fails on the host due to invalid file descriptor (EBADF):
<-Fread,3,1234,6->F-1,9
Example sequence of a read call, user presses Ctrl-C before syscall on host is called:
<-Fread,3,1234,6->F-1,4,C<-T02
Example sequence of a read call, user presses Ctrl-C after syscall on host is called:
<-Fread,3,1234,6->X1234,6:XXXXXX<-T02
Go to the first, previous, next, last section, table of contents.