URL
https://opencores.org/ocsvn/or1k/or1k/trunk
Subversion Repositories or1k
[/] [or1k/] [trunk/] [insight/] [gdb/] [doc/] [gdb.info-8] - Rev 1774
Go to most recent revision | Compare with Previous | Blame | View Log
This is ./gdb.info, produced by makeinfo version 4.0 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 Ninth Edition, April 2001, of `Debugging with GDB: the
GNU Source-Level Debugger' for GDB Version 20010707.
Copyright (C)
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "A Sample GDB Session" and "Free Software",
with the Front-Cover texts being "A GNU Manual," and with the
Back-Cover Texts as in (a) below.
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
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 mode `!' Enable extended mode. In
extended mode, the remote
server is made persistent.
The `R' packet is used to
restart the program being
debugged.
reply `OK' The remote target both
supports and has enabled
extended mode.
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 program being
debugged. XX, while needed,
is ignored. This packet is
only available in extended
mode.
no reply The `R' packet has no reply.
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.
symbol lookup `qSymbol::' Notify the target that GDB is prepared to
serve symbol lookup requests. Accept
requests from the target for the values of
symbols.
reply `OK' The target does not need to look up any
(more) symbols.
reply The target requests the value of symbol
`qSymbol:'SYM_NAMESYM_NAME (hex encoded). GDB may provide
the value by using the
`qSymbol:'SYM_VALUE:SYM_NAME message,
described below.
symbol value `qSymbol:'SYM_VALUE:SYM_NAMESet the value of SYM_NAME to SYM_VALUE.
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 `OK' The target does not need to look up any
(more) symbols.
reply The target requests the value of a new
`qSymbol:'SYM_NAMEsymbol SYM_NAME (hex encoded). GDB will
continue to supply the values of symbols
(if available), until the target ceases to
request them.
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.
File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Targets, Up: Top
Configuration-Specific Information
**********************************
While nearly all GDB commands are available for all native and cross
versions of the debugger, there are some exceptions. This chapter
describes things that are only available in certain configurations.
There are three major categories of configurations: native
configurations, where the host and target are the same, embedded
operating system configurations, which are usually the same for several
different processor architectures, and bare embedded processors, which
are quite different from each other.
* Menu:
* Native::
* Embedded OS::
* Embedded Processors::
* Architectures::
File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations
Native
======
This section describes details specific to particular native
configurations.
* Menu:
* HP-UX:: HP-UX
* SVR4 Process Information:: SVR4 process information
File: gdb.info, Node: HP-UX, Next: SVR4 Process Information, Up: Native
HP-UX
-----
On HP-UX systems, if you refer to a function or variable name that
begins with a dollar sign, GDB searches for a user or system name
first, before it searches for a convenience variable.
File: gdb.info, Node: SVR4 Process Information, Prev: HP-UX, Up: Native
SVR4 process information
------------------------
Many versions of SVR4 provide a facility called `/proc' that can be
used to examine the image of a running process using file-system
subroutines. If GDB is configured for an operating system with this
facility, the command `info proc' is available to report on several
kinds of information about the process running your program. `info
proc' works only on SVR4 systems that include the `procfs' code. This
includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
HP-UX or Linux, for example.
`info proc'
Summarize available information about the process.
`info proc mappings'
Report on the address ranges accessible in the program, with
information on whether your program may read, write, or execute
each range.
`info proc times'
Starting time, user CPU time, and system CPU time for your program
and its children.
`info proc id'
Report on the process IDs related to your program: its own process
ID, the ID of its parent, the process group ID, and the session ID.
`info proc status'
General information on the state of the process. If the process is
stopped, this report includes the reason for stopping, and any
signal received.
`info proc all'
Show all the above information about the process.
File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations
Embedded Operating Systems
==========================
This section describes configurations involving the debugging of
embedded operating systems that are available for several different
architectures.
* Menu:
* VxWorks:: Using GDB with VxWorks
GDB includes the ability to debug programs running on various
real-time operating systems.
File: gdb.info, Node: VxWorks, Up: Embedded OS
Using GDB with VxWorks
----------------------
`target vxworks MACHINENAME'
A VxWorks system, attached via TCP/IP. The argument MACHINENAME
is the target system's machine name or IP address.
On VxWorks, `load' links FILENAME dynamically on the current target
system as well as adding its symbols in GDB.
GDB enables developers to spawn and debug tasks running on networked
VxWorks targets from a Unix host. Already-running tasks spawned from
the VxWorks shell can also be debugged. GDB uses code that runs on
both the Unix host and on the VxWorks target. The program `gdb' is
installed and executed on the Unix host. (It may be installed with the
name `vxgdb', to distinguish it from a GDB for debugging programs on
the host itself.)
`VxWorks-timeout ARGS'
All VxWorks-based targets now support the option `vxworks-timeout'.
This option is set by the user, and ARGS represents the number of
seconds GDB waits for responses to rpc's. You might use this if
your VxWorks target is a slow software simulator or is on the far
side of a thin network line.
The following information on connecting to VxWorks was current when
this manual was produced; newer releases of VxWorks may use revised
procedures.
To use GDB with VxWorks, you must rebuild your VxWorks kernel to
include the remote debugging interface routines in the VxWorks library
`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration
file `configAll.h' and rebuild your VxWorks kernel. The resulting
kernel contains `rdb.a', and spawns the source debugging task
`tRdbTask' when VxWorks is booted. For more information on configuring
and remaking VxWorks, see the manufacturer's manual.
Once you have included `rdb.a' in your VxWorks system image and set
your Unix execution search path to find GDB, you are ready to run GDB.
From your Unix host, run `gdb' (or `vxgdb', depending on your
installation).
GDB comes up showing the prompt:
(vxgdb)
* Menu:
* VxWorks Connection:: Connecting to VxWorks
* VxWorks Download:: VxWorks download
* VxWorks Attach:: Running tasks
File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks
Connecting to VxWorks
.....................
The GDB command `target' lets you connect to a VxWorks target on the
network. To connect to a target whose host name is "`tt'", type:
(vxgdb) target vxworks tt
GDB displays messages like these:
Attaching remote machine across net...
Connected to tt.
GDB then attempts to read the symbol tables of any object modules
loaded into the VxWorks target since it was last booted. GDB locates
these files by searching the directories listed in the command search
path (*note Your program's environment: Environment.); if it fails to
find an object file, it displays a message such as:
prog.o: No such file or directory.
When this happens, add the appropriate directory to the search path
with the GDB command `path', and execute the `target' command again.
File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks
VxWorks download
................
If you have connected to the VxWorks target and you want to debug an
object that has not yet been loaded, you can use the GDB `load' command
to download a file from Unix to VxWorks incrementally. The object file
given as an argument to the `load' command is actually opened twice:
first by the VxWorks target in order to download the code, then by GDB
in order to read the symbol table. This can lead to problems if the
current working directories on the two systems differ. If both systems
have NFS mounted the same filesystems, you can avoid these problems by
using absolute paths. Otherwise, it is simplest to set the working
directory on both systems to the directory in which the object file
resides, and then to reference the file by its name, without any path.
For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in
VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this
program, type this on VxWorks:
-> cd "VXPATH/vw/demo/rdb"
Then, in GDB, type:
(vxgdb) cd HOSTPATH/vw/demo/rdb
(vxgdb) load prog.o
GDB displays a response similar to this:
Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
You can also use the `load' command to reload an object module after
editing and recompiling the corresponding source file. Note that this
makes GDB delete all currently-defined breakpoints, auto-displays, and
convenience variables, and to clear the value history. (This is
necessary in order to preserve the integrity of debugger's data
structures that reference the target system's symbol table.)
File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks
Running tasks
.............
You can also attach to an existing task using the `attach' command as
follows:
(vxgdb) attach TASK
where TASK is the VxWorks hexadecimal task ID. The task can be running
or suspended when you attach to it. Running tasks are suspended at the
time of attachment.
File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations
Embedded Processors
===================
This section goes into details specific to particular embedded
configurations.
* Menu:
* A29K Embedded:: AMD A29K Embedded
* ARM:: ARM
* H8/300:: Hitachi H8/300
* H8/500:: Hitachi H8/500
* i960:: Intel i960
* M32R/D:: Mitsubishi M32R/D
* M68K:: Motorola M68K
* M88K:: Motorola M88K
* MIPS Embedded:: MIPS Embedded
* PA:: HP PA Embedded
* PowerPC: PowerPC
* SH:: Hitachi SH
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
* ST2000:: Tandem ST2000
* Z8000:: Zilog Z8000
Go to most recent revision | Compare with Previous | Blame | View Log