This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
the input file gdb.texinfo.

START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY
   This file documents the GNU debugger GDB.

   This is the Seventh Edition, February 1999, of `Debugging with GDB:
the GNU Source-Level Debugger' for GDB Version 4.18-xscale-010413.

   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: 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 `$', this is
followed by an optional two-digit SEQUENCE-ID and the character `:',
the actual PACKET-DATA, and the terminating character `#' followed by a
two-digit CHECKSUM:

     `$'PACKET-DATA`#'CHECKSUM

or, with the optional SEQUENCE-ID:
     `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM

The two-digit CHECKSUM is computed as the modulo 256 sum of all
characters between the leading `$' and the trailing `#' (that
consisting of both the optional SEQUENCE-ID`:' and the actual
PACKET-DATA) (an eight bit unsigned checksum).

The two-digit SEQUENCE-ID, when present, is returned with the
acknowledgment.  Beyond that its meaning is poorly defined.  GDB is not
known to output SEQUENCE-IDs.

   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
     -> `+'

If the received packet included a SEQUENCE-ID than that is appended to
a positive acknowledgment:

     <- `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
     -> `+'SEQUENCE-ID

   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 an exception). `:' can not appear as
the third character in a packet.  Fields within the packet should be
separated using `,' and `;' (unfortunately some packets chose to use
`:').  Except where otherwise noted all numbers are represented in HEX
with leading zeros suppressed.

   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.

   Below is a complete list of all currently defined COMMANDs and their
corresponding response DATA:

Packet                 Request                Description                   
extended ops           `!'                    Use the extended remote       
*(optional)*                                  protocol.  Sticky--only       
                                              needs to be set once.  The    
                                              extended remote protocol      
                                              support 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`,...'Initialized `argv[]' array    
*(reserved)*                                  passed into program. ARGLEN   
*(optional)*                                  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      
*(optional)*                                  (hex signal number).  If      
                                              `;'ADDR is omitted, resume    
                                              at same address.              
                       reply                  see below                     
toggle debug           `d'                    toggle debug flag.            
*(deprecated)*                                                              
detach *(optional)*    `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     
*(optional)*                                  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   
*(optional)*                                  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.         
*(optional)*                                                                
reserved               `j'                    Reserved for future use       
reserved               `J'                    Reserved for future use       
kill request           `k'                    FIXME: *There is no           
*(optional)*                                  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 *(optional)* `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.     
*(optional)*                                  In general GDB QUERY's 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.      
*(optional)*                                  See `q' for a discussing of   
                                              naming conventions.           
reset *(deprecated)*   `r'                    Reset the entire system.      
remote restart         `R'XX                  Restart the remote server.    
*(optional)*                                  XX while needed has no clear  
                                              definition.  FIXME: *An       
                                              example interaction           
                                              explaining how this packet    
                                              is used in extended-remote    
                                              mode is needed*.              
step *(optional)*      `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         
*(optional)*                                  continue.                     
                       reply                  see below                     
search *(optional)*    `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  
*(optional)*                                  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    
*(optional)*                                  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)*                                                        
*(optional)*                                                                
insert break or        `Z'T`,'ADDR`,'LENGTH   T is type: `0' - software     
watchpoint *(draft)*                          breakpoint, `1' - hardware    
*(optional)*                                  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             
                                              ident-potentent 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... = (`watch' | `rwatch' |       
                              `awatch'), R... = address of data access    
                              that caused target to stop for a            
                              watchpoint, 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`;'TTTTTTTT`;'DDDDDDDD`;'BBBBBBBBAA = signal number; TTTTTTTT = address of   
*(obsolete)*                  symbol "_start"; DDDDDDDD = base of data    
                              section; BBBBBBBB = 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.        
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 LIST or  `q'`L'STARTFLAGTHREADCOUNTNEXTTHREADObtain thread information from RTOS.        
THREADLIST                    Where: STARTFLAG (one hex digit) is one to  
*(deprecated)*                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.      
               reply          Where: COUNT (two hex digits) is the        
               `q'`M'COUNTDONEARGTHREADTHREAD...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()'. 
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'MODETHREADIDReturns information on THREADID.  Where:    
request                       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,'COMMANDCOMMAND (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.           
get            `q'`Waddr'     Get address of data access that caused      
watchpoint                    target to stop because of a watchpoint.     
data addr                     Zero if target stopped for some reason      
                              other than a watchpoint.                    
               reply `E'NN    An error (such as memory fault)             
               reply ADDR                                                 

   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...'
     <- `+'

   If you have trouble with the serial connection, you can use the
command `set remotedebug'.  This makes GDB report on all packets sent
back and forth across the serial line to the remote machine.  The
packet-debugging information is printed on the GDB standard output
stream.  `set remotedebug off' turns it off, and `show remotedebug'
shows you its current state.


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 {No Value For "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

