900 lines
50 KiB
Plaintext
900 lines
50 KiB
Plaintext
|
This is ./gdb.info, produced by Makeinfo version 3.12f from gdb.texinfo.
|
|||
|
|
|
|||
|
|
INFO-DIR-SECTION Programming & development tools.
|
|||
|
|
START-INFO-DIR-ENTRY
|
|||
|
|
* Gdb: (gdb). The GNU debugger.
|
|||
|
|
END-INFO-DIR-ENTRY
|
|||
|
|
|
|||
|
|
This file documents the GNU debugger GDB.
|
|||
|
|
|
|||
|
|
This is the Eighth Edition, March 2000, of `Debugging with GDB: the
|
|||
|
|
GNU Source-Level Debugger' for GDB Version 5.0.
|
|||
|
|
|
|||
|
|
Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
|||
|
|
|
|||
|
|
Permission is granted to make and distribute verbatim copies of this
|
|||
|
|
manual provided the copyright notice and this permission notice are
|
|||
|
|
preserved on all copies.
|
|||
|
|
|
|||
|
|
Permission is granted to copy and distribute modified versions of
|
|||
|
|
this manual under the conditions for verbatim copying, provided also
|
|||
|
|
that the entire resulting derived work is distributed under the terms
|
|||
|
|
of a permission notice identical to this one.
|
|||
|
|
|
|||
|
|
Permission is granted to copy and distribute translations of this
|
|||
|
|
manual into another language, under the above conditions for modified
|
|||
|
|
versions.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Serial
|
|||
|
|
|
|||
|
|
What you must do for the stub
|
|||
|
|
.............................
|
|||
|
|
|
|||
|
|
The debugging stubs that come with GDB are set up for a particular
|
|||
|
|
chip architecture, but they have no information about the rest of your
|
|||
|
|
debugging target machine.
|
|||
|
|
|
|||
|
|
First of all you need to tell the stub how to communicate with the
|
|||
|
|
serial port.
|
|||
|
|
|
|||
|
|
`int getDebugChar()'
|
|||
|
|
Write this subroutine to read a single character from the serial
|
|||
|
|
port. It may be identical to `getchar' for your target system; a
|
|||
|
|
different name is used to allow you to distinguish the two if you
|
|||
|
|
wish.
|
|||
|
|
|
|||
|
|
`void putDebugChar(int)'
|
|||
|
|
Write this subroutine to write a single character to the serial
|
|||
|
|
port. It may be identical to `putchar' for your target system; a
|
|||
|
|
different name is used to allow you to distinguish the two if you
|
|||
|
|
wish.
|
|||
|
|
|
|||
|
|
If you want GDB to be able to stop your program while it is running,
|
|||
|
|
you need to use an interrupt-driven serial driver, and arrange for it
|
|||
|
|
to stop when it receives a `^C' (`\003', the control-C character).
|
|||
|
|
That is the character which GDB uses to tell the remote system to stop.
|
|||
|
|
|
|||
|
|
Getting the debugging target to return the proper status to GDB
|
|||
|
|
probably requires changes to the standard stub; one quick and dirty way
|
|||
|
|
is to just execute a breakpoint instruction (the "dirty" part is that
|
|||
|
|
GDB reports a `SIGTRAP' instead of a `SIGINT').
|
|||
|
|
|
|||
|
|
Other routines you need to supply are:
|
|||
|
|
|
|||
|
|
`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
|
|||
|
|
Write this function to install EXCEPTION_ADDRESS in the exception
|
|||
|
|
handling tables. You need to do this because the stub does not
|
|||
|
|
have any way of knowing what the exception handling tables on your
|
|||
|
|
target system are like (for example, the processor's table might
|
|||
|
|
be in ROM, containing entries which point to a table in RAM).
|
|||
|
|
EXCEPTION_NUMBER is the exception number which should be changed;
|
|||
|
|
its meaning is architecture-dependent (for example, different
|
|||
|
|
numbers might represent divide by zero, misaligned access, etc).
|
|||
|
|
When this exception occurs, control should be transferred directly
|
|||
|
|
to EXCEPTION_ADDRESS, and the processor state (stack, registers,
|
|||
|
|
and so on) should be just as it is when a processor exception
|
|||
|
|
occurs. So if you want to use a jump instruction to reach
|
|||
|
|
EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
|
|||
|
|
subroutine.
|
|||
|
|
|
|||
|
|
For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
|
|||
|
|
gate so that interrupts are masked while the handler runs. The
|
|||
|
|
gate should be at privilege level 0 (the most privileged level).
|
|||
|
|
The SPARC and 68k stubs are able to mask interrupts themselves
|
|||
|
|
without help from `exceptionHandler'.
|
|||
|
|
|
|||
|
|
`void flush_i_cache()'
|
|||
|
|
On SPARC and SPARCLITE only, write this subroutine to flush the
|
|||
|
|
instruction cache, if any, on your target machine. If there is no
|
|||
|
|
instruction cache, this subroutine may be a no-op.
|
|||
|
|
|
|||
|
|
On target machines that have instruction caches, GDB requires this
|
|||
|
|
function to make certain that the state of your program is stable.
|
|||
|
|
|
|||
|
|
You must also make sure this library routine is available:
|
|||
|
|
|
|||
|
|
`void *memset(void *, int, int)'
|
|||
|
|
This is the standard library function `memset' that sets an area of
|
|||
|
|
memory to a known value. If you have one of the free versions of
|
|||
|
|
`libc.a', `memset' can be found there; otherwise, you must either
|
|||
|
|
obtain it from your hardware manufacturer, or write your own.
|
|||
|
|
|
|||
|
|
If you do not use the GNU C compiler, you may need other standard
|
|||
|
|
library subroutines as well; this varies from one stub to another, but
|
|||
|
|
in general the stubs are likely to use any of the common library
|
|||
|
|
subroutines which `gcc' generates as inline code.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: gdb.info, Node: Debug Session, Next: Protocol, Prev: Bootstrapping, Up: Remote Serial
|
|||
|
|
|
|||
|
|
Putting it all together
|
|||
|
|
.......................
|
|||
|
|
|
|||
|
|
In summary, when your program is ready to debug, you must follow
|
|||
|
|
these steps.
|
|||
|
|
|
|||
|
|
1. Make sure you have defined the supporting low-level routines
|
|||
|
|
(*note What you must do for the stub: Bootstrapping.):
|
|||
|
|
`getDebugChar', `putDebugChar',
|
|||
|
|
`flush_i_cache', `memset', `exceptionHandler'.
|
|||
|
|
|
|||
|
|
2. Insert these lines near the top of your program:
|
|||
|
|
|
|||
|
|
set_debug_traps();
|
|||
|
|
breakpoint();
|
|||
|
|
|
|||
|
|
3. For the 680x0 stub only, you need to provide a variable called
|
|||
|
|
`exceptionHook'. Normally you just use:
|
|||
|
|
|
|||
|
|
void (*exceptionHook)() = 0;
|
|||
|
|
|
|||
|
|
but if before calling `set_debug_traps', you set it to point to a
|
|||
|
|
function in your program, that function is called when `GDB'
|
|||
|
|
continues after stopping on a trap (for example, bus error). The
|
|||
|
|
function indicated by `exceptionHook' is called with one
|
|||
|
|
parameter: an `int' which is the exception number.
|
|||
|
|
|
|||
|
|
4. Compile and link together: your program, the GDB debugging stub for
|
|||
|
|
your target architecture, and the supporting subroutines.
|
|||
|
|
|
|||
|
|
5. Make sure you have a serial connection between your target machine
|
|||
|
|
and the GDB host, and identify the serial port on the host.
|
|||
|
|
|
|||
|
|
6. Download your program to your target machine (or get it there by
|
|||
|
|
whatever means the manufacturer provides), and start it.
|
|||
|
|
|
|||
|
|
7. To start remote debugging, run GDB on the host machine, and specify
|
|||
|
|
as an executable file the program that is running in the remote
|
|||
|
|
machine. This tells GDB how to find your program's symbols and
|
|||
|
|
the contents of its pure text.
|
|||
|
|
|
|||
|
|
8. Establish communication using the `target remote' command. Its
|
|||
|
|
argument specifies how to communicate with the target
|
|||
|
|
machine--either via a devicename attached to a direct serial line,
|
|||
|
|
or a TCP port (usually to a terminal server which in turn has a
|
|||
|
|
serial line to the target). For example, to use a serial line
|
|||
|
|
connected to the device named `/dev/ttyb':
|
|||
|
|
|
|||
|
|
target remote /dev/ttyb
|
|||
|
|
|
|||
|
|
To use a TCP connection, use an argument of the form `HOST:port'.
|
|||
|
|
For example, to connect to port 2828 on a terminal server named
|
|||
|
|
`manyfarms':
|
|||
|
|
|
|||
|
|
target remote manyfarms:2828
|
|||
|
|
|
|||
|
|
Now you can use all the usual commands to examine and change data
|
|||
|
|
and to step and continue the remote program.
|
|||
|
|
|
|||
|
|
To resume the remote program and stop debugging it, use the `detach'
|
|||
|
|
command.
|
|||
|
|
|
|||
|
|
Whenever GDB is waiting for the remote program, if you type the
|
|||
|
|
interrupt character (often <C-C>), GDB attempts to stop the program.
|
|||
|
|
This may or may not succeed, depending in part on the hardware and the
|
|||
|
|
serial drivers the remote system uses. If you type the interrupt
|
|||
|
|
character once again, GDB displays this prompt:
|
|||
|
|
|
|||
|
|
Interrupted while waiting for the program.
|
|||
|
|
Give up (and stop debugging it)? (y or n)
|
|||
|
|
|
|||
|
|
If you type `y', GDB abandons the remote debugging session. (If you
|
|||
|
|
decide you want to try again later, you can use `target remote' again
|
|||
|
|
to connect once more.) If you type `n', GDB goes back to waiting.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: gdb.info, Node: Protocol, Next: Server, Prev: Debug Session, Up: Remote Serial
|
|||
|
|
|
|||
|
|
Communication protocol
|
|||
|
|
......................
|
|||
|
|
|
|||
|
|
The stub files provided with GDB implement the target side of the
|
|||
|
|
communication protocol, and the GDB side is implemented in the GDB
|
|||
|
|
source file `remote.c'. Normally, you can simply allow these
|
|||
|
|
subroutines to communicate, and ignore the details. (If you're
|
|||
|
|
implementing your own stub file, you can still ignore the details: start
|
|||
|
|
with one of the existing stub files. `sparc-stub.c' is the best
|
|||
|
|
organized, and therefore the easiest to read.)
|
|||
|
|
|
|||
|
|
However, 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.
|
|||
|
|
|
|||
|
|
Some remote systems have used a different run-length encoding
|
|||
|
|
mechanism loosely refered to as the cisco encoding. Following the `*'
|
|||
|
|
character are two hex digits that indicate the size of the packet.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
Below is a complete list of all currently defined COMMANDs and their
|
|||
|
|
corresponding response DATA:
|
|||
|
|
|
|||
|
|
Packet Request Description
|
|||
|
|
extended ops `!' Use the extended remote
|
|||
|
|
protocol. Sticky--only
|
|||
|
|
needs to be set once. The
|
|||
|
|
extended remote protocol
|
|||
|
|
supports the `R' packet.
|
|||
|
|
reply `' Stubs that support the
|
|||
|
|
extended remote protocol
|
|||
|
|
return `' which,
|
|||
|
|
unfortunately, is identical
|
|||
|
|
to the response returned by
|
|||
|
|
stubs that do not support
|
|||
|
|
protocol extensions.
|
|||
|
|
last signal `?' Indicate the reason the
|
|||
|
|
target halted. The reply is
|
|||
|
|
the same as for step and
|
|||
|
|
continue.
|
|||
|
|
reply see below
|
|||
|
|
reserved `a' Reserved for future use
|
|||
|
|
set program arguments `A'ARGLEN`,'ARGNUM`,'ARG`,...'
|
|||
|
|
*(reserved)*
|
|||
|
|
Initialized `argv[]' array
|
|||
|
|
passed into program. ARGLEN
|
|||
|
|
specifies the number of
|
|||
|
|
bytes in the hex encoded
|
|||
|
|
byte stream ARG. See
|
|||
|
|
`gdbserver' for more details.
|
|||
|
|
reply `OK'
|
|||
|
|
reply `E'NN
|
|||
|
|
set baud `b'BAUD Change the serial line speed
|
|||
|
|
*(deprecated)* to BAUD. 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._
|
|||
|
|
set breakpoint `B'ADDR,MODE Set (MODE is `S') or clear
|
|||
|
|
*(deprecated)* (MODE is `C') a breakpoint
|
|||
|
|
at ADDR. _This has been
|
|||
|
|
replaced by the `Z' and `z'
|
|||
|
|
packets._
|
|||
|
|
continue `c'ADDR ADDR is address to resume.
|
|||
|
|
If ADDR is omitted, resume at
|
|||
|
|
current address.
|
|||
|
|
reply see below
|
|||
|
|
continue with signal `C'SIG`;'ADDR Continue with signal SIG
|
|||
|
|
(hex signal number). If
|
|||
|
|
`;'ADDR is omitted, resume
|
|||
|
|
at same address.
|
|||
|
|
reply see below
|
|||
|
|
toggle debug `d' toggle debug flag.
|
|||
|
|
*(deprecated)*
|
|||
|
|
detach `D' Detach GDB from the remote
|
|||
|
|
system. Sent to the remote
|
|||
|
|
target before GDB
|
|||
|
|
disconnects.
|
|||
|
|
reply _no response_ GDB does not check for any
|
|||
|
|
response after sending this
|
|||
|
|
packet.
|
|||
|
|
reserved `e' Reserved for future use
|
|||
|
|
reserved `E' Reserved for future use
|
|||
|
|
reserved `f' Reserved for future use
|
|||
|
|
reserved `F' Reserved for future use
|
|||
|
|
read registers `g' Read general registers.
|
|||
|
|
reply XX... Each byte of register data
|
|||
|
|
is described by two hex
|
|||
|
|
digits. The bytes with the
|
|||
|
|
register are transmitted in
|
|||
|
|
target byte order. The size
|
|||
|
|
of each register and their
|
|||
|
|
position within the `g'
|
|||
|
|
PACKET are determined by the
|
|||
|
|
GDB internal macros
|
|||
|
|
REGISTER_RAW_SIZE and
|
|||
|
|
REGISTER_NAME macros. The
|
|||
|
|
specification of several
|
|||
|
|
standard `g' packets is
|
|||
|
|
specified below.
|
|||
|
|
`E'NN for an error.
|
|||
|
|
write regs `G'XX... See `g' for a description of
|
|||
|
|
the XX... data.
|
|||
|
|
reply `OK' for success
|
|||
|
|
reply `E'NN for an error
|
|||
|
|
reserved `h' Reserved for future use
|
|||
|
|
set thread `H'CT... Set thread for subsequent
|
|||
|
|
operations (`m', `M', `g',
|
|||
|
|
`G', et.al.). C = `c' for
|
|||
|
|
thread used in step and
|
|||
|
|
continue; T... can be -1 for
|
|||
|
|
all threads. C = `g' for
|
|||
|
|
thread used in other
|
|||
|
|
operations. If zero, pick a
|
|||
|
|
thread, any thread.
|
|||
|
|
reply `OK' for success
|
|||
|
|
reply `E'NN for an error
|
|||
|
|
cycle step *(draft)* `i'ADDR`,'NNN Step the remote target by a
|
|||
|
|
single clock cycle. If
|
|||
|
|
`,'NNN is present, cycle
|
|||
|
|
step NNN cycles. If ADDR is
|
|||
|
|
present, cycle step starting
|
|||
|
|
at that address.
|
|||
|
|
signal then cycle `I' See `i' and `S' for likely
|
|||
|
|
step *(reserved)* syntax and semantics.
|
|||
|
|
reserved `j' Reserved for future use
|
|||
|
|
reserved `J' Reserved for future use
|
|||
|
|
kill request `k' FIXME: _There is no
|
|||
|
|
description of how operate
|
|||
|
|
when a specific thread
|
|||
|
|
context has been selected
|
|||
|
|
(ie. does 'k' kill only that
|
|||
|
|
thread?)_.
|
|||
|
|
reserved `l' Reserved for future use
|
|||
|
|
reserved `L' Reserved for future use
|
|||
|
|
read memory `m'ADDR`,'LENGTH Read LENGTH bytes of memory
|
|||
|
|
starting at address ADDR.
|
|||
|
|
Neither GDB nor the stub
|
|||
|
|
assume that sized memory
|
|||
|
|
transfers are assumed using
|
|||
|
|
word alligned accesses.
|
|||
|
|
FIXME: _A word aligned memory
|
|||
|
|
transfer mechanism is
|
|||
|
|
needed._
|
|||
|
|
reply XX... XX... is mem contents. Can
|
|||
|
|
be fewer bytes than
|
|||
|
|
requested if able to read
|
|||
|
|
only part of the data.
|
|||
|
|
Neither GDB nor the stub
|
|||
|
|
assume that sized memory
|
|||
|
|
transfers are assumed using
|
|||
|
|
word alligned accesses.
|
|||
|
|
FIXME: _A word aligned
|
|||
|
|
memory transfer mechanism is
|
|||
|
|
needed._
|
|||
|
|
reply `E'NN NN is errno
|
|||
|
|
write mem `M'ADDR,LENGTH`:'XX... Write LENGTH bytes of memory
|
|||
|
|
starting at address ADDR.
|
|||
|
|
XX... is the data.
|
|||
|
|
reply `OK' for success
|
|||
|
|
reply `E'NN for an error (this includes
|
|||
|
|
the case where only part of
|
|||
|
|
the data was written).
|
|||
|
|
reserved `n' Reserved for future use
|
|||
|
|
reserved `N' Reserved for future use
|
|||
|
|
reserved `o' Reserved for future use
|
|||
|
|
reserved `O' Reserved for future use
|
|||
|
|
read reg *(reserved)* `p'N... See write register.
|
|||
|
|
return R.... The hex encoded value of the
|
|||
|
|
register in target byte
|
|||
|
|
order.
|
|||
|
|
write reg `P'N...`='R... Write register N... with
|
|||
|
|
value R..., which contains
|
|||
|
|
two hex digits for each byte
|
|||
|
|
in the register (target byte
|
|||
|
|
order).
|
|||
|
|
reply `OK' for success
|
|||
|
|
reply `E'NN for an error
|
|||
|
|
general query `q'QUERY Request info about QUERY.
|
|||
|
|
In general GDB queries have
|
|||
|
|
a leading upper case letter.
|
|||
|
|
Custom vendor queries
|
|||
|
|
should use a company prefix
|
|||
|
|
(in lower case) ex:
|
|||
|
|
`qfsf.var'. QUERY may
|
|||
|
|
optionally be followed by a
|
|||
|
|
`,' or `;' separated list.
|
|||
|
|
Stubs must ensure that they
|
|||
|
|
match the full QUERY name.
|
|||
|
|
reply `XX...' Hex encoded data from query.
|
|||
|
|
The reply can not be empty.
|
|||
|
|
reply `E'NN error reply
|
|||
|
|
reply `' Indicating an unrecognized
|
|||
|
|
QUERY.
|
|||
|
|
general set `Q'VAR`='VAL Set value of VAR to VAL.
|
|||
|
|
See `q' for a discussing of
|
|||
|
|
naming conventions.
|
|||
|
|
reset *(deprecated)* `r' Reset the entire system.
|
|||
|
|
remote restart `R'XX Restart the remote server.
|
|||
|
|
XX while needed has no clear
|
|||
|
|
definition. FIXME: _An
|
|||
|
|
example interaction
|
|||
|
|
explaining how this packet
|
|||
|
|
is used in extended-remote
|
|||
|
|
mode is needed_.
|
|||
|
|
step `s'ADDR ADDR is address to resume.
|
|||
|
|
If ADDR is omitted, resume at
|
|||
|
|
same address.
|
|||
|
|
reply see below
|
|||
|
|
step with signal `S'SIG`;'ADDR Like `C' but step not
|
|||
|
|
continue.
|
|||
|
|
reply see below
|
|||
|
|
search `t'ADDR`:'PP`,'MM Search backwards starting at
|
|||
|
|
address ADDR for a match
|
|||
|
|
with pattern PP and mask MM.
|
|||
|
|
PP and MM are 4 bytes.
|
|||
|
|
ADDR must be at least 3
|
|||
|
|
digits.
|
|||
|
|
thread alive `T'XX Find out if the thread XX is
|
|||
|
|
alive.
|
|||
|
|
reply `OK' thread is still alive
|
|||
|
|
reply `E'NN thread is dead
|
|||
|
|
reserved `u' Reserved for future use
|
|||
|
|
reserved `U' Reserved for future use
|
|||
|
|
reserved `v' Reserved for future use
|
|||
|
|
reserved `V' Reserved for future use
|
|||
|
|
reserved `w' Reserved for future use
|
|||
|
|
reserved `W' Reserved for future use
|
|||
|
|
reserved `x' Reserved for future use
|
|||
|
|
write mem (binary) `X'ADDR`,'LENGTH:XX... ADDR is address, LENGTH is
|
|||
|
|
number of bytes, XX... is
|
|||
|
|
binary data. The characters
|
|||
|
|
`$', `#', and `0x7d' are
|
|||
|
|
escaped using `0x7d'.
|
|||
|
|
reply `OK' for success
|
|||
|
|
reply `E'NN for an error
|
|||
|
|
reserved `y' Reserved for future use
|
|||
|
|
reserved `Y' Reserved for future use
|
|||
|
|
remove break or `z'T`,'ADDR`,'LENGTH See `Z'.
|
|||
|
|
watchpoint *(draft)*
|
|||
|
|
insert break or `Z'T`,'ADDR`,'LENGTH T is type: `0' - software
|
|||
|
|
watchpoint *(draft)* breakpoint, `1' - hardware
|
|||
|
|
breakpoint, `2' - write
|
|||
|
|
watchpoint, `3' - read
|
|||
|
|
watchpoint, `4' - access
|
|||
|
|
watchpoint; ADDR is address;
|
|||
|
|
LENGTH is in bytes. For a
|
|||
|
|
software breakpoint, LENGTH
|
|||
|
|
specifies the size of the
|
|||
|
|
instruction to be patched.
|
|||
|
|
For hardware breakpoints and
|
|||
|
|
watchpoints LENGTH specifies
|
|||
|
|
the memory region to be
|
|||
|
|
monitored. To avoid
|
|||
|
|
potential problems with
|
|||
|
|
duplicate packets, the
|
|||
|
|
operations should be
|
|||
|
|
implemented in an idempotent
|
|||
|
|
way.
|
|||
|
|
reply `E'NN for an error
|
|||
|
|
reply `OK' for success
|
|||
|
|
`' If not supported.
|
|||
|
|
reserved <other> Reserved for future use
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
`S'AA AA is the signal number
|
|||
|
|
`T'AAN...`:'R...`;'N...`:'R...`;'N...`:'R...`;'AA = two hex digit signal number; N... =
|
|||
|
|
register number (hex), R... = target byte
|
|||
|
|
ordered register contents, size defined by
|
|||
|
|
`REGISTER_RAW_SIZE'; N... = `thread', R...
|
|||
|
|
= thread process ID, 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.
|
|||
|
|
`W'AA The process exited, and AA is the exit
|
|||
|
|
status. This is only applicable for
|
|||
|
|
certains sorts of targets.
|
|||
|
|
`X'AA The process terminated with signal AA.
|
|||
|
|
`N'AA`;'T...`;'D...`;'B... AA = signal number; T... = address of
|
|||
|
|
*(obsolete)* symbol "_start"; D... = base of data
|
|||
|
|
section; B... = base of bss section.
|
|||
|
|
_Note: only used by Cisco Systems targets.
|
|||
|
|
The difference between this reply and the
|
|||
|
|
"qOffsets" query is that the 'N' packet
|
|||
|
|
may arrive spontaneously whereas the
|
|||
|
|
'qOffsets' is a query initiated by the host
|
|||
|
|
debugger._
|
|||
|
|
`O'XX... XX... is hex encoding of ASCII data. This
|
|||
|
|
can happen at any time while the program
|
|||
|
|
is running and the debugger should
|
|||
|
|
continue to wait for 'W', 'T', etc.
|
|||
|
|
|
|||
|
|
The following set and query packets have already been defined.
|
|||
|
|
|
|||
|
|
current thread `q'`C' Return the current thread id.
|
|||
|
|
reply `QC'PID Where PID is a HEX encoded 16 bit process
|
|||
|
|
id.
|
|||
|
|
reply * Any other reply implies the old pid.
|
|||
|
|
all thread ids `q'`fThreadInfo'
|
|||
|
|
`q'`sThreadInfo'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 `qf'`ThreadInfo' query;
|
|||
|
|
subsequent queries in the sequence will be
|
|||
|
|
the `qs'`ThreadInfo' query.
|
|||
|
|
NOTE: replaces the `qL' query (see below).
|
|||
|
|
reply `m'<ID> A single thread id
|
|||
|
|
reply a comma-separated list of thread ids
|
|||
|
|
`m'<ID>,<ID>...
|
|||
|
|
reply `l' (lower case 'el') denotes end of list.
|
|||
|
|
In response to each query, the target will
|
|||
|
|
reply with a list of one or more thread
|
|||
|
|
ids, in big-endian hex, 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 el,
|
|||
|
|
for `'last'').
|
|||
|
|
extra thread `q'`ThreadExtraInfo'`,'ID
|
|||
|
|
info
|
|||
|
|
Where <ID> is a thread-id in big-endian
|
|||
|
|
hex. Obtain a printable string
|
|||
|
|
description of a thread's attributes from
|
|||
|
|
the target OS. This string may contain
|
|||
|
|
anything that the target OS thinks is
|
|||
|
|
interesting for GDB to tell the user about
|
|||
|
|
the thread. The string is displayed in
|
|||
|
|
GDB's `info threads' display. Some
|
|||
|
|
examples of possible thread extra info
|
|||
|
|
strings are "Runnable", or "Blocked on
|
|||
|
|
Mutex".
|
|||
|
|
reply XX... Where XX... is a hex encoding of ASCII
|
|||
|
|
data, comprising the printable string
|
|||
|
|
containing the extra information about the
|
|||
|
|
thread's attributes.
|
|||
|
|
query LIST or `q'`L'STARTFLAGTHREADCOUNTNEXTTHREAD
|
|||
|
|
THREADLIST
|
|||
|
|
*(deprecated)*
|
|||
|
|
Obtain thread information from RTOS.
|
|||
|
|
Where: STARTFLAG (one hex digit) is one to
|
|||
|
|
indicate the first query and zero to
|
|||
|
|
indicate a subsequent query; THREADCOUNT
|
|||
|
|
(two hex digits) is the maximum number of
|
|||
|
|
threads the response packet can contain;
|
|||
|
|
and NEXTTHREAD (eight hex digits), for
|
|||
|
|
subsequent queries (STARTFLAG is zero), is
|
|||
|
|
returned in the response as ARGTHREAD.
|
|||
|
|
NOTE: this query is replaced by the
|
|||
|
|
`q'`fThreadInfo' query (see above).
|
|||
|
|
reply
|
|||
|
|
`q'`M'COUNTDONEARGTHREADTHREAD...
|
|||
|
|
Where: COUNT (two hex digits) is the
|
|||
|
|
number of threads being returned; DONE
|
|||
|
|
(one hex digit) is zero to indicate more
|
|||
|
|
threads and one indicates no further
|
|||
|
|
threads; ARGTHREADID (eight hex digits) is
|
|||
|
|
NEXTTHREAD from the request packet;
|
|||
|
|
THREAD... is a sequence of thread IDs from
|
|||
|
|
the target. THREADID (eight hex digits).
|
|||
|
|
See `remote.c:parse_threadlist_response()'.
|
|||
|
|
compute CRC `q'`CRC:'ADDR`,'LENGTH
|
|||
|
|
of memory
|
|||
|
|
block
|
|||
|
|
reply `E'NN An error (such as memory fault)
|
|||
|
|
reply `C'CRC32 A 32 bit cyclic redundancy check of the
|
|||
|
|
specified memory region.
|
|||
|
|
query sect `q'`Offsets' Get section offsets that the target used
|
|||
|
|
offs when re-locating the downloaded image.
|
|||
|
|
_Note: while a `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
|
|||
|
|
thread info `q'`P'MODETHREADID
|
|||
|
|
request
|
|||
|
|
Returns information on THREADID. Where:
|
|||
|
|
MODE is a hex encoded 32 bit mode;
|
|||
|
|
THREADID is a hex encoded 64 bit thread ID.
|
|||
|
|
reply * See
|
|||
|
|
`remote.c:remote_unpack_thread_info_response()'.
|
|||
|
|
remote command `q'`Rcmd,'COMMAND
|
|||
|
|
COMMAND (hex encoded) is passed to the
|
|||
|
|
local interpreter for execution. Invalid
|
|||
|
|
commands should be reported using the
|
|||
|
|
output string. Before the final result
|
|||
|
|
packet, the target may also respond with a
|
|||
|
|
number of intermediate `O'OUTPUT console
|
|||
|
|
output packets. _Implementors should note
|
|||
|
|
that providing access to a stubs's
|
|||
|
|
interpreter may have security
|
|||
|
|
implications_.
|
|||
|
|
reply `OK' A command response with no output.
|
|||
|
|
reply OUTPUT A command response with the hex encoded
|
|||
|
|
output string OUTPUT.
|
|||
|
|
reply `E'NN Indicate a badly formed request.
|
|||
|
|
reply `' When `q'`Rcmd' is not recognized.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
MIPS32 All registers are transfered as
|
|||
|
|
thirty-two bit quantities in the
|
|||
|
|
order: 32 general-purpose; sr; lo;
|
|||
|
|
hi; bad; cause; pc; 32
|
|||
|
|
floating-point registers; fsr; fir;
|
|||
|
|
fp.
|
|||
|
|
MIPS64 All registers are transfered as
|
|||
|
|
sixty-four bit quantities (including
|
|||
|
|
thirty-two bit registers such as
|
|||
|
|
`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...'
|
|||
|
|
<- `+'
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: gdb.info, Node: Server, Next: NetWare, Prev: Protocol, Up: Remote Serial
|
|||
|
|
|
|||
|
|
Using the `gdbserver' program
|
|||
|
|
.............................
|
|||
|
|
|
|||
|
|
`gdbserver' is a control program for Unix-like systems, which allows
|
|||
|
|
you to connect your program with a remote GDB via `target remote'--but
|
|||
|
|
without linking in the usual debugging stub.
|
|||
|
|
|
|||
|
|
`gdbserver' is not a complete replacement for the debugging stubs,
|
|||
|
|
because it requires essentially the same operating-system facilities
|
|||
|
|
that GDB itself does. In fact, a system that can run `gdbserver' to
|
|||
|
|
connect to a remote GDB could also run GDB locally! `gdbserver' is
|
|||
|
|
sometimes useful nevertheless, because it is a much smaller program
|
|||
|
|
than GDB itself. It is also easier to port than all of GDB, so you may
|
|||
|
|
be able to get started more quickly on a new system by using
|
|||
|
|
`gdbserver'. Finally, if you develop code for real-time systems, you
|
|||
|
|
may find that the tradeoffs involved in real-time operation make it
|
|||
|
|
more convenient to do as much development work as possible on another
|
|||
|
|
system, for example by cross-compiling. You can use `gdbserver' to
|
|||
|
|
make a similar choice for debugging.
|
|||
|
|
|
|||
|
|
GDB and `gdbserver' communicate via either a serial line or a TCP
|
|||
|
|
connection, using the standard GDB remote serial protocol.
|
|||
|
|
|
|||
|
|
_On the target machine,_
|
|||
|
|
you need to have a copy of the program you want to debug.
|
|||
|
|
`gdbserver' does not need your program's symbol table, so you can
|
|||
|
|
strip the program if necessary to save space. GDB on the host
|
|||
|
|
system does all the symbol handling.
|
|||
|
|
|
|||
|
|
To use the server, you must tell it how to communicate with GDB;
|
|||
|
|
the name of your program; and the arguments for your program. The
|
|||
|
|
syntax is:
|
|||
|
|
|
|||
|
|
target> gdbserver COMM PROGRAM [ ARGS ... ]
|
|||
|
|
|
|||
|
|
COMM is either a device name (to use a serial line) or a TCP
|
|||
|
|
hostname and portnumber. For example, to debug Emacs with the
|
|||
|
|
argument `foo.txt' and communicate with GDB over the serial port
|
|||
|
|
`/dev/com1':
|
|||
|
|
|
|||
|
|
target> gdbserver /dev/com1 emacs foo.txt
|
|||
|
|
|
|||
|
|
`gdbserver' waits passively for the host GDB to communicate with
|
|||
|
|
it.
|
|||
|
|
|
|||
|
|
To use a TCP connection instead of a serial line:
|
|||
|
|
|
|||
|
|
target> gdbserver host:2345 emacs foo.txt
|
|||
|
|
|
|||
|
|
The only difference from the previous example is the first
|
|||
|
|
argument, specifying that you are communicating with the host GDB
|
|||
|
|
via TCP. The `host:2345' argument means that `gdbserver' is to
|
|||
|
|
expect a TCP connection from machine `host' to local TCP port 2345.
|
|||
|
|
(Currently, the `host' part is ignored.) You can choose any number
|
|||
|
|
you want for the port number as long as it does not conflict with
|
|||
|
|
any TCP ports already in use on the target system (for example,
|
|||
|
|
`23' is reserved for `telnet').(1) You must use the same port
|
|||
|
|
number with the host GDB `target remote' command.
|
|||
|
|
|
|||
|
|
_On the GDB host machine,_
|
|||
|
|
you need an unstripped copy of your program, since GDB needs
|
|||
|
|
symbols and debugging information. Start up GDB as usual, using
|
|||
|
|
the name of the local copy of your program as the first argument.
|
|||
|
|
(You may also need the `--baud' option if the serial line is
|
|||
|
|
running at anything other than 9600bps.) After that, use `target
|
|||
|
|
remote' to establish communications with `gdbserver'. Its argument
|
|||
|
|
is either a device name (usually a serial device, like
|
|||
|
|
`/dev/ttyb'), or a TCP port descriptor in the form `HOST:PORT'.
|
|||
|
|
For example:
|
|||
|
|
|
|||
|
|
(gdb) target remote /dev/ttyb
|
|||
|
|
|
|||
|
|
communicates with the server via serial line `/dev/ttyb', and
|
|||
|
|
|
|||
|
|
(gdb) target remote the-target:2345
|
|||
|
|
|
|||
|
|
communicates via a TCP connection to port 2345 on host
|
|||
|
|
`the-target'. For TCP connections, you must start up `gdbserver'
|
|||
|
|
prior to using the `target remote' command. Otherwise you may get
|
|||
|
|
an error whose text depends on the host system, but which usually
|
|||
|
|
looks something like `Connection refused'.
|
|||
|
|
|
|||
|
|
---------- Footnotes ----------
|
|||
|
|
|
|||
|
|
(1) If you choose a port number that conflicts with another service,
|
|||
|
|
`gdbserver' prints an error message and exits.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: gdb.info, Node: NetWare, Prev: Server, Up: Remote Serial
|
|||
|
|
|
|||
|
|
Using the `gdbserve.nlm' program
|
|||
|
|
................................
|
|||
|
|
|
|||
|
|
`gdbserve.nlm' is a control program for NetWare systems, which
|
|||
|
|
allows you to connect your program with a remote GDB via `target
|
|||
|
|
remote'.
|
|||
|
|
|
|||
|
|
GDB and `gdbserve.nlm' communicate via a serial line, using the
|
|||
|
|
standard GDB remote serial protocol.
|
|||
|
|
|
|||
|
|
_On the target machine,_
|
|||
|
|
you need to have a copy of the program you want to debug.
|
|||
|
|
`gdbserve.nlm' does not need your program's symbol table, so you
|
|||
|
|
can strip the program if necessary to save space. GDB on the host
|
|||
|
|
system does all the symbol handling.
|
|||
|
|
|
|||
|
|
To use the server, you must tell it how to communicate with GDB;
|
|||
|
|
the name of your program; and the arguments for your program. The
|
|||
|
|
syntax is:
|
|||
|
|
|
|||
|
|
load gdbserve [ BOARD=BOARD ] [ PORT=PORT ]
|
|||
|
|
[ BAUD=BAUD ] PROGRAM [ ARGS ... ]
|
|||
|
|
|
|||
|
|
BOARD and PORT specify the serial line; BAUD specifies the baud
|
|||
|
|
rate used by the connection. PORT and NODE default to 0, BAUD
|
|||
|
|
defaults to 9600bps.
|
|||
|
|
|
|||
|
|
For example, to debug Emacs with the argument `foo.txt'and
|
|||
|
|
communicate with GDB over serial port number 2 or board 1 using a
|
|||
|
|
19200bps connection:
|
|||
|
|
|
|||
|
|
load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
|
|||
|
|
|
|||
|
|
_On the GDB host machine,_
|
|||
|
|
you need an unstripped copy of your program, since GDB needs
|
|||
|
|
symbols and debugging information. Start up GDB as usual, using
|
|||
|
|
the name of the local copy of your program as the first argument.
|
|||
|
|
(You may also need the `--baud' option if the serial line is
|
|||
|
|
running at anything other than 9600bps. After that, use `target
|
|||
|
|
remote' to establish communications with `gdbserve.nlm'. Its
|
|||
|
|
argument is a device name (usually a serial device, like
|
|||
|
|
`/dev/ttyb'). For example:
|
|||
|
|
|
|||
|
|
(gdb) target remote /dev/ttyb
|
|||
|
|
|
|||
|
|
communications with the server via serial line `/dev/ttyb'.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: gdb.info, Node: KOD, Prev: Remote, Up: Targets
|
|||
|
|
|
|||
|
|
Kernel Object Display
|
|||
|
|
=====================
|
|||
|
|
|
|||
|
|
Some targets support kernel object display. Using this facility,
|
|||
|
|
GDB communicates specially with the underlying operating system and can
|
|||
|
|
display information about operating system-level objects such as
|
|||
|
|
mutexes and other synchronization objects. Exactly which objects can be
|
|||
|
|
displayed is determined on a per-OS basis.
|
|||
|
|
|
|||
|
|
Use the `set os' command to set the operating system. This tells
|
|||
|
|
GDB which kernel object display module to initialize:
|
|||
|
|
|
|||
|
|
(gdb) set os cisco
|
|||
|
|
|
|||
|
|
If `set os' succeeds, GDB will display some information about the
|
|||
|
|
operating system, and will create a new `info' command which can be
|
|||
|
|
used to query the target. The `info' command is named after the
|
|||
|
|
operating system:
|
|||
|
|
|
|||
|
|
(gdb) info cisco
|
|||
|
|
List of Cisco Kernel Objects
|
|||
|
|
Object Description
|
|||
|
|
any Any and all objects
|
|||
|
|
|
|||
|
|
Further subcommands can be used to query about particular objects
|
|||
|
|
known by the kernel.
|
|||
|
|
|
|||
|
|
There is currently no way to determine whether a given operating
|
|||
|
|
system is supported other than to try it.
|
|||
|
|
|