This is ./gdb.info, produced by makeinfo version 4.0b 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, January 2002, of `Debugging with GDB: the
GNU Source-Level Debugger' for GDB Version 5.1.1.

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998,
1999, 2000, 2001, 2002 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 "Free Software" and "Free Software Needs Free
Documentation", with the Front-Cover Texts being "A GNU Manual," and
with the Back-Cover Texts as in (a) below.

   (a) The Free Software Foundation'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          
               `qSymbol:'SYM_NAME
                              The target requests the value of symbol
                              SYM_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_NAME
                              Set 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          
               `qSymbol:'SYM_NAME
                              The target requests the value of a new
                              symbol 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
* DJGPP Native::                Features specific to the DJGPP port


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,  Next: DJGPP Native,  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: DJGPP Native,  Prev: SVR4 Process Information,  Up: Native

Features for Debugging DJGPP Programs
-------------------------------------

   DJGPP is the port of GNU development tools to MS-DOS and MS-Windows.
DJGPP programs are 32-bit protected-mode programs that use the "DPMI"
(DOS Protected-Mode Interface) API to run on top of real-mode DOS
systems and their emulations.

   GDB supports native debugging of DJGPP programs, and defines a few
commands specific to the DJGPP port.  This subsection describes those
commands.

`info dos'
     This is a prefix of DJGPP-specific commands which print
     information about the target system and important OS structures.

`info dos sysinfo'
     This command displays assorted information about the underlying
     platform: the CPU type and features, the OS version and flavor, the
     DPMI version, and the available conventional and DPMI memory.

`info dos gdt'
`info dos ldt'
`info dos idt'
     These 3 commands display entries from, respectively, Global, Local,
     and Interrupt Descriptor Tables (GDT, LDT, and IDT).  The
     descriptor tables are data structures which store a descriptor for
     each segment that is currently in use.  The segment's selector is
     an index into a descriptor table; the table entry for that index
     holds the descriptor's base address and limit, and its attributes
     and access rights.

     A typical DJGPP program uses 3 segments: a code segment, a data
     segment (used for both data and the stack), and a DOS segment
     (which allows access to DOS/BIOS data structures and absolute
     addresses in conventional memory).  However, the DPMI host will
     usually define additional segments in order to support the DPMI
     environment.

     These commands allow to display entries from the descriptor tables.
     Without an argument, all entries from the specified table are
     displayed.  An argument, which should be an integer expression,
     means display a single entry whose index is given by the argument.
     For example, here's a convenient way to display information about
     the debugged program's data segment:

     `(gdb) info dos ldt $ds'
     `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)'

     This comes in handy when you want to see whether a pointer is
     outside the data segment's limit (i.e. "garbled").

`info dos pde'
`info dos pte'
     These two commands display entries from, respectively, the Page
     Directory and the Page Tables.  Page Directories and Page Tables
     are data structures which control how virtual memory addresses are
     mapped into physical addresses.  A Page Table includes an entry
     for every page of memory that is mapped into the program's address
     space; there may be several Page Tables, each one holding up to
     4096 entries.  A Page Directory has up to 4096 entries, one each
     for every Page Table that is currently in use.

     Without an argument, `info dos pde' displays the entire Page
     Directory, and `info dos pte' displays all the entries in all of
     the Page Tables.  An argument, an integer expression, given to the
     `info dos pde' command means display only that entry from the Page
     Directory table.  An argument given to the `info dos pte' command
     means display entries from a single Page Table, the one pointed to
     by the specified entry in the Page Directory.

     These commands are useful when your program uses "DMA" (Direct
     Memory Access), which needs physical addresses to program the DMA
     controller.

     These commands are supported only with some DPMI servers.

`info dos address-pte ADDR'
     This command displays the Page Table entry for a specified linear
     address.  The argument linear address ADDR should already have the
     appropriate segment's base address added to it, because this
     command accepts addresses which may belong to _any_ segment.  For
     example, here's how to display the Page Table entry for the page
     where the variable `i' is stored:

     `(gdb) info dos address-pte __djgpp_base_address + (char *)&i'
     `Page Table entry for address 0x11a00d30:'
     `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30'

     This says that `i' is stored at offset `0xd30' from the page whose
     physical base address is `0x02698000', and prints all the
     attributes of that page.

     Note that you must cast the addresses of variables to a `char *',
     since otherwise the value of `__djgpp_base_address', the base
     address of all variables and functions in a DJGPP program, will be
     added using the rules of C pointer arithmetics: if `i' is declared
     an `int', GDB will add 4 times the value of `__djgpp_base_address'
     to the address of `i'.

     Here's another example, it displays the Page Table entry for the
     transfer buffer:

     `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)'
     `Page Table entry for address 0x29110:'
     `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110'

     (The `+ 3' offset is because the transfer buffer's address is the
     3rd member of the `_go32_info_block' structure.)  The output of
     this command clearly shows that addresses in conventional memory
     are mapped 1:1, i.e. the physical and linear addresses are
     identical.

     This command is supported only with some DPMI servers.


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.

