From 1171f8d754f71e35fd2f6c4e82b00f3c685e515f Mon Sep 17 00:00:00 2001 From: Jason Molenda Date: Tue, 8 Feb 2000 03:37:34 +0000 Subject: 2000-02-07 Jason Molenda (jsm@bugshack.cygnus.com) * gdb/config/i386/windows.mh, gdb/doc/GDBvn.texi, gdb/doc/remote.texi, gdb/testsuite/gdb.base/README, gdb/testsuite/gdb.base/crossload.exp, gdb/testsuite/gdb.base/i486-elf.u, gdb/testsuite/gdb.base/i860-elf.u, gdb/testsuite/gdb.base/m68k-aout.u, gdb/testsuite/gdb.base/m68k-aout2.u, gdb/testsuite/gdb.base/m68k-elf.u, gdb/testsuite/gdb.base/mips-ecoff.u, gdb/testsuite/gdb.base/sparc-aout.u, gdb/testsuite/gdb.base/sparc-elf.u, gdb/tui/Makefile, readline/ChangeLog: These files have been removed over the course of the last year, but weren't cvs removed from the old GDB repository on sourceware. --- gdb/doc/GDBvn.texi | 1 - gdb/doc/remote.texi | 2202 --------------------------------------------------- 2 files changed, 2203 deletions(-) delete mode 100644 gdb/doc/GDBvn.texi delete mode 100644 gdb/doc/remote.texi (limited to 'gdb/doc') diff --git a/gdb/doc/GDBvn.texi b/gdb/doc/GDBvn.texi deleted file mode 100644 index fd722bd..0000000 --- a/gdb/doc/GDBvn.texi +++ /dev/null @@ -1 +0,0 @@ -@set GDBVN 4.18 diff --git a/gdb/doc/remote.texi b/gdb/doc/remote.texi deleted file mode 100644 index 714b2a2..0000000 --- a/gdb/doc/remote.texi +++ /dev/null @@ -1,2202 +0,0 @@ -@c -*- Texinfo -*- -@c Copyright (c) 1990 1991 1992 1993 Free Software Foundation, Inc. -@c This file is part of the source for the GDB manual. - -@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 -@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 i960-Nindy Remote -@subsection @value{GDBN} with a remote i960 (Nindy) - -@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}. - -@end itemize - -@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 UDI29K Remote -@subsection The UDI protocol for AMD29K - -@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 EB29K Remote -@subsection The 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. - -@menu -* Comms (EB29K):: Communications setup -* gdb-EB29K:: EB29K cross-debugging -* Remote Log:: Remote log -@end menu - -@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 ST2000 Remote -@subsection @value{GDBN} with a Tandem ST2000 - -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 VxWorks Remote -@subsection @value{GDBN} and VxWorks - -@cindex VxWorks - -@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 Sparclet Remote -@subsection @value{GDBN} and 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 Hitachi Remote -@subsection @value{GDBN} and Hitachi microprocessors -@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 on the H8/300 or the -H8/500 configurations: - -@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. - -@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 MIPS Remote -@subsection @value{GDBN} and remote MIPS boards - -@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} - -@item target ddb @var{port} -@kindex target ddb @var{port} - -@item target lsi @var{port} -@kindex target lsi @var{port} - -@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 Simulator -@subsection Simulated CPU target - -@cindex simulator -@cindex simulator, Z8000 -@cindex Z8000 simulator -@cindex simulator, H8/300 or H8/500 -@cindex H8/300 or H8/500 simulator -@cindex simulator, Hitachi SH -@cindex Hitachi SH simulator -@cindex CPU simulator -For some configurations, @value{GDBN} includes a CPU simulator that you -can use instead of a hardware CPU to debug your programs. -Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300, -H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850, -W65, and 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. - -@c need to add much more detail about sims! -- cgit v1.1