diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 2976 |
1 files changed, 2679 insertions, 297 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 7d77765..bfa9cc4 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -142,6 +142,7 @@ Copyright (C) 1988-1999 Free Software Foundation, Inc. * Altering:: Altering execution * GDB Files:: @value{GDBN} files * Targets:: Specifying a debugging target +* Configurations:: Configuration-specific information * Controlling GDB:: Controlling @value{GDBN} * Sequences:: Canned sequences of commands * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs @@ -1299,7 +1300,6 @@ kill a child process. * Input/Output:: Your program's input and output * Attach:: Debugging an already-running process * Kill Process:: Killing the child process -* Process Information:: Additional process information * Threads:: Debugging programs with multiple threads * Processes:: Debugging programs with multiple processes @@ -1691,51 +1691,6 @@ next type @code{run}, @value{GDBN} notices that the file has changed, and reads the symbol table again (while trying to preserve your current breakpoint settings). -@node Process Information -@section Additional process information - -@kindex /proc -@cindex process image - -Some operating systems provide a facility called @samp{/proc} that can -be used to examine the image of a running process using file-system -subroutines. If @value{GDBN} is configured for an operating system with this -facility, the command @code{info proc} is available to report on several -kinds of information about the process running your program. -@code{info proc} works only on SVR4 systems that support @code{procfs}. -This includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, -but not HP-UX or Linux, for example. - -@table @code -@kindex info proc -@item info proc -Summarize available information about the process. - -@kindex info proc mappings -@item 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. - -@kindex info proc times -@item info proc times -Starting time, user CPU time, and system CPU time for your program and -its children. - -@kindex info proc id -@item 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. - -@kindex info proc status -@item 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. - -@item info proc all -Show all the above information about the process. -@end table - @node Threads @section Debugging programs with multiple threads @@ -3392,7 +3347,6 @@ currently executing frame and describes it briefly, similar to the * Backtrace:: Backtraces * Selection:: Selecting a frame * Frame Info:: Information on a frame -* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack @end menu @@ -3684,40 +3638,6 @@ exception handlers, visit the associated frame (using the @code{up}, @end table -@node Alpha/MIPS Stack -@section MIPS/Alpha machines and the function stack - -@cindex stack on Alpha -@cindex stack on MIPS -@cindex Alpha stack -@cindex MIPS stack -Alpha- and MIPS-based computers use an unusual stack frame, which -sometimes requires @value{GDBN} to search backward in the object code to -find the beginning of a function. - -@cindex response time, MIPS debugging -To improve response time (especially for embedded applications, where -@value{GDBN} may be restricted to a slow serial line for this search) -you may want to limit the size of this search, using one of these -commands: - -@table @code -@cindex @code{heuristic-fence-post} (Alpha,MIPS) -@item set heuristic-fence-post @var{limit} -Restrict @value{GDBN} to examining at most @var{limit} bytes in its search -for the beginning of a function. A value of @var{0} (the default) -means there is no limit. However, except for @var{0}, the larger the -limit the more bytes @code{heuristic-fence-post} must search and -therefore the longer it takes to run. - -@item show heuristic-fence-post -Display the current limit. -@end table - -@noindent -These commands are available @emph{only} when @value{GDBN} is configured -for debugging programs on Alpha or MIPS processors. - @node Source @chapter Examining Source Files @@ -5226,27 +5146,6 @@ code generated by your compiler. If some registers are not saved, or if @value{GDBN} is unable to locate the saved registers, the selected stack frame makes no difference. -@table @code -@kindex set rstack_high_address -@cindex AMD 29K register stack -@cindex register stack, AMD29K -@item set rstack_high_address @var{address} -On AMD 29000 family processors, registers are saved in a separate -``register stack''. There is no way for @value{GDBN} to determine the extent -of this stack. Normally, @value{GDBN} just assumes that the stack is ``large -enough''. This may result in @value{GDBN} referencing memory locations that -do not exist. If necessary, you can get around this problem by -specifying the ending address of the register stack with the @code{set -rstack_high_address} command. The argument should be an address, which -you probably want to precede with @samp{0x} to specify in -hexadecimal. - -@kindex show rstack_high_address -@item show rstack_high_address -Display the current limit of the register stack, on AMD 29000 family -processors. -@end table - @node Floating Point Hardware @section Floating point hardware @cindex floating point @@ -5639,7 +5538,7 @@ language reference or tutorial. @menu * C:: C and C++ * Modula-2:: Modula-2 -* Chill:: Chill +* Chill:: Chill @end menu @node C @@ -6607,8 +6506,8 @@ This section covers the following Chill related topics and the features of @value{GDBN} which support these topics. @menu -* How modes are displayed:: How modes are displayed -* Locations:: Locations and their accesses +* How modes are displayed:: How modes are displayed +* Locations:: Locations and their accesses * Values and their Operations:: Values and their Operations * Chill type and range checks:: * Chill defaults:: @@ -8074,176 +7973,29 @@ it somewhere in memory where it won't get clobbered by the download. @kindex target sim @item target sim -CPU simulator. @xref{Simulator,,Simulated CPU Target}. +Builtin CPU simulator. GDB includes simulators for most architectures. +In general, +@example + target sim + load + run +@end example +works; however, you cannot assume that a specific memory map, device +drivers, or even basic I/O is available, although some simulator do +provide these. For info about any processor-specific simulator details, +see the appropriate section in @ref{Embedded Processors, ,Embedded +Processors}. + @end table -The following targets are all CPU-specific, and only available for -specific configurations. -@c should organize by CPU +Some configurations may include these targets as well: @table @code -@kindex target abug -@item target abug @var{dev} -ABug ROM monitor for M68K. - -@kindex target adapt -@item target adapt @var{dev} -Adapt monitor for A29K. - -@kindex target amd-eb -@item target amd-eb @var{dev} @var{speed} @var{PROG} -@cindex AMD EB29K -Remote PC-resident AMD EB29K board, attached over serial lines. -@var{dev} is the serial device, as for @code{target remote}; -@var{speed} allows you to specify the linespeed; and @var{PROG} is the -name of the program to be debugged, as it appears to DOS on the PC. -@xref{EB29K Remote, ,The EBMON protocol for AMD29K}. - -@kindex target array -@item target array @var{dev} -Array Tech LSI33K RAID controller board. - -@kindex target bug -@item target bug @var{dev} -BUG monitor, running on a MVME187 (m88k) board. - -@kindex target cpu32bug -@item target cpu32bug @var{dev} -CPU32BUG monitor, running on a CPU32 (M68K) board. - -@kindex target dbug -@item target dbug @var{dev} -dBUG ROM monitor for Motorola ColdFire. - -@kindex target ddb -@item target ddb @var{dev} -NEC's DDB monitor for Mips Vr4300. - -@kindex target dink32 -@item target dink32 @var{dev} -DINK32 ROM monitor for PowerPC. - -@kindex target e7000 -@item target e7000 @var{dev} -E7000 emulator for Hitachi H8 and SH. - -@kindex target es1800 -@item target es1800 @var{dev} -ES-1800 emulator for M68K. - -@kindex target est -@item target est @var{dev} -EST-300 ICE monitor, running on a CPU32 (M68K) board. - -@kindex target hms -@item target hms @var{dev} -A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. -Use special commands @code{device} and @code{speed} to control the serial -line and the communications speed used. -@xref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}. - -@kindex target lsi -@item target lsi @var{dev} -LSI ROM monitor for Mips. - -@kindex target m32r -@item target m32r @var{dev} -Mitsubishi M32R/D ROM monitor. - -@kindex target mips -@item target mips @var{dev} -IDT/SIM ROM monitor for Mips. - -@kindex target mon960 -@item target mon960 @var{dev} -MON960 monitor for Intel i960. - -@kindex target nindy -@item target nindy @var{devicename} -An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is -the name of the serial device to use for the connection, e.g. -@file{/dev/ttya}. @xref{i960-Nindy Remote, ,@value{GDBN} with a remote i960 (Nindy)}. - @kindex target nrom @item target nrom @var{dev} NetROM ROM emulator. This target only supports downloading. -@kindex target op50n -@item target op50n @var{dev} -OP50N monitor, running on an OKI HPPA board. - -@kindex target pmon -@item target pmon @var{dev} -PMON ROM monitor for Mips. - -@kindex target ppcbug -@item target ppcbug @var{dev} -@kindex target ppcbug1 -@item target ppcbug1 @var{dev} -PPCBUG ROM monitor for PowerPC. - -@kindex target r3900 -@item target r3900 @var{dev} -Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. - -@kindex target rdi -@item target rdi @var{dev} -ARM Angel monitor, via RDI library interface. - -@kindex target rdp -@item target rdp @var{dev} -ARM Demon monitor. - -@kindex target rom68k -@item target rom68k @var{dev} -ROM 68K monitor, running on an M68K IDP board. - -@kindex target rombug -@item target rombug @var{dev} -ROMBUG ROM monitor for OS/9000. - -@kindex target sds -@item target sds @var{dev} -SDS monitor, running on a PowerPC board (such as Motorola's ADS). - -@kindex target sparclite -@item target sparclite @var{dev} -Fujitsu sparclite boards, used only for the purpose of loading. -You must use an additional command to debug the program. -For example: target remote @var{dev} using @value{GDBN} standard -remote protocol. - -@kindex target sh3 -@kindex target sh3e -@item target sh3 @var{dev} -@item target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. - -@kindex target st2000 -@item target st2000 @var{dev} @var{speed} -A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. @var{dev} -is the name of the device attached to the ST2000 serial line; -@var{speed} is the communication line speed. The arguments are not used -if @value{GDBN} is configured to connect to the ST2000 using TCP or Telnet. -@xref{ST2000 Remote,,@value{GDBN} with a Tandem ST2000}. - -@kindex target udi -@item target udi @var{keyword} -Remote AMD29K target, using the AMD UDI protocol. The @var{keyword} -argument specifies which 29K board or simulator to use. @xref{UDI29K -Remote,,The UDI protocol for AMD29K}. - -@kindex target vxworks -@item target vxworks @var{machinename} -A VxWorks system, attached via TCP/IP. The argument @var{machinename} -is the target system's machine name or IP address. -@xref{VxWorks Remote, ,@value{GDBN} and VxWorks}. - -@kindex target w89k -@item target w89k @var{dev} -W89K monitor, running on a Winbond HPPA board. - @end table Different targets are available on different configurations of @value{GDBN}; @@ -8273,24 +8025,6 @@ link the program; for other formats, like a.out, the object file format specifies a fixed address. @c FIXME! This would be a good place for an xref to the GNU linker doc. -On VxWorks, @code{load} links @var{filename} dynamically on the -current target system as well as adding its symbols in @value{GDBN}. - -@cindex download to Nindy-960 -With the Nindy interface to an Intel 960 board, @code{load} -downloads @var{filename} to the 960 as well as adding its symbols in -@value{GDBN}. - -@cindex download to H8/300 or H8/500 -@cindex H8/300 or H8/500 download -@cindex download to Hitachi SH -@cindex Hitachi SH download -When you select remote debugging to a Hitachi SH, H8/300, or H8/500 board -(@pxref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}), -the @code{load} command downloads your program to the Hitachi board and also -opens it as the current executable target for @value{GDBN} on your host -(like the @code{file} command). - @code{load} does not repeat if you press @key{RET} again after using it. @end table @@ -8354,27 +8088,1173 @@ communicate with @value{GDBN}. Other remote targets may be available in your configuration of @value{GDBN}; use @code{help target} to list them. -@c Text on starting up GDB in various specific cases; it goes up front -@c in manuals configured for any of those particular situations, here -@c otherwise. @menu * Remote Serial:: @value{GDBN} remote serial protocol -* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) -* UDI29K Remote:: The UDI protocol for AMD29K -* EB29K Remote:: The EBMON protocol for AMD29K -* VxWorks Remote:: @value{GDBN} and VxWorks -* ST2000 Remote:: @value{GDBN} with a Tandem ST2000 -* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors -* MIPS Remote:: @value{GDBN} and MIPS boards -* Sparclet Remote:: @value{GDBN} and Sparclet boards -* Simulator:: Simulated CPU target @end menu -@include remote.texi +@node Remote Serial +@subsection The @value{GDBN} remote serial protocol + +@cindex remote serial debugging, overview +To debug a program running on another machine (the debugging +@dfn{target} machine), you must first arrange for all the usual +prerequisites for the program to run by itself. For example, for a C +program, you need: + +@enumerate +@item +A startup routine to set up the C runtime environment; these usually +have a name like @file{crt0}. The startup routine may be supplied by +your hardware supplier, or you may have to write your own. + +@item +You probably need a C subroutine library to support your program's +subroutine calls, notably managing input and output. + +@item +A way of getting your program to the other machine---for example, a +download program. These are often supplied by the hardware +manufacturer, but you may have to write your own from hardware +documentation. +@end enumerate + +The next step is to arrange for your program to use a serial port to +communicate with the machine where @value{GDBN} is running (the @dfn{host} +machine). In general terms, the scheme looks like this: + +@table @emph +@item On the host, +@value{GDBN} already understands how to use this protocol; when everything +else is set up, you can simply use the @samp{target remote} command +(@pxref{Targets,,Specifying a Debugging Target}). + +@item On the target, +you must link with your program a few special-purpose subroutines that +implement the @value{GDBN} remote serial protocol. The file containing these +subroutines is called a @dfn{debugging stub}. + +On certain remote targets, you can use an auxiliary program +@code{gdbserver} instead of linking a stub into your program. +@xref{Server,,Using the @code{gdbserver} program}, for details. +@end table + +The debugging stub is specific to the architecture of the remote +machine; for example, use @file{sparc-stub.c} to debug programs on +@sc{sparc} boards. + +@cindex remote serial stub list +These working remote stubs are distributed with @value{GDBN}: + +@table @code + +@item i386-stub.c +@kindex i386-stub.c +@cindex Intel +@cindex i386 +For Intel 386 and compatible architectures. + +@item m68k-stub.c +@kindex m68k-stub.c +@cindex Motorola 680x0 +@cindex m680x0 +For Motorola 680x0 architectures. + +@item sh-stub.c +@kindex sh-stub.c +@cindex Hitachi +@cindex SH +For Hitachi SH architectures. + +@item sparc-stub.c +@kindex sparc-stub.c +@cindex Sparc +For @sc{sparc} architectures. + +@item sparcl-stub.c +@kindex sparcl-stub.c +@cindex Fujitsu +@cindex SparcLite +For Fujitsu @sc{sparclite} architectures. + +@end table + +The @file{README} file in the @value{GDBN} distribution may list other +recently added stubs. + +@menu +* Stub Contents:: What the stub can do for you +* Bootstrapping:: What you must do for the stub +* Debug Session:: Putting it all together +* Protocol:: Definition of the communication protocol +* Server:: Using the `gdbserver' program +* NetWare:: Using the `gdbserve.nlm' program +@end menu + +@node Stub Contents +@subsubsection What the stub can do for you + +@cindex remote serial stub +The debugging stub for your architecture supplies these three +subroutines: + +@table @code +@item set_debug_traps +@kindex set_debug_traps +@cindex remote serial stub, initialization +This routine arranges for @code{handle_exception} to run when your +program stops. You must call this subroutine explicitly near the +beginning of your program. + +@item handle_exception +@kindex handle_exception +@cindex remote serial stub, main routine +This is the central workhorse, but your program never calls it +explicitly---the setup code arranges for @code{handle_exception} to +run when a trap is triggered. + +@code{handle_exception} takes control when your program stops during +execution (for example, on a breakpoint), and mediates communications +with @value{GDBN} on the host machine. This is where the communications +protocol is implemented; @code{handle_exception} acts as the @value{GDBN} +representative on the target machine; it begins by sending summary +information on the state of your program, then continues to execute, +retrieving and transmitting any information @value{GDBN} needs, until you +execute a @value{GDBN} command that makes your program resume; at that point, +@code{handle_exception} returns control to your own code on the target +machine. + +@item breakpoint +@cindex @code{breakpoint} subroutine, remote +Use this auxiliary subroutine to make your program contain a +breakpoint. Depending on the particular situation, this may be the only +way for @value{GDBN} to get control. For instance, if your target +machine has some sort of interrupt button, you won't need to call this; +pressing the interrupt button transfers control to +@code{handle_exception}---in effect, to @value{GDBN}. On some machines, +simply receiving characters on the serial port may also trigger a trap; +again, in that situation, you don't need to call @code{breakpoint} from +your own program---simply running @samp{target remote} from the host +@value{GDBN} session gets control. + +Call @code{breakpoint} if none of these is true, or if you simply want +to make certain your program stops at a predetermined point for the +start of your debugging session. +@end table + +@node Bootstrapping +@subsubsection What you must do for the stub + +@cindex remote stub, support routines +The debugging stubs that come with @value{GDBN} are set up for a particular +chip architecture, but they have no information about the rest of your +debugging target machine. + +First of all you need to tell the stub how to communicate with the +serial port. + +@table @code +@item int getDebugChar() +@kindex getDebugChar +Write this subroutine to read a single character from the serial port. +It may be identical to @code{getchar} for your target system; a +different name is used to allow you to distinguish the two if you wish. + +@item void putDebugChar(int) +@kindex putDebugChar +Write this subroutine to write a single character to the serial port. +It may be identical to @code{putchar} for your target system; a +different name is used to allow you to distinguish the two if you wish. +@end table + +@cindex control C, and remote debugging +@cindex interrupting remote targets +If you want @value{GDBN} to be able to stop your program while it is +running, you need to use an interrupt-driven serial driver, and arrange +for it to stop when it receives a @code{^C} (@samp{\003}, the control-C +character). That is the character which @value{GDBN} uses to tell the +remote system to stop. + +Getting the debugging target to return the proper status to @value{GDBN} +probably requires changes to the standard stub; one quick and dirty way +is to just execute a breakpoint instruction (the ``dirty'' part is that +@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). + +Other routines you need to supply are: + +@table @code +@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) +@kindex exceptionHandler +Write this function to install @var{exception_address} in the exception +handling tables. You need to do this because the stub does not have any +way of knowing what the exception handling tables on your target system +are like (for example, the processor's table might be in @sc{rom}, +containing entries which point to a table in @sc{ram}). +@var{exception_number} is the exception number which should be changed; +its meaning is architecture-dependent (for example, different numbers +might represent divide by zero, misaligned access, etc). When this +exception occurs, control should be transferred directly to +@var{exception_address}, and the processor state (stack, registers, +and so on) should be just as it is when a processor exception occurs. So if +you want to use a jump instruction to reach @var{exception_address}, it +should be a simple jump, not a jump to subroutine. + +For the 386, @var{exception_address} should be installed as an interrupt +gate so that interrupts are masked while the handler runs. The gate +should be at privilege level 0 (the most privileged level). The +@sc{sparc} and 68k stubs are able to mask interrupts themselves without +help from @code{exceptionHandler}. + +@item void flush_i_cache() +@kindex flush_i_cache +(sparc and sparclite only) Write this subroutine to flush the +instruction cache, if any, on your target machine. If there is no +instruction cache, this subroutine may be a no-op. + +On target machines that have instruction caches, @value{GDBN} requires this +function to make certain that the state of your program is stable. +@end table + +@noindent +You must also make sure this library routine is available: + +@table @code +@item void *memset(void *, int, int) +@kindex memset +This is the standard library function @code{memset} that sets an area of +memory to a known value. If you have one of the free versions of +@code{libc.a}, @code{memset} can be found there; otherwise, you must +either obtain it from your hardware manufacturer, or write your own. +@end table + +If you do not use the GNU C compiler, you may need other standard +library subroutines as well; this varies from one stub to another, +but in general the stubs are likely to use any of the common library +subroutines which @code{gcc} generates as inline code. + + +@node Debug Session +@subsubsection Putting it all together + +@cindex remote serial debugging summary +In summary, when your program is ready to debug, you must follow these +steps. + +@enumerate +@item +Make sure you have the supporting low-level routines +(@pxref{Bootstrapping,,What you must do for the stub}): +@display +@code{getDebugChar}, @code{putDebugChar}, +@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. +@end display + +@item +Insert these lines near the top of your program: + +@example +set_debug_traps(); +breakpoint(); +@end example + +@item +For the 680x0 stub only, you need to provide a variable called +@code{exceptionHook}. Normally you just use: + +@example +void (*exceptionHook)() = 0; +@end example + +but if before calling @code{set_debug_traps}, you set it to point to a +function in your program, that function is called when +@code{@value{GDBN}} continues after stopping on a trap (for example, bus +error). The function indicated by @code{exceptionHook} is called with +one parameter: an @code{int} which is the exception number. + +@item +Compile and link together: your program, the @value{GDBN} debugging stub for +your target architecture, and the supporting subroutines. + +@item +Make sure you have a serial connection between your target machine and +the @value{GDBN} host, and identify the serial port on the host. + +@item +@c The "remote" target now provides a `load' command, so we should +@c document that. FIXME. +Download your program to your target machine (or get it there by +whatever means the manufacturer provides), and start it. + +@item +To start remote debugging, run @value{GDBN} on the host machine, and specify +as an executable file the program that is running in the remote machine. +This tells @value{GDBN} how to find your program's symbols and the contents +of its pure text. + +@cindex serial line, @code{target remote} +Then establish communication using the @code{target remote} command. +Its argument specifies how to communicate with the target +machine---either via a devicename attached to a direct serial line, or a +TCP port (usually to a terminal server which in turn has a serial line +to the target). For example, to use a serial line connected to the +device named @file{/dev/ttyb}: + +@example +target remote /dev/ttyb +@end example + +@cindex TCP port, @code{target remote} +To use a TCP connection, use an argument of the form +@code{@var{host}:port}. For example, to connect to port 2828 on a +terminal server named @code{manyfarms}: + +@example +target remote manyfarms:2828 +@end example +@end enumerate + +Now you can use all the usual commands to examine and change data and to +step and continue the remote program. + +To resume the remote program and stop debugging it, use the @code{detach} +command. + +@cindex interrupting remote programs +@cindex remote programs, interrupting +Whenever @value{GDBN} is waiting for the remote program, if you type the +interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the +program. This may or may not succeed, depending in part on the hardware +and the serial drivers the remote system uses. If you type the +interrupt character once again, @value{GDBN} displays this prompt: + +@example +Interrupted while waiting for the program. +Give up (and stop debugging it)? (y or n) +@end example + +If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. +(If you decide you want to try again later, you can use @samp{target +remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} +goes back to waiting. + +@node Protocol +@subsubsection Communication protocol + +@cindex debugging stub, example +@cindex remote stub, example +@cindex stub example, remote debugging +The stub files provided with @value{GDBN} implement the target side of the +communication protocol, and the @value{GDBN} side is implemented in the +@value{GDBN} source file @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. @file{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 @value{GDBN}. + +In the examples below, @samp{<-} and @samp{->} are used to indicate +transmitted and received data respectfully. + +@cindex protocol, @value{GDBN} remote serial +@cindex serial protocol, @value{GDBN} remote +@cindex remote serial protocol +All @value{GDBN} commands and responses (other than acknowledgments) +are sent as a @var{packet}. A @var{packet} is introduced with the +character @samp{$}, this is followed by an optional two-digit +@var{sequence-id} and the character @samp{:}, the actual +@var{packet-data}, and the terminating character @samp{#} followed by a +two-digit @var{checksum}: + +@example +@code{$}@var{packet-data}@code{#}@var{checksum} +@end example +@noindent +or, with the optional @var{sequence-id}: +@example +@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} +@end example + +@cindex checksum, for @value{GDBN} remote +@noindent +The two-digit @var{checksum} is computed as the modulo 256 sum of all +characters between the leading @samp{$} and the trailing @samp{#} (that +consisting of both the optional @var{sequence-id}@code{:} and the actual +@var{packet-data}). + +@cindex sequence-id, for @value{GDBN} remote +@noindent +The two-digit @var{sequence-id}, when present, is returned with the +acknowledgment. Beyond that its meaning is poorly defined. +@value{GDBN} is not known to output @var{sequence-id}s. + +When either the host or the target machine receives a packet, the first +response expected is an acknowledgment: either @samp{+} (to indicate +the package was received correctly) or @samp{-} (to request +retransmission): + +@example +<- @code{$}@var{packet-data}@code{#}@var{checksum} +-> @code{+} +@end example +@noindent +If the received packet included a @var{sequence-id} than that is +appended to a positive acknowledgment: + +@example +<- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} +-> @code{+}@var{sequence-id} +@end example + +The host (@value{GDBN}) sends @var{command}s, and the target (the +debugging stub incorporated in your program) sends a @var{response}. In +the case of step and continue @var{command}s, the response is only sent +when the operation has completed (the target has again stopped). + +@var{packet-data} consists of a sequence of characters with the +exception of @samp{#} and @samp{$} (see @samp{X} packet for an +exception). @samp{:} can not appear as the third character in a packet. +Fields within the packet should be separated using @samp{,} and @samp{;} +(unfortunately some packets chose to use @samp{:}). Except where +otherwise noted all numbers are represented in HEX with leading zeros +suppressed. + +Response @var{data} can be run-length encoded to save space. A @samp{*} +means that the next character is an ASCII encoding giving a repeat count +which stands for that many repetitions of the character preceding the +@samp{*}. The encoding is @code{n+29}, yielding a printable character +where @code{n >=3} (which is where rle starts to win). Don't use an +@code{n > 126}. + +So: +@example +"@code{0* }" +@end example +@noindent +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 @var{command} not supported by the stub, an empty response +(@samp{$#00}) should be returned. That way it is possible to extend the +protocol. A newer @value{GDBN} can tell if a packet is supported based +on the response. + +Below is a complete list of all currently defined @var{command}s and +their corresponding response @var{data}: + +@multitable @columnfractions .30 .30 .40 +@item Packet +@tab Request +@tab Description + +@item extended ops @emph{(optional)} +@tab @code{!} +@tab +Use the extended remote protocol. Sticky -- only needs to be set once. +The extended remote protocol support the @samp{R} packet. +@item +@tab reply @samp{} +@tab +Stubs that support the extended remote protocol return @samp{} which, +unfortunately, is identical to the response returned by stubs that do not +support protocol extensions. + +@item last signal +@tab @code{?} +@tab +Reply the current reason for stopping. This is the same reply as is +generated for step or cont : @code{S}@var{AA} where @var{AA} is the +signal number. + +@item reserved +@tab @code{a} +@tab Reserved for future use + +@item set program arguments @strong{(reserved)} @emph{(optional)} +@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...} +@tab +Initialized @samp{argv[]} array passed into program. @var{arglen} +specifies the number of bytes in the hex encoded byte stream @var{arg}. +@item +@tab reply @code{OK} +@item +@tab reply @code{E}@var{NN} + +@item set baud @strong{(deprecated)} +@tab @code{b}@var{baud} +@tab +Change the serial line speed to @var{baud}. JTC: @emph{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: @emph{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.} + +@item set breakpoint @strong{(deprecated)} +@tab @code{B}@var{addr},@var{mode} +@tab +Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a +breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and +@samp{z} packets.} + +@item continue +@tab @code{c}@var{addr} +@tab +@var{addr} is address to resume. If @var{addr} is omitted, resume at +current address. +@item +@tab reply +@tab see below + +@item continue with signal @emph{(optional)} +@tab @code{C}@var{sig}@code{;}@var{addr} +@tab +Continue with signal @var{sig} (hex signal number). If +@code{;}@var{addr} is omitted, resume at same address. +@item +@tab reply +@tab see below + +@item toggle debug @emph{(optional)} +@tab @code{d} +@tab +toggle debug flag (see 386 & 68k stubs) + +@item detach @emph{(optional)} +@tab @code{D} +@tab Reply OK. + +@item reserved +@tab @code{e} +@tab Reserved for future use + +@item reserved +@tab @code{E} +@tab Reserved for future use + +@item reserved +@tab @code{f} +@tab Reserved for future use + +@item reserved +@tab @code{F} +@tab Reserved for future use + +@item read registers +@tab @code{g} +@tab Read general registers. +@item +@tab reply @var{XX...} +@tab +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 @samp{g} @var{packet} is +determined by the @var{REGISTER_RAW_SIZE} and @var{REGISTER_NAME} +macros. +@item +@tab @code{E}@var{NN} +@tab for an error. + +@item write regs +@tab @code{G}@var{XX...} +@tab +See @samp{g} for a description of the @var{XX...} data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item reserved +@tab @code{h} +@tab Reserved for future use + +@item set thread @emph{(optional)} +@tab @code{H}@var{c}@var{t...} +@tab +Set thread for subsequent operations. @var{c} = @samp{c} for thread +used in step and continue; @var{t...} can be -1 for all threads. +@var{c} = @samp{g} for thread used in other operations. If zero, pick a +thread, any thread. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item cycle step @strong{(draft)} @emph{(optional)} +@tab @code{i}@var{addr}@code{,}@var{nnn} +@tab +Step the remote target by a single clock cycle. If @code{,}@var{nnn} is +present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle +step starting at that address. + +@item signal then cycle step @strong{(reserved)} @emph{(optional)} +@tab @code{I} +@tab +See @samp{i} and @samp{S} for likely syntax and semantics. + +@item reserved +@tab @code{j} +@tab Reserved for future use + +@item reserved +@tab @code{J} +@tab Reserved for future use + +@item kill request @emph{(optional)} +@tab @code{k} +@tab + +@item reserved +@tab @code{l} +@tab Reserved for future use + +@item reserved +@tab @code{L} +@tab Reserved for future use + +@item read memory +@tab @code{m}@var{addr}@code{,}@var{length} +@tab +Read @var{length} bytes of memory starting at address @var{addr}. +@item +@tab reply @var{XX...} +@tab +@var{XX...} is mem contents. Can be fewer bytes than requested if able to +read only part of the data. +@item +@tab reply @code{E}@var{NN} +@tab @var{NN} is errno + +@item write mem +@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...} +@tab +Write @var{length} bytes of memory starting at address @var{addr}. +@var{XX...} is the data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab +for an error (this includes the case where only part of the data was +written). + +@item reserved +@tab @code{n} +@tab Reserved for future use + +@item reserved +@tab @code{N} +@tab Reserved for future use + +@item reserved +@tab @code{o} +@tab Reserved for future use + +@item reserved +@tab @code{O} +@tab Reserved for future use + +@item read reg @strong{(reserved)} +@tab @code{p}@var{n...} +@tab +See write register. +@item +@tab return @var{r....} +@tab The hex encoded value of the register in target byte order. + +@item write reg @emph{(optional)} +@tab @code{P}@var{n...}@code{=}@var{r...} +@tab +Write register @var{n...} with value @var{r...}, which contains two hex +digits for each byte in the register (target byte order). +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item general query @emph{(optional)} +@tab @code{q}@var{query} +@tab +Request info about @var{query}. In general @value{GDBN} @var{query}'s +have a leading upper case letter. Custom vendor queries should use a +leading lower case letter and a company prefix, ex: @samp{qfsf.var}. +@var{query} may optionally be followed by a @samp{,} or @samp{;} +separated list. Stubs should ensure that they fully match any +@var{query} name. +@item +@tab reply @code{XX...} +@tab Hex encoded data from query. The reply can not be empty. +@item +@tab reply @code{E}@var{NN} +@tab error reply +@item +@tab reply @samp{} +@tab Indicating an unrecognized @var{query}. + +@item current thread +@tab @code{q}@code{C} +@tab Return the current thread id. +@item +@tab reply @code{QC}@var{pid} +@tab +Where @var{pid} is a HEX encoded 16 bit process id. +@item +@tab reply * +@tab Any other reply implies the old pid. + +@item compute CRC of memory block +@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length} +@tab +@item +@tab reply @code{E}@var{NN} +@tab An error (such as memory fault) +@item +@tab reply @code{C}@var{CRC32} +@tab A 32 bit cyclic redundancy check of the specified memory region. + +@item query @var{LIST} or @var{threadLIST} +@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} +@tab +Obtain thread information from RTOS. @var{startflag} is one hex digit; +@var{threadcount} is two hex digits; and @var{nextthread} is 16 hex +digits. +@item +@tab reply * +@tab +See @code{remote.c:parse_threadlist_response()}. + +@item query sect offs +@tab @code{q}@code{Offsets} +@tab Get section offsets. +@item +@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} + +@item thread info request +@tab @code{q}@code{P}@var{mode}@var{threadid} +@tab +Returns information on @var{threadid}. Where: @var{mode} is a hex +encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. +@item +@tab reply * +@tab +See @code{remote.c:remote_unpack_thread_info_response()}. + +@item remote command +@tab @code{q}@code{Rcmd,}@var{COMMAND} +@tab +@var{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 @code{O}@var{OUTPUT} console output +packets. @emph{Implementors should note that providing access to a +stubs's interpreter may have security implications}. +@item +@tab reply @code{OK} +@tab +A command response with no output. +@item +@tab reply @var{OUTPUT} +@tab +A command response with the hex encoded output string @var{OUTPUT}. +@item +@tab reply @code{E}@var{NN} +@tab +Indicate a badly formed request. + +@item +@tab reply @samp{} +@tab +When @samp{q}@samp{Rcmd} is not recognized. + +@item general set @emph{(optional)} +@tab @code{Q}@var{var}@code{=}@var{val} +@tab +Set value of @var{var} to @var{val}. See @samp{q} for a discussing of +naming conventions. + +@item reset @emph{(optional)} +@tab r +@tab reset -- see sparc stub. + +@item remote restart @emph{(optional)} +@tab @code{R}@var{XX} +@tab +Restart the remote server. @var{XX} while needed has no clear +definition. + +@item step @emph{(optional)} +@tab @code{s}@var{addr} +@tab +@var{addr} is address to resume. If @var{addr} is omitted, resume at +same address. +@item +@tab reply +@tab see below + +@item step with signal @emph{(optional)} +@tab @code{S}@var{sig}@code{;}@var{addr} +@tab +Like @samp{C} but step not continue. +@item +@tab reply +@tab see below + +@item search @emph{(optional)} +@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} +@tab +Search backwards starting at address @var{addr} for a match with pattern +@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 +bytes. @var{addr} must be at least 3 digits. + +@item thread alive @emph{(optional)} +@tab @code{T}@var{XX} +@tab Find out if the thread XX is alive. +@item +@tab reply @code{OK} +@tab thread is still alive +@item +@tab reply @code{E}@var{NN} +@tab thread is dead + +@item reserved +@tab @code{u} +@tab Reserved for future use + +@item reserved +@tab @code{U} +@tab Reserved for future use + +@item reserved +@tab @code{v} +@tab Reserved for future use + +@item reserved +@tab @code{V} +@tab Reserved for future use + +@item reserved +@tab @code{w} +@tab Reserved for future use + +@item reserved +@tab @code{W} +@tab Reserved for future use + +@item reserved +@tab @code{x} +@tab Reserved for future use + +@item write mem (binary) @emph{(optional)} +@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...} +@tab +@var{addr} is address, @var{length} is number of bytes, @var{XX...} is +binary data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item reserved +@tab @code{y} +@tab Reserved for future use + +@item reserved +@tab @code{Y} +@tab Reserved for future use + +@item remove break or watchpoint @strong{(draft)} @emph{(optional)} +@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} +@tab +See @samp{Z}. + +@item insert break or watchpoint @strong{(draft)} @emph{(optional)} +@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} +@tab +@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware +breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, +@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in +bytes. For a software breakpoint, @var{length} specifies the size of +the instruction to be patched. For hardware breakpoints and watchpoints +@var{length} specifies the memory region to be monitored. +@item +@tab reply @code{E}@var{NN} +@tab for an error +@item +@tab reply @code{OK} +@tab for success +@item +@tab @samp{} +@tab If not supported. + +@item reserved +@tab <other> +@tab Reserved for future use + +@end multitable + +In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets, +there is no immediate response. The reply, described below, comes when +the machine stops: + +@multitable @columnfractions .4 .6 + +@item @code{S}@var{AA} +@tab @var{AA} is the signal number + +@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} +@tab +@var{AA} = two hex digit signal number; @var{n...} = register number +(hex), @var{r...} = target byte ordered register contents, size defined +by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = +thread process ID, this is a hex integer; @var{n...} = other string not +starting with valid hex digit. @value{GDBN} should ignore this +@var{n...}, @var{r...} pair and go on to the next. This way we can +extend the protocol. + +@item @code{W}@var{AA} +@tab +The process exited, and @var{AA} is the exit status. This is only +applicable for certains sorts of targets. + +@item @code{X}@var{AA} +@tab +The process terminated with signal @var{AA}. + +@item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)} +@tab +@var{AA} = signal number; @var{tttttttt} = address of symbol "_start"; +@var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss +section. @emph{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.} + +@item @code{O}@var{XX...} +@tab +@var{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. + +@end multitable + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + +@example +<- @code{R00} +-> @code{+} +@emph{target restarts} +<- @code{?} +-> @code{+} +-> @code{T001:1234123412341234} +<- @code{+} +@end example + +Example sequence of a target being stepped by a single instruction: + +@example +<- @code{G1445...} +-> @code{+} +<- @code{s} +-> @code{+} +@emph{time passes} +-> @code{T001:1234123412341234} +<- @code{+} +<- @code{g} +-> @code{+} +-> @code{1455...} +<- @code{+} +@end example + +@kindex set remotedebug +@kindex show remotedebug +@cindex packets, reporting on stdout +@cindex serial connections, debugging +If you have trouble with the serial connection, you can use the command +@code{set remotedebug}. This makes @value{GDBN} report on all packets sent +back and forth across the serial line to the remote machine. The +packet-debugging information is printed on the @value{GDBN} standard output +stream. @code{set remotedebug off} turns it off, and @code{show +remotedebug} shows you its current state. + +@node Server +@subsubsection Using the @code{gdbserver} program + +@kindex gdbserver +@cindex remote connection without stubs +@code{gdbserver} is a control program for Unix-like systems, which +allows you to connect your program with a remote @value{GDBN} via +@code{target remote}---but without linking in the usual debugging stub. + +@code{gdbserver} is not a complete replacement for the debugging stubs, +because it requires essentially the same operating-system facilities +that @value{GDBN} itself does. In fact, a system that can run +@code{gdbserver} to connect to a remote @value{GDBN} could also run +@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, +because it is a much smaller program than @value{GDBN} itself. It is +also easier to port than all of @value{GDBN}, so you may be able to get +started more quickly on a new system by using @code{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 @code{gdbserver} to make a similar +choice for debugging. + +@value{GDBN} and @code{gdbserver} communicate via either a serial line +or a TCP connection, using the standard @value{GDBN} remote serial +protocol. + +@table @emph +@item On the target machine, +you need to have a copy of the program you want to debug. +@code{gdbserver} does not need your program's symbol table, so you can +strip the program if necessary to save space. @value{GDBN} on the host +system does all the symbol handling. + +To use the server, you must tell it how to communicate with @value{GDBN}; +the name of your program; and the arguments for your program. The +syntax is: + +@smallexample +target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] +@end smallexample + +@var{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 +@samp{foo.txt} and communicate with @value{GDBN} over the serial port +@file{/dev/com1}: + +@smallexample +target> gdbserver /dev/com1 emacs foo.txt +@end smallexample + +@code{gdbserver} waits passively for the host @value{GDBN} to communicate +with it. +To use a TCP connection instead of a serial line: + +@smallexample +target> gdbserver host:2345 emacs foo.txt +@end smallexample + +The only difference from the previous example is the first argument, +specifying that you are communicating with the host @value{GDBN} via +TCP. The @samp{host:2345} argument means that @code{gdbserver} is to +expect a TCP connection from machine @samp{host} to local TCP port 2345. +(Currently, the @samp{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, @code{23} is +reserved for @code{telnet}).@footnote{If you choose a port number that +conflicts with another service, @code{gdbserver} prints an error message +and exits.} You must use the same port number with the host @value{GDBN} +@code{target remote} command. + +@item On the @value{GDBN} host machine, +you need an unstripped copy of your program, since @value{GDBN} needs +symbols and debugging information. Start up @value{GDBN} as usual, +using the name of the local copy of your program as the first argument. +(You may also need the @w{@samp{--baud}} option if the serial line is +running at anything other than 9600 bps.) After that, use @code{target +remote} to establish communications with @code{gdbserver}. Its argument +is either a device name (usually a serial device, like +@file{/dev/ttyb}), or a TCP port descriptor in the form +@code{@var{host}:@var{PORT}}. For example: + +@smallexample +(@value{GDBP}) target remote /dev/ttyb +@end smallexample + +@noindent +communicates with the server via serial line @file{/dev/ttyb}, and + +@smallexample +(@value{GDBP}) target remote the-target:2345 +@end smallexample + +@noindent +communicates via a TCP connection to port 2345 on host @w{@file{the-target}}. +For TCP connections, you must start up @code{gdbserver} prior to using +the @code{target remote} command. Otherwise you may get an error whose +text depends on the host system, but which usually looks something like +@samp{Connection refused}. +@end table + +@node NetWare +@subsubsection Using the @code{gdbserve.nlm} program + +@kindex gdbserve.nlm +@code{gdbserve.nlm} is a control program for NetWare systems, which +allows you to connect your program with a remote @value{GDBN} via +@code{target remote}. + +@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line, +using the standard @value{GDBN} remote serial protocol. + +@table @emph +@item On the target machine, +you need to have a copy of the program you want to debug. +@code{gdbserve.nlm} does not need your program's symbol table, so you +can strip the program if necessary to save space. @value{GDBN} on the +host system does all the symbol handling. + +To use the server, you must tell it how to communicate with +@value{GDBN}; the name of your program; and the arguments for your +program. The syntax is: + +@smallexample +load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ] + [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ] +@end smallexample + +@var{board} and @var{port} specify the serial line; @var{baud} specifies +the baud rate used by the connection. @var{port} and @var{node} default +to 0, @var{baud} defaults to 9600 bps. + +For example, to debug Emacs with the argument @samp{foo.txt}and +communicate with @value{GDBN} over serial port number 2 or board 1 +using a 19200 bps connection: + +@smallexample +load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt +@end smallexample + +@item On the @value{GDBN} host machine, +you need an unstripped copy of your program, since @value{GDBN} needs +symbols and debugging information. Start up @value{GDBN} as usual, +using the name of the local copy of your program as the first argument. +(You may also need the @w{@samp{--baud}} option if the serial line is +running at anything other than 9600 bps. After that, use @code{target +remote} to establish communications with @code{gdbserve.nlm}. Its +argument is a device name (usually a serial device, like +@file{/dev/ttyb}). For example: + +@smallexample +(@value{GDBP}) target remote /dev/ttyb +@end smallexample + +@noindent +communications with the server via serial line @file{/dev/ttyb}. +@end table @node KOD @section Kernel Object Display + @cindex kernel object display @cindex kernel object @cindex KOD @@ -8411,6 +9291,1508 @@ There is currently no way to determine whether a given operating system is supported other than to try it. +@node Configurations +@chapter Configuration-Specific Information + +While nearly all @value{GDBN} 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:: +@end menu + +@node Native +@section Native + +This section describes details specific to particular native +configurations. + +@menu +* HP-UX:: HP-UX +* SVR4 Process Information:: SVR4 process information +@end menu + +@node HP-UX +@subsection HP-UX + +On HP-UX systems, if you refer to a function or variable name that +begins with a dollar sign, @value{GDBN} searches for a user or system +name first, before it searches for a convenience variable. + +@node SVR4 Process Information +@subsection SVR4 process information + +@kindex /proc +@cindex process image + +Many versions of SVR4 provide a facility called @samp{/proc} that can be +used to examine the image of a running process using file-system +subroutines. If @value{GDBN} is configured for an operating system with +this facility, the command @code{info proc} is available to report on +several kinds of information about the process running your program. +@code{info proc} works only on SVR4 systems that include the +@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix, +and Unixware, but not HP-UX or Linux, for example. + +@table @code +@kindex info proc +@item info proc +Summarize available information about the process. + +@kindex info proc mappings +@item 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. + +@kindex info proc times +@item info proc times +Starting time, user CPU time, and system CPU time for your program and +its children. + +@kindex info proc id +@item 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. + +@kindex info proc status +@item 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. + +@item info proc all +Show all the above information about the process. +@end table + +@node Embedded OS +@section Embedded Operating Systems + +This section describes configurations involving the debugging of +embedded operating systems that are available for several different +architectures. + +@menu +* VxWorks:: Using @value{GDBN} with VxWorks +@end menu + +@value{GDBN} includes the ability to debug programs running on +various real-time operating systems. + +@node VxWorks +@subsection Using @value{GDBN} with VxWorks + +@cindex VxWorks + +@table @code + +@kindex target vxworks +@item target vxworks @var{machinename} +A VxWorks system, attached via TCP/IP. The argument @var{machinename} +is the target system's machine name or IP address. + +@end table + +On VxWorks, @code{load} links @var{filename} dynamically on the +current target system as well as adding its symbols in @value{GDBN}. + +@value{GDBN} 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. @value{GDBN} uses code that runs on +both the Unix host and on the VxWorks target. The program +@code{gdb} is installed and executed on the Unix host. (It may be +installed with the name @code{vxgdb}, to distinguish it from a +@value{GDBN} for debugging programs on the host itself.) + +@table @code +@item VxWorks-timeout @var{args} +@kindex vxworks-timeout +All VxWorks-based targets now support the option @code{vxworks-timeout}. +This option is set by the user, and @var{args} represents the number of +seconds @value{GDBN} 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. +@end table + +The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. + +@kindex INCLUDE_RDB +To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel +to include the remote debugging interface routines in the VxWorks +library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the +VxWorks configuration file @file{configAll.h} and rebuild your VxWorks +kernel. The resulting kernel contains @file{rdb.a}, and spawns the +source debugging task @code{tRdbTask} when VxWorks is booted. For more +information on configuring and remaking VxWorks, see the manufacturer's +manual. +@c VxWorks, see the @cite{VxWorks Programmer's Guide}. + +Once you have included @file{rdb.a} in your VxWorks system image and set +your Unix execution search path to find @value{GDBN}, you are ready to +run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb}, +depending on your installation). + +@value{GDBN} comes up showing the prompt: + +@example +(vxgdb) +@end example + +@menu +* VxWorks Connection:: Connecting to VxWorks +* VxWorks Download:: VxWorks download +* VxWorks Attach:: Running tasks +@end menu + +@node VxWorks Connection +@subsubsection Connecting to VxWorks + +The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the +network. To connect to a target whose host name is ``@code{tt}'', type: + +@example +(vxgdb) target vxworks tt +@end example + +@need 750 +@value{GDBN} displays messages like these: + +@smallexample +Attaching remote machine across net... +Connected to tt. +@end smallexample + +@need 1000 +@value{GDBN} then attempts to read the symbol tables of any object modules +loaded into the VxWorks target since it was last booted. @value{GDBN} locates +these files by searching the directories listed in the command search +path (@pxref{Environment, ,Your program's environment}); if it fails +to find an object file, it displays a message such as: + +@example +prog.o: No such file or directory. +@end example + +When this happens, add the appropriate directory to the search path with +the @value{GDBN} command @code{path}, and execute the @code{target} +command again. + +@node VxWorks Download +@subsubsection VxWorks download + +@cindex download to VxWorks +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 @value{GDBN} +@code{load} command to download a file from Unix to VxWorks +incrementally. The object file given as an argument to the @code{load} +command is actually opened twice: first by the VxWorks target in order +to download the code, then by @value{GDBN} 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 +@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks +and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this +program, type this on VxWorks: + +@example +-> cd "@var{vxpath}/vw/demo/rdb" +@end example +v +Then, in @value{GDBN}, type: + +@example +(vxgdb) cd @var{hostpath}/vw/demo/rdb +(vxgdb) load prog.o +@end example + +@value{GDBN} displays a response similar to this: + +@smallexample +Reading symbol data from wherever/vw/demo/rdb/prog.o... done. +@end smallexample + +You can also use the @code{load} command to reload an object module +after editing and recompiling the corresponding source file. Note that +this makes @value{GDBN} 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 data structures that reference the target system's symbol +table.) + +@node VxWorks Attach +@subsubsection Running tasks + +@cindex running VxWorks tasks +You can also attach to an existing task using the @code{attach} command as +follows: + +@example +(vxgdb) attach @var{task} +@end example + +@noindent +where @var{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. + +@node Embedded Processors +@section 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 +@end menu + +@node A29K Embedded +@subsection AMD A29K Embedded + +@menu +* A29K UDI:: +* A29K EB29K:: +* Comms (EB29K):: Communications setup +* gdb-EB29K:: EB29K cross-debugging +* Remote Log:: Remote log +@end menu + +@table @code + +@kindex target adapt +@item target adapt @var{dev} +Adapt monitor for A29K. + +@kindex target amd-eb +@item target amd-eb @var{dev} @var{speed} @var{PROG} +@cindex AMD EB29K +Remote PC-resident AMD EB29K board, attached over serial lines. +@var{dev} is the serial device, as for @code{target remote}; +@var{speed} allows you to specify the linespeed; and @var{PROG} is the +name of the program to be debugged, as it appears to DOS on the PC. +@xref{A29K EB29K, ,EBMON protocol for AMD29K}. + +@end table + +@node A29K UDI +@subsubsection A29K UDI + +@cindex UDI +@cindex AMD29K via UDI + +@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'') +protocol for debugging the a29k processor family. To use this +configuration with AMD targets running the MiniMON monitor, you need the +program @code{MONTIP}, available from AMD at no charge. You can also +use @value{GDBN} with the UDI-conformant a29k simulator program +@code{ISSTIP}, also available from AMD. + +@table @code +@item target udi @var{keyword} +@kindex udi +Select the UDI interface to a remote a29k board or simulator, where +@var{keyword} is an entry in the AMD configuration file @file{udi_soc}. +This file contains keyword entries which specify parameters used to +connect to a29k targets. If the @file{udi_soc} file is not in your +working directory, you must set the environment variable @samp{UDICONF} +to its pathname. +@end table + +@node A29K EB29K +@subsubsection EBMON protocol for AMD29K + +@cindex EB29K board +@cindex running 29K programs + +AMD distributes a 29K development board meant to fit in a PC, together +with a DOS-hosted monitor program called @code{EBMON}. As a shorthand +term, this development system is called the ``EB29K''. To use +@value{GDBN} from a Unix system to run programs on the EB29K board, you +must first connect a serial cable between the PC (which hosts the EB29K +board) and a serial port on the Unix system. In the following, we +assume you've hooked the cable between the PC's @file{COM1} port and +@file{/dev/ttya} on the Unix system. + +@node Comms (EB29K) +@subsubsection Communications setup + +The next step is to set up the PC's port, by doing something like this +in DOS on the PC: + +@example +C:\> MODE com1:9600,n,8,1,none +@end example + +@noindent +This example---run on an MS DOS 4.0 system---sets the PC port to 9600 +bps, no parity, eight data bits, one stop bit, and no ``retry'' action; +you must match the communications parameters when establishing the Unix +end of the connection as well. +@c FIXME: Who knows what this "no retry action" crud from the DOS manual may +@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91 + +To give control of the PC to the Unix side of the serial line, type +the following at the DOS console: + +@example +C:\> CTTY com1 +@end example + +@noindent +(Later, if you wish to return control to the DOS console, you can use +the command @code{CTTY con}---but you must send it over the device that +had control, in our example over the @file{COM1} serial line). + +From the Unix host, use a communications program such as @code{tip} or +@code{cu} to communicate with the PC; for example, + +@example +cu -s 9600 -l /dev/ttya +@end example + +@noindent +The @code{cu} options shown specify, respectively, the linespeed and the +serial port to use. If you use @code{tip} instead, your command line +may look something like the following: + +@example +tip -9600 /dev/ttya +@end example + +@noindent +Your system may require a different name where we show +@file{/dev/ttya} as the argument to @code{tip}. The communications +parameters, including which port to use, are associated with the +@code{tip} argument in the ``remote'' descriptions file---normally the +system table @file{/etc/remote}. +@c FIXME: What if anything needs doing to match the "n,8,1,none" part of +@c the DOS side's comms setup? cu can support -o (odd +@c parity), -e (even parity)---apparently no settings for no parity or +@c for character size. Taken from stty maybe...? John points out tip +@c can set these as internal variables, eg ~s parity=none; man stty +@c suggests that it *might* work to stty these options with stdin or +@c stdout redirected... ---doc@cygnus.com, 25feb91 + +@kindex EBMON +Using the @code{tip} or @code{cu} connection, change the DOS working +directory to the directory containing a copy of your 29K program, then +start the PC program @code{EBMON} (an EB29K control program supplied +with your board by AMD). You should see an initial display from +@code{EBMON} similar to the one that follows, ending with the +@code{EBMON} prompt @samp{#}--- + +@example +C:\> G: + +G:\> CD \usr\joe\work29k + +G:\USR\JOE\WORK29K> EBMON +Am29000 PC Coprocessor Board Monitor, version 3.0-18 +Copyright 1990 Advanced Micro Devices, Inc. +Written by Gibbons and Associates, Inc. + +Enter '?' or 'H' for help + +PC Coprocessor Type = EB29K +I/O Base = 0x208 +Memory Base = 0xd0000 + +Data Memory Size = 2048KB +Available I-RAM Range = 0x8000 to 0x1fffff +Available D-RAM Range = 0x80002000 to 0x801fffff + +PageSize = 0x400 +Register Stack Size = 0x800 +Memory Stack Size = 0x1800 + +CPU PRL = 0x3 +Am29027 Available = No +Byte Write Available = Yes + +# ~. +@end example + +Then exit the @code{cu} or @code{tip} program (done in the example by +typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps +running, ready for @value{GDBN} to take over. + +For this example, we've assumed what is probably the most convenient +way to make sure the same 29K program is on both the PC and the Unix +system: a PC/NFS connection that establishes ``drive @code{G:}'' on the +PC as a file system on the Unix host. If you do not have PC/NFS or +something similar connecting the two systems, you must arrange some +other way---perhaps floppy-disk transfer---of getting the 29K program +from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the +serial line. + +@node gdb-EB29K +@subsubsection EB29K cross-debugging + +Finally, @code{cd} to the directory containing an image of your 29K +program on the Unix system, and start @value{GDBN}---specifying as argument the +name of your 29K program: + +@example +cd /usr/joe/work29k +@value{GDBP} myfoo +@end example + +@need 500 +Now you can use the @code{target} command: + +@example +target amd-eb /dev/ttya 9600 MYFOO +@c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to +@c emphasize that this is the name as seen by DOS (since I think DOS is +@c single-minded about case of letters). ---doc@cygnus.com, 25feb91 +@end example + +@noindent +In this example, we've assumed your program is in a file called +@file{myfoo}. Note that the filename given as the last argument to +@code{target amd-eb} should be the name of the program as it appears to DOS. +In our example this is simply @code{MYFOO}, but in general it can include +a DOS path, and depending on your transfer mechanism may not resemble +the name on the Unix side. + +At this point, you can set any breakpoints you wish; when you are ready +to see your program run on the 29K board, use the @value{GDBN} command +@code{run}. + +To stop debugging the remote program, use the @value{GDBN} @code{detach} +command. + +To return control of the PC to its console, use @code{tip} or @code{cu} +once again, after your @value{GDBN} session has concluded, to attach to +@code{EBMON}. You can then type the command @code{q} to shut down +@code{EBMON}, returning control to the DOS command-line interpreter. +Type @code{CTTY con} to return command input to the main DOS console, +and type @kbd{~.} to leave @code{tip} or @code{cu}. + +@node Remote Log +@subsubsection Remote log +@kindex eb.log +@cindex log file for EB29K + +The @code{target amd-eb} command creates a file @file{eb.log} in the +current working directory, to help debug problems with the connection. +@file{eb.log} records all the output from @code{EBMON}, including echoes +of the commands sent to it. Running @samp{tail -f} on this file in +another window often helps to understand trouble with @code{EBMON}, or +unexpected events on the PC side of the connection. + +@node ARM +@subsection ARM + +@table @code + +@kindex target rdi +@item target rdi @var{dev} +ARM Angel monitor, via RDI library interface to ADP protocol. You may +use this target to communicate with both boards running the Angel +monitor, or with the EmbeddedICE JTAG debug device. + +@kindex target rdp +@item target rdp @var{dev} +ARM Demon monitor. + +@end table + +@node H8/300 +@subsection Hitachi H8/300 + +@table @code + +@kindex target hms +@item target hms @var{dev} +A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. +Use special commands @code{device} and @code{speed} to control the serial +line and the communications speed used. + +@kindex target e7000 +@item target e7000 @var{dev} +E7000 emulator for Hitachi H8 and SH. + +@kindex target sh3 +@kindex target sh3e +@item target sh3 @var{dev} +@item target sh3e @var{dev} +Hitachi SH-3 and SH-3E target systems. + +@end table + +@cindex download to H8/300 or H8/500 +@cindex H8/300 or H8/500 download +@cindex download to Hitachi SH +@cindex Hitachi SH download +When you select remote debugging to a Hitachi SH, H8/300, or H8/500 +board, the @code{load} command downloads your program to the Hitachi +board and also opens it as the current executable target for +@value{GDBN} on your host (like the @code{file} command). + +@value{GDBN} needs to know these things to talk to your +Hitachi SH, H8/300, or H8/500: + +@enumerate +@item +that you want to use @samp{target hms}, the remote debugging interface +for Hitachi microprocessors, or @samp{target e7000}, the in-circuit +emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is +the default when GDB is configured specifically for the Hitachi SH, +H8/300, or H8/500.) + +@item +what serial device connects your host to your Hitachi board (the first +serial device available on your host is the default). + +@item +what speed to use over the serial device. +@end enumerate + +@menu +* Hitachi Boards:: Connecting to Hitachi boards. +* Hitachi ICE:: Using the E7000 In-Circuit Emulator. +* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros. +@end menu + +@node Hitachi Boards +@subsubsection Connecting to Hitachi boards + +@c only for Unix hosts +@kindex device +@cindex serial device, Hitachi micros +Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you +need to explicitly set the serial device. The default @var{port} is the +first available port on your host. This is only necessary on Unix +hosts, where it is typically something like @file{/dev/ttya}. + +@kindex speed +@cindex serial line speed, Hitachi micros +@code{@value{GDBP}} has another special command to set the communications +speed: @samp{speed @var{bps}}. This command also is only used from Unix +hosts; on DOS hosts, set the line speed as usual from outside GDB with +the DOS @kbd{mode} command (for instance, @w{@samp{mode +com2:9600,n,8,1,p}} for a 9600 bps connection). + +The @samp{device} and @samp{speed} commands are available only when you +use a Unix host to debug your Hitachi microprocessor programs. If you +use a DOS host, +@value{GDBN} depends on an auxiliary terminate-and-stay-resident program +called @code{asynctsr} to communicate with the development board +through a PC serial port. You must also use the DOS @code{mode} command +to set up the serial port on the DOS side. + +The following sample session illustrates the steps needed to start a +program under @value{GDBN} control on an H8/300. The example uses a +sample H8/300 program called @file{t.x}. The procedure is the same for +the Hitachi SH and the H8/500. + +First hook up your development board. In this example, we use a +board attached to serial port @code{COM2}; if you use a different serial +port, substitute its name in the argument of the @code{mode} command. +When you call @code{asynctsr}, the auxiliary comms program used by the +degugger, you give it just the numeric part of the serial port's name; +for example, @samp{asyncstr 2} below runs @code{asyncstr} on +@code{COM2}. + +@example +C:\H8300\TEST> asynctsr 2 +C:\H8300\TEST> mode com2:9600,n,8,1,p + +Resident portion of MODE loaded + +COM2: 9600, n, 8, 1, p + +@end example + +@quotation +@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with +@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to +disable it, or even boot without it, to use @code{asynctsr} to control +your development board. +@end quotation + +@kindex target hms +Now that serial communications are set up, and the development board is +connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with +the name of your program as the argument. @code{@value{GDBP}} prompts +you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special +commands to begin your debugging session: @samp{target hms} to specify +cross-debugging to the Hitachi board, and the @code{load} command to +download your program to the board. @code{load} displays the names of +the program's sections, and a @samp{*} for each 2K of data downloaded. +(If you want to refresh @value{GDBN} data on symbols or on the +executable file without downloading, use the @value{GDBN} commands +@code{file} or @code{symbol-file}. These commands, and @code{load} +itself, are described in @ref{Files,,Commands to specify files}.) + +@smallexample +(eg-C:\H8300\TEST) @value{GDBP} t.x +GDB is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. +There is absolutely no warranty for GDB; type "show warranty" +for details. +GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... +(gdb) target hms +Connected to remote H8/300 HMS system. +(gdb) load t.x +.text : 0x8000 .. 0xabde *********** +.data : 0xabde .. 0xad30 * +.stack : 0xf000 .. 0xf014 * +@end smallexample + +At this point, you're ready to run or debug your program. From here on, +you can use all the usual @value{GDBN} commands. The @code{break} command +sets breakpoints; the @code{run} command starts your program; +@code{print} or @code{x} display data; the @code{continue} command +resumes execution after stopping at a breakpoint. You can use the +@code{help} command at any time to find out more about @value{GDBN} commands. + +Remember, however, that @emph{operating system} facilities aren't +available on your development board; for example, if your program hangs, +you can't send an interrupt---but you can press the @sc{reset} switch! + +Use the @sc{reset} button on the development board +@itemize @bullet +@item +to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has +no way to pass an interrupt signal to the development board); and + +@item +to return to the @value{GDBN} command prompt after your program finishes +normally. The communications protocol provides no other way for @value{GDBN} +to detect program completion. +@end itemize + +In either case, @value{GDBN} sees the effect of a @sc{reset} on the +development board as a ``normal exit'' of your program. + +@node Hitachi ICE +@subsubsection Using the E7000 in-circuit emulator + +@kindex target e7000 +You can use the E7000 in-circuit emulator to develop code for either the +Hitachi SH or the H8/300H. Use one of these forms of the @samp{target +e7000} command to connect @value{GDBN} to your E7000: + +@table @code +@item target e7000 @var{port} @var{speed} +Use this form if your E7000 is connected to a serial port. The +@var{port} argument identifies what serial port to use (for example, +@samp{com2}). The third argument is the line speed in bits per second +(for example, @samp{9600}). + +@item target e7000 @var{hostname} +If your E7000 is installed as a host on a TCP/IP network, you can just +specify its hostname; @value{GDBN} uses @code{telnet} to connect. +@end table + +@node Hitachi Special +@subsubsection Special @value{GDBN} commands for Hitachi micros + +Some @value{GDBN} commands are available only for the H8/300: + +@table @code + +@kindex set machine +@kindex show machine +@item set machine h8300 +@itemx set machine h8300h +Condition @value{GDBN} for one of the two variants of the H8/300 +architecture with @samp{set machine}. You can use @samp{show machine} +to check which variant is currently in effect. + +@end table + +@node H8/500 +@subsection H8/500 + +@table @code + +@kindex set memory @var{mod} +@cindex memory models, H8/500 +@item set memory @var{mod} +@itemx show memory +Specify which H8/500 memory model (@var{mod}) you are using with +@samp{set memory}; check which memory model is in effect with @samp{show +memory}. The accepted values for @var{mod} are @code{small}, +@code{big}, @code{medium}, and @code{compact}. + +@end table + +@node i960 +@subsection Intel i960 + +@table @code + +@kindex target mon960 +@item target mon960 @var{dev} +MON960 monitor for Intel i960. + +@item target nindy @var{devicename} +An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is +the name of the serial device to use for the connection, e.g. +@file{/dev/ttya}. + +@end table + +@cindex Nindy +@cindex i960 +@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When +@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can +tell @value{GDBN} how to connect to the 960 in several ways: + +@itemize @bullet +@item +Through command line options specifying serial port, version of the +Nindy protocol, and communications speed; + +@item +By responding to a prompt on startup; + +@item +By using the @code{target} command at any point during your @value{GDBN} +session. @xref{Target Commands, ,Commands for managing targets}. + +@kindex target nindy +@item target nindy @var{devicename} +An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is +the name of the serial device to use for the connection, e.g. +@file{/dev/ttya}. + +@end itemize + +@cindex download to Nindy-960 +With the Nindy interface to an Intel 960 board, @code{load} +downloads @var{filename} to the 960 as well as adding its symbols in +@value{GDBN}. + +@menu +* Nindy Startup:: Startup with Nindy +* Nindy Options:: Options for Nindy +* Nindy Reset:: Nindy reset command +@end menu + +@node Nindy Startup +@subsubsection Startup with Nindy + +If you simply start @code{@value{GDBP}} without using any command-line +options, you are prompted for what serial port to use, @emph{before} you +reach the ordinary @value{GDBN} prompt: + +@example +Attach /dev/ttyNN -- specify NN, or "quit" to quit: +@end example + +@noindent +Respond to the prompt with whatever suffix (after @samp{/dev/tty}) +identifies the serial port you want to use. You can, if you choose, +simply start up with no Nindy connection by responding to the prompt +with an empty line. If you do this and later wish to attach to Nindy, +use @code{target} (@pxref{Target Commands, ,Commands for managing targets}). + +@node Nindy Options +@subsubsection Options for Nindy + +These are the startup options for beginning your @value{GDBN} session with a +Nindy-960 board attached: + +@table @code +@item -r @var{port} +Specify the serial port name of a serial interface to be used to connect +to the target system. This option is only available when @value{GDBN} is +configured for the Intel 960 target architecture. You may specify +@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a +device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique +suffix for a specific @code{tty} (e.g. @samp{-r a}). + +@item -O +(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use +the ``old'' Nindy monitor protocol to connect to the target system. +This option is only available when @value{GDBN} is configured for the Intel 960 +target architecture. + +@quotation +@emph{Warning:} if you specify @samp{-O}, but are actually trying to +connect to a target system that expects the newer protocol, the connection +fails, appearing to be a speed mismatch. @value{GDBN} repeatedly +attempts to reconnect at several different line speeds. You can abort +this process with an interrupt. +@end quotation + +@item -brk +Specify that @value{GDBN} should first send a @code{BREAK} signal to the target +system, in an attempt to reset it, before connecting to a Nindy target. + +@quotation +@emph{Warning:} Many target systems do not have the hardware that this +requires; it only works with a few boards. +@end quotation +@end table + +The standard @samp{-b} option controls the line speed used on the serial +port. + +@c @group +@node Nindy Reset +@subsubsection Nindy reset command + +@table @code +@item reset +@kindex reset +For a Nindy target, this command sends a ``break'' to the remote target +system; this is only useful if the target has been equipped with a +circuit to perform a hard reset (or some other interesting action) when +a break is detected. +@end table +@c @end group + +@node M32R/D +@subsection Mitsubishi M32R/D + +@table @code + +@kindex target m32r +@item target m32r @var{dev} +Mitsubishi M32R/D ROM monitor. + +@end table + +@node M68K +@subsection M68k + +The Motorola m68k configuration includes ColdFire support, and +target command for the following ROM monitors. + +@table @code + +@kindex target abug +@item target abug @var{dev} +ABug ROM monitor for M68K. + +@kindex target cpu32bug +@item target cpu32bug @var{dev} +CPU32BUG monitor, running on a CPU32 (M68K) board. + +@kindex target dbug +@item target dbug @var{dev} +dBUG ROM monitor for Motorola ColdFire. + +@kindex target est +@item target est @var{dev} +EST-300 ICE monitor, running on a CPU32 (M68K) board. + +@kindex target rom68k +@item target rom68k @var{dev} +ROM 68K monitor, running on an M68K IDP board. + +@end table + +If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will +instead have only a single special target command: + +@table @code + +@kindex target es1800 +@item target es1800 @var{dev} +ES-1800 emulator for M68K. + +@end table + +[context?] + +@table @code + +@kindex target rombug +@item target rombug @var{dev} +ROMBUG ROM monitor for OS/9000. + +@end table + +@node M88K +@subsection M88K + +@table @code + +@kindex target bug +@item target bug @var{dev} +BUG monitor, running on a MVME187 (m88k) board. + +@end table + +@node MIPS Embedded +@subsection MIPS Embedded + +@cindex MIPS boards +@value{GDBN} can use the MIPS remote debugging protocol to talk to a +MIPS board attached to a serial line. This is available when +you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. + +@need 1000 +Use these @value{GDBN} commands to specify the connection to your target board: + +@table @code +@item target mips @var{port} +@kindex target mips @var{port} +To run a program on the board, start up @code{@value{GDBP}} with the +name of your program as the argument. To connect to the board, use the +command @samp{target mips @var{port}}, where @var{port} is the name of +the serial port connected to the board. If the program has not already +been downloaded to the board, you may use the @code{load} command to +download it. You can then use all the usual @value{GDBN} commands. + +For example, this sequence connects to the target board through a serial +port, and loads and runs a program called @var{prog} through the +debugger: + +@example +host$ @value{GDBP} @var{prog} +GDB is free software and @dots{} +(gdb) target mips /dev/ttyb +(gdb) load @var{prog} +(gdb) run +@end example + +@item target mips @var{hostname}:@var{portnumber} +On some @value{GDBN} host configurations, you can specify a TCP +connection (for instance, to a serial line managed by a terminal +concentrator) instead of a serial port, using the syntax +@samp{@var{hostname}:@var{portnumber}}. + +@item target pmon @var{port} +@kindex target pmon @var{port} +PMON ROM monitor. + +@item target ddb @var{port} +@kindex target ddb @var{port} +NEC's DDB variant of PMON for Vr4300. + +@item target lsi @var{port} +@kindex target lsi @var{port} +LSI variant of PMON. + +@kindex target r3900 +@item target r3900 @var{dev} +Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. + +@kindex target array +@item target array @var{dev} +Array Tech LSI33K RAID controller board. + +@end table + + +@noindent +@value{GDBN} also supports these special commands for MIPS targets: + +@table @code +@item set processor @var{args} +@itemx show processor +@kindex set processor @var{args} +@kindex show processor +Use the @code{set processor} command to set the type of MIPS +processor when you want to access processor-type-specific registers. +For example, @code{set processor @var{r3041}} tells @value{GDBN} +to use the CPO registers appropriate for the 3041 chip. +Use the @code{show processor} command to see what MIPS processor @value{GDBN} +is using. Use the @code{info reg} command to see what registers +@value{GDBN} is using. + +@item set mipsfpu double +@itemx set mipsfpu single +@itemx set mipsfpu none +@itemx show mipsfpu +@kindex set mipsfpu +@kindex show mipsfpu +@cindex MIPS remote floating point +@cindex floating point, MIPS remote +If your target board does not support the MIPS floating point +coprocessor, you should use the command @samp{set mipsfpu none} (if you +need this, you may wish to put the command in your @value{GDBINIT} +file). This tells @value{GDBN} how to find the return value of +functions which return floating point values. It also allows +@value{GDBN} to avoid saving the floating point registers when calling +functions on the board. If you are using a floating point coprocessor +with only single precision floating point support, as on the @sc{r4650} +processor, use the command @samp{set mipsfpu single}. The default +double precision floating point coprocessor may be selected using +@samp{set mipsfpu double}. + +In previous versions the only choices were double precision or no +floating point, so @samp{set mipsfpu on} will select double precision +and @samp{set mipsfpu off} will select no floating point. + +As usual, you can inquire about the @code{mipsfpu} variable with +@samp{show mipsfpu}. + +@item set remotedebug @var{n} +@itemx show remotedebug +@kindex set remotedebug +@kindex show remotedebug +@cindex @code{remotedebug}, MIPS protocol +@cindex MIPS @code{remotedebug} protocol +@c FIXME! For this to be useful, you must know something about the MIPS +@c FIXME...protocol. Where is it described? +You can see some debugging information about communications with the board +by setting the @code{remotedebug} variable. If you set it to @code{1} using +@samp{set remotedebug 1}, every packet is displayed. If you set it +to @code{2}, every character is displayed. You can check the current value +at any time with the command @samp{show remotedebug}. + +@item set timeout @var{seconds} +@itemx set retransmit-timeout @var{seconds} +@itemx show timeout +@itemx show retransmit-timeout +@cindex @code{timeout}, MIPS protocol +@cindex @code{retransmit-timeout}, MIPS protocol +@kindex set timeout +@kindex show timeout +@kindex set retransmit-timeout +@kindex show retransmit-timeout +You can control the timeout used while waiting for a packet, in the MIPS +remote protocol, with the @code{set timeout @var{seconds}} command. The +default is 5 seconds. Similarly, you can control the timeout used while +waiting for an acknowledgement of a packet with the @code{set +retransmit-timeout @var{seconds}} command. The default is 3 seconds. +You can inspect both values with @code{show timeout} and @code{show +retransmit-timeout}. (These commands are @emph{only} available when +@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) + +The timeout set by @code{set timeout} does not apply when @value{GDBN} +is waiting for your program to stop. In that case, @value{GDBN} waits +forever because it has no way of knowing how long the program is going +to run before stopping. +@end table + +@node PowerPC +@subsection PowerPC + +@table @code + +@kindex target dink32 +@item target dink32 @var{dev} +DINK32 ROM monitor. + +@kindex target ppcbug +@item target ppcbug @var{dev} +@kindex target ppcbug1 +@item target ppcbug1 @var{dev} +PPCBUG ROM monitor for PowerPC. + +@kindex target sds +@item target sds @var{dev} +SDS monitor, running on a PowerPC board (such as Motorola's ADS). + +@end table + +@node PA +@subsection HP PA Embedded + +@table @code + +@kindex target op50n +@item target op50n @var{dev} +OP50N monitor, running on an OKI HPPA board. + +@kindex target w89k +@item target w89k @var{dev} +W89K monitor, running on a Winbond HPPA board. + +@end table + +@node SH +@subsection Hitachi SH + +@table @code + +@kindex target hms +@item target hms @var{dev} +A Hitachi SH board attached via serial line to your host. Use special +commands @code{device} and @code{speed} to control the serial line and +the communications speed used. + +@kindex target e7000 +@item target e7000 @var{dev} +E7000 emulator for Hitachi SH. + +@kindex target sh3 +@kindex target sh3e +@item target sh3 @var{dev} +@item target sh3e @var{dev} +Hitachi SH-3 and SH-3E target systems. + +@end table + +@node Sparclet +@subsection Tsqware Sparclet + +@cindex Sparclet + +@value{GDBN} enables developers to debug tasks running on +Sparclet targets from a Unix host. +@value{GDBN} uses code that runs on +both the Unix host and on the Sparclet target. The program +@code{gdb} is installed and executed on the Unix host. + +@table @code +@item timeout @var{args} +@kindex remotetimeout +@value{GDBN} now supports the option @code{remotetimeout}. +This option is set by the user, and @var{args} represents the number of +seconds @value{GDBN} waits for responses. +@end table + +@kindex Compiling +When compiling for debugging, include the options "-g" to get debug +information and "-Ttext" to relocate the program to where you wish to +load it on the target. You may also want to add the options "-n" or +"-N" in order to reduce the size of the sections. + +@example +sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N +@end example + +You can use objdump to verify that the addresses are what you intended. + +@example +sparclet-aout-objdump --headers --syms prog +@end example + +@kindex Running +Once you have set +your Unix execution search path to find @value{GDBN}, you are ready to +run @value{GDBN}. From your Unix host, run @code{gdb} +(or @code{sparclet-aout-gdb}, depending on your installation). + +@value{GDBN} comes up showing the prompt: + +@example +(gdbslet) +@end example + +@menu +* Sparclet File:: Setting the file to debug +* Sparclet Connection:: Connecting to Sparclet +* Sparclet Download:: Sparclet download +* Sparclet Execution:: Running and debugging +@end menu + +@node Sparclet File +@subsubsection Setting file to debug + +The @value{GDBN} command @code{file} lets you choose with program to debug. + +@example +(gdbslet) file prog +@end example + +@need 1000 +@value{GDBN} then attempts to read the symbol table of @file{prog}. +@value{GDBN} locates +the file by searching the directories listed in the command search +path. +If the file was compiled with debug information (option "-g"), source +files will be searched as well. +@value{GDBN} locates +the source files by searching the directories listed in the directory search +path (@pxref{Environment, ,Your program's environment}). +If it fails +to find a file, it displays a message such as: + +@example +prog: No such file or directory. +@end example + +When this happens, add the appropriate directories to the search paths with +the @value{GDBN} commands @code{path} and @code{dir}, and execute the +@code{target} command again. + +@node Sparclet Connection +@subsubsection Connecting to Sparclet + +The @value{GDBN} command @code{target} lets you connect to a Sparclet target. +To connect to a target on serial port ``@code{ttya}'', type: + +@example +(gdbslet) target sparclet /dev/ttya +Remote target sparclet connected to /dev/ttya +main () at ../prog.c:3 +@end example + +@need 750 +@value{GDBN} displays messages like these: + +@smallexample +Connected to ttya. +@end smallexample + +@node Sparclet Download +@subsubsection Sparclet download + +@cindex download to Sparclet +Once connected to the Sparclet target, +you can use the @value{GDBN} +@code{load} command to download the file from the host to the target. +The file name and load offset should be given as arguments to the @code{load} +command. +Since the file format is aout, the program must be loaded to the starting +address. You can use objdump to find out what this value is. The load +offset is an offset which is added to the VMA (virtual memory address) +of each of the file's sections. +For instance, if the program +@file{prog} was linked to text address 0x1201000, with data at 0x12010160 +and bss at 0x12010170, in @value{GDBN}, type: + +@example +(gdbslet) load prog 0x12010000 +Loading section .text, size 0xdb0 vma 0x12010000 +@end example + +If the code is loaded at a different address then what the program was linked +to, you may need to use the @code{section} and @code{add-symbol-file} commands +to tell @value{GDBN} where to map the symbol table. + +@node Sparclet Execution +@subsubsection Running and debugging + +@cindex running and debugging Sparclet programs +You can now begin debugging the task using @value{GDBN}'s execution control +commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} +manual for the list of commands. + +@example +(gdbslet) b main +Breakpoint 1 at 0x12010000: file prog.c, line 3. +(gdbslet) run +Starting program: prog +Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 +3 char *symarg = 0; +(gdbslet) step +4 char *execarg = "hello!"; +(gdbslet) +@end example + +@node Sparclite +@subsection Fujitsu Sparclite + +@table @code + +@kindex target sparclite +@item target sparclite @var{dev} +Fujitsu sparclite boards, used only for the purpose of loading. +You must use an additional command to debug the program. +For example: target remote @var{dev} using @value{GDBN} standard +remote protocol. + +@end table + +@node ST2000 +@subsection Tandem ST2000 + +GDB may be used with a Tandem ST2000 phone switch, running Tandem's +STDBUG protocol. + +To connect your ST2000 to the host system, see the manufacturer's +manual. Once the ST2000 is physically attached, you can run: + +@example +target st2000 @var{dev} @var{speed} +@end example + +@noindent +to establish it as your debugging environment. @var{dev} is normally +the name of a serial device, such as @file{/dev/ttya}, connected to the +ST2000 via a serial line. You can instead specify @var{dev} as a TCP +connection (for example, to a serial line attached via a terminal +concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. + +The @code{load} and @code{attach} commands are @emph{not} defined for +this target; you must load your program into the ST2000 as you normally +would for standalone operation. @value{GDBN} reads debugging information +(such as symbols) from a separate, debugging version of the program +available on your host computer. +@c FIXME!! This is terribly vague; what little content is here is +@c basically hearsay. + +@cindex ST2000 auxiliary commands +These auxiliary @value{GDBN} commands are available to help you with the ST2000 +environment: + +@table @code +@item st2000 @var{command} +@kindex st2000 @var{cmd} +@cindex STDBUG commands (ST2000) +@cindex commands to STDBUG (ST2000) +Send a @var{command} to the STDBUG monitor. See the manufacturer's +manual for available commands. + +@item connect +@cindex connect (to STDBUG) +Connect the controlling terminal to the STDBUG command monitor. When +you are done interacting with STDBUG, typing either of two character +sequences gets you back to the @value{GDBN} command prompt: +@kbd{@key{RET}~.} (Return, followed by tilde and period) or +@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). +@end table + +@node Z8000 +@subsection Zilog Z8000 + +@cindex Z8000 +@cindex simulator, Z8000 +@cindex Zilog Z8000 simulator + +When configured for debugging Zilog Z8000 targets, @value{GDBN} includes +a Z8000 simulator. + +For the Z8000 family, @samp{target sim} simulates either the Z8002 (the +unsegmented variant of the Z8000 architecture) or the Z8001 (the +segmented variant). The simulator recognizes which architecture is +appropriate by inspecting the object code. + +@table @code +@item target sim @var{args} +@kindex sim +@kindex target sim +Debug programs on a simulated CPU. If the simulator supports setup +options, specify them via @var{args}. +@end table + +@noindent +After specifying this target, you can debug programs for the simulated +CPU in the same style as programs for your host computer; use the +@code{file} command to load a new program image, the @code{run} command +to run your program, and so on. + +As well as making available all the usual machine registers (see +@code{info reg}), the Z8000 simulator provides three additional items +of information as specially named registers: + +@table @code + +@item cycles +Counts clock-ticks in the simulator. + +@item insts +Counts instructions run in the simulator. + +@item time +Execution time in 60ths of a second. + +@end table + +You can refer to these values in @value{GDBN} expressions with the usual +conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a +conditional breakpoint that suspends only after at least 5000 +simulated clock ticks. + +@node Architectures +@section Architectures + +This section describes characteristics of architectures that affect +all uses of GDB with this architecture, both native and cross. + +@menu +* A29K:: +* Alpha:: +* MIPS:: +@end menu + +@node A29K +@subsection A29K + +@table @code + +@kindex set rstack_high_address +@cindex AMD 29K register stack +@cindex register stack, AMD29K +@item set rstack_high_address @var{address} +On AMD 29000 family processors, registers are saved in a separate +``register stack''. There is no way for @value{GDBN} to determine the +extent of this stack. Normally, @value{GDBN} just assumes that the +stack is ``large enough''. This may result in @value{GDBN} referencing +memory locations that do not exist. If necessary, you can get around +this problem by specifying the ending address of the register stack with +the @code{set rstack_high_address} command. The argument should be an +address, which you probably want to precede with @samp{0x} to specify in +hexadecimal. + +@kindex show rstack_high_address +@item show rstack_high_address +Display the current limit of the register stack, on AMD 29000 family +processors. + +@end table + +@node Alpha +@subsection Alpha + +See the following section. + +@node MIPS +@subsection MIPS + +@cindex stack on Alpha +@cindex stack on MIPS +@cindex Alpha stack +@cindex MIPS stack +Alpha- and MIPS-based computers use an unusual stack frame, which +sometimes requires @value{GDBN} to search backward in the object code to +find the beginning of a function. + +@cindex response time, MIPS debugging +To improve response time (especially for embedded applications, where +@value{GDBN} may be restricted to a slow serial line for this search) +you may want to limit the size of this search, using one of these +commands: + +@table @code +@cindex @code{heuristic-fence-post} (Alpha,MIPS) +@item set heuristic-fence-post @var{limit} +Restrict @value{GDBN} to examining at most @var{limit} bytes in its +search for the beginning of a function. A value of @var{0} (the +default) means there is no limit. However, except for @var{0}, the +larger the limit the more bytes @code{heuristic-fence-post} must search +and therefore the longer it takes to run. + +@item show heuristic-fence-post +Display the current limit. +@end table + +@noindent +These commands are available @emph{only} when @value{GDBN} is configured +for debugging programs on Alpha or MIPS processors. + + @node Controlling GDB @chapter Controlling @value{GDBN} |