diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 13 | ||||
| -rw-r--r-- | gdb/doc/Makefile.in | 2 | ||||
| -rw-r--r-- | gdb/doc/all-cfg.texi | 3 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 4 | ||||
| -rw-r--r-- | gdb/doc/gdbinv-s.texi | 1168 | ||||
| -rw-r--r-- | gdb/doc/h8-cfg.texi | 1 | ||||
| -rw-r--r-- | gdb/doc/remote.texi | 1288 |
7 files changed, 1308 insertions, 1171 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 0ba5b17..a4367a5 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,16 @@ +Wed Jul 28 15:26:53 1993 Roland H. Pesch (pesch@el_bosque.cygnus.com) + + * h8-cfg.texi, all-cfg.texi: new flag GDBSERVER + + * Makefile.in: depend on remote.texi rather than gdbinv-s.texi + + * remote.texi: (Server) New node on gdbserver. (Remote Serial, + ST2000 Remote, MIPS Remote): mention `host:port' syntax for TCP. + + * remote.texi: new name for former gdbinv-s.texi + + * gdb.texinfo: use remote.texi rather than gdbinv-s.texi + Wed Jul 28 08:26:24 1993 Ian Lance Taylor (ian@cygnus.com) * gdbinv-s.texi: Documented timeout and retransmit-timeout diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index 9f15b89..d5ae290 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -75,7 +75,7 @@ TEX = tex TEXINDEX = texindex # Main GDB manual's source files -SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/gdbinv-s.texi +SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/remote.texi SFILES_LOCAL = $(srcdir)/gdb.texinfo GDBvn.texi $(SFILES_INCLUDED) diff --git a/gdb/doc/all-cfg.texi b/gdb/doc/all-cfg.texi index 8811bb3..ec64da1 100644 --- a/gdb/doc/all-cfg.texi +++ b/gdb/doc/all-cfg.texi @@ -84,6 +84,9 @@ @c Discuss remote serial debugging stub? @set REMOTESTUB @c +@c Discuss gdbserver? +@set GDBSERVER +@c @c Refrain from discussing how to configure sw and format doc? @clear PRECONFIGURED @c diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 9cd418d..e31b01a 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -798,7 +798,7 @@ in sequential order. The order makes a difference when the @end menu @ifclear GENERIC -@include gdbinv-s.texi +@include remote.texi @end ifclear @node File Options @@ -7068,7 +7068,7 @@ configuration of GDB; use @code{help targets} to list them. @end ifset @end menu -@include gdbinv-s.texi +@include remote.texi @end ifset @node Controlling GDB diff --git a/gdb/doc/gdbinv-s.texi b/gdb/doc/gdbinv-s.texi index 196c3f8..e69de29 100644 --- a/gdb/doc/gdbinv-s.texi +++ b/gdb/doc/gdbinv-s.texi @@ -1,1168 +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. -@c This text diverted to "Remote Debugging" section in general case; -@c however, if we're doing a manual specifically for one of these, it -@c belongs up front (in "Getting In and Out" chapter). - -@ifset REMOTESTUB -@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}. -@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 sparc-stub.c -@kindex sparc-stub.c -For @sc{sparc} architectures. - -@item m68k-stub.c -@kindex m68k-stub.c -@kindex Motorola 680x0 -@kindex 680x0 -For Motorola 680x0 architectures. - -@item i386-stub.c -@kindex i386-stub.c -@kindex Intel -@kindex 386 -For Intel 386 and compatible 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:: Outline of the communication protocol -@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 will transfer 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 will get 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. To allow the stub to work, you must supply -these special low-level subroutines: - -@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. - -@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) -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, -etc.) 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. - -@c For the 386, doesn't the interrupt gate contain a privilege level? -@c If so, what should it be set to? I suspect the answer is the -@c privilege level in effect at the time that exceptionHandler is -@c called, but I'm not sure. FIXME. -For the 386, @var{exception_address} should be installed as an interrupt -gate so that interrupts are masked while the handler runs. The -@sc{sparc} and 68k stubs are able to mask interrupts themself without -help from @code{exceptionHandler}. - -@item void flush_i_cache() -@kindex flush_i_cache -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 will vary 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}): -@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 used for this 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. - -Then establish communication using the @code{target remote} command. -Its argument is the name of the device you're using to control the -target machine. For example: - -@example -target remote /dev/ttyb -@end example - -@noindent -if the serial line is connected to the device named @file{/dev/ttyb}. -@ignore -@c this is from the old text, but it doesn't seem to make sense now that I've -@c seen an example... pesch 4sep1992 -This will stop the remote machine if it is not already stopped. -@end ignore -@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 Outline of the 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}. - -@cindex protocol, @value{GDBN} remote serial -@cindex serial protocol, @value{GDBN} remote -@cindex remote serial protocol -All @value{GDBN} commands and responses (other than acknowledgements, which -are single characters) are sent as a packet which includes a -checksum. A packet is introduced with the character @samp{$}, and ends -with the character @samp{#} followed by a two-digit checksum: - -@example -$@var{packet info}#@var{checksum} -@end example - -@cindex checksum, for @value{GDBN} remote -@noindent -@var{checksum} is computed as the modulo 256 sum of the @var{packet -info} characters. - -When either the host or the target machine receives a packet, the first -response expected is an acknowledgement: a single character, either -@samp{+} (to indicate the package was received correctly) or @samp{-} -(to request retransmission). - -The host (@value{GDBN}) sends commands, and the target (the debugging stub -incorporated in your program) sends data in response. The target also -sends data when your program stops. - -Command packets are distinguished by their first character, which -identifies the kind of command. - -These are the commands currently supported: - -@table @code -@item g -Requests the values of CPU registers. - -@item G -Sets the values of CPU registers. - -@item m@var{addr},@var{count} -Read @var{count} bytes at location @var{addr}. - -@item M@var{addr},@var{count}:@dots{} -Write @var{count} bytes at location @var{addr}. - -@item c -@itemx c@var{addr} -Resume execution at the current address (or at @var{addr} if supplied). - -@item s -@itemx s@var{addr} -Step the target program for one instruction, from either the current -program counter or from @var{addr} if supplied. - -@item k -Kill the target program. - -@item ? -Report the most recent signal. To allow you to take advantage of the -@value{GDBN} signal handling commands, one of the functions of the debugging -stub is to report CPU traps as the corresponding POSIX signal values. -@end table - -@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} will show you its current state. -@end ifset - -@ifset I960 -@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 -@end ifset - -@ifset AMD29K -@node UDI29K Remote -@subsection @value{GDBN} and 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 @value{GDBN} and 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? ---pesch@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... ---pesch@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} will keep -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} will @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 - -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). ---pesch@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. - -@end ifset - -@ifset ST2000 -@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. - -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} will read 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 will get 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 -@end ifset - -@ifset VXWORKS -@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.) - -The following information on connecting to VxWorks was current when -this manual was produced; newer releases of VxWorks may use revised -procedures. - -The remote debugging interface (RDB) routines are installed and executed -on the VxWorks target. These routines are included in the VxWorks library -@file{rdb.a} and are incorporated into the system image when source-level -debugging is enabled in the VxWorks configuration. - -@kindex INCLUDE_RDB -If you wish, you can define @code{INCLUDE_RDB} in the VxWorks -configuration file @file{configAll.h} to include the RDB interface -routines and spawn 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 the RDB interface 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 - -@value{GDBN} displays messages like these: - -@smallexample -Attaching remote machine across net... -Connected to tt. -@end smallexample - -@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 - -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 will cause @value{GDBN} to 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. If running, it will be suspended at -the time of attachment. -@end ifset - -@ifset H8 -@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 (this 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); - -@ignore -@c this is only for Unix hosts, not currently of interest. -@item -what speed to use over the serial device. -@end ignore -@end enumerate - -@ifclear H8EXCLUSIVE -@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, -@end ifclear -@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. - -@ifset DOSHOST -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 -(eg-C:\H8300\TEST) mode com2:9600,n,8,1,p - -Resident portion of MODE loaded - -COM2: 9600, n, 8, 1, p - -(eg-C:\H8300\TEST) asynctsr 2 -@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} will see the effect of a @sc{reset} on the -development board as a ``normal exit'' of your program. -@end ifset -@end ifset - -@ifset MIPS -@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}. - -@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. - -@cindex @code{remotedebug}, MIPS 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 1 using -@samp{set remotedebug 1} every packet will be displayed. If you set it -to 2 every character will be displayed. You can check the current value -at any time with the command @samp{show remotedebug}. - -@cindex @code{timeout}, MIPS protocol -@cindex @code{retransmit-timeout}, MIPS protocol -The timeout used while waiting for a packet is controlled by the -@code{timeout} variable. The default is 5 seconds. The timeout used -while waiting for an acknowledgement of a packet is controlled by the -@code{retransmit-timeout} variable. The default is 3 seconds. - -@kindex set mipsfpu off -@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 off} (you may -wish to put this in your @value{GDBINIT} file). This will tell -@value{GDBN} how to find the return value of functions which return -floating point values, and tell it to call functions on the board -without saving the floating point registers. -@end ifset - -@ifset SIMS -@node Simulator -@subsection Simulated CPU target - -@ifset GENERIC -@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, -a simulator is available when @value{GDBN} is configured to debug Zilog -Z8000 or Hitachi microprocessor targets. -@end ifset - -@ifclear GENERIC -@ifset H8 -@cindex simulator, H8/300 or H8/500 -@cindex Hitachi H8/300 or H8/500 simulator -@cindex simulator, Hitachi SH -@cindex Hitachi SH simulator -When configured for debugging Hitachi microprocessor targets, -@value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH, -H8/300, or H8/500). -@end ifset - -@ifset Z8K -@cindex simulator, Z8000 -@cindex Zilog Z8000 simulator -When configured for debugging Zilog Z8000 targets, @value{GDBN} includes -a Z8000 simulator. -@end ifset -@end ifclear - -@ifset Z8K -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. -@end ifset - -@table @code -@item target sim -@kindex sim -@kindex target sim -Debug programs on a simulated CPU -@ifset GENERIC -(which CPU depends on the @value{GDBN} configuration) -@end ifset -@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}), this debugging target 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 will suspend only after at least 5000 -simulated clock ticks. -@end ifset diff --git a/gdb/doc/h8-cfg.texi b/gdb/doc/h8-cfg.texi index a717982..823c7c2 100644 --- a/gdb/doc/h8-cfg.texi +++ b/gdb/doc/h8-cfg.texi @@ -8,6 +8,7 @@ @set DOSHOST @clear FORTRAN @clear FSFDOC +@clear GDBSERVER @clear GENERIC @set H8 @set H8EXCLUSIVE diff --git a/gdb/doc/remote.texi b/gdb/doc/remote.texi new file mode 100644 index 0000000..03d546e --- /dev/null +++ b/gdb/doc/remote.texi @@ -0,0 +1,1288 @@ +@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. +@c This text diverted to "Remote Debugging" section in general case; +@c however, if we're doing a manual specifically for one of these, it +@c belongs up front (in "Getting In and Out" chapter). + +@ifset REMOTESTUB +@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}. + +@ifset GDBSERVER +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 ifset +@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 sparc-stub.c +@kindex sparc-stub.c +For @sc{sparc} architectures. + +@item m68k-stub.c +@kindex m68k-stub.c +@kindex Motorola 680x0 +@kindex 680x0 +For Motorola 680x0 architectures. + +@item i386-stub.c +@kindex i386-stub.c +@kindex Intel +@kindex 386 +For Intel 386 and compatible 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:: Outline of the communication protocol +@ifset GDBSERVER +* Server:: Using the `gdbserver' program +@end ifset +@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 will transfer 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 will get 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. To allow the stub to work, you must supply +these special low-level subroutines: + +@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. + +@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) +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, +etc.) 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. + +@c For the 386, doesn't the interrupt gate contain a privilege level? +@c If so, what should it be set to? I suspect the answer is the +@c privilege level in effect at the time that exceptionHandler is +@c called, but I'm not sure. FIXME. +For the 386, @var{exception_address} should be installed as an interrupt +gate so that interrupts are masked while the handler runs. The +@sc{sparc} and 68k stubs are able to mask interrupts themself without +help from @code{exceptionHandler}. + +@item void flush_i_cache() +@kindex flush_i_cache +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 will vary 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}): +@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 used for this 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 Outline of the 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}. + +@cindex protocol, @value{GDBN} remote serial +@cindex serial protocol, @value{GDBN} remote +@cindex remote serial protocol +All @value{GDBN} commands and responses (other than acknowledgements, which +are single characters) are sent as a packet which includes a +checksum. A packet is introduced with the character @samp{$}, and ends +with the character @samp{#} followed by a two-digit checksum: + +@example +$@var{packet info}#@var{checksum} +@end example + +@cindex checksum, for @value{GDBN} remote +@noindent +@var{checksum} is computed as the modulo 256 sum of the @var{packet +info} characters. + +When either the host or the target machine receives a packet, the first +response expected is an acknowledgement: a single character, either +@samp{+} (to indicate the package was received correctly) or @samp{-} +(to request retransmission). + +The host (@value{GDBN}) sends commands, and the target (the debugging stub +incorporated in your program) sends data in response. The target also +sends data when your program stops. + +Command packets are distinguished by their first character, which +identifies the kind of command. + +These are the commands currently supported: + +@table @code +@item g +Requests the values of CPU registers. + +@item G +Sets the values of CPU registers. + +@item m@var{addr},@var{count} +Read @var{count} bytes at location @var{addr}. + +@item M@var{addr},@var{count}:@dots{} +Write @var{count} bytes at location @var{addr}. + +@item c +@itemx c@var{addr} +Resume execution at the current address (or at @var{addr} if supplied). + +@item s +@itemx s@var{addr} +Step the target program for one instruction, from either the current +program counter or from @var{addr} if supplied. + +@item k +Kill the target program. + +@item ? +Report the most recent signal. To allow you to take advantage of the +@value{GDBN} signal handling commands, one of the functions of the debugging +stub is to report CPU traps as the corresponding POSIX signal values. +@end table + +@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} will show you its current state. + +@ifset GDBSERVER +@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 +@var{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 @var{GDBN}, so you may be able to get +started more quickly on a new system by using @code{gdbserver}. + +@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, +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{GDB}; +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.@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 host, +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 +@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 descriptof 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 @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 +@end ifset + +@end ifset + +@ifset I960 +@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 +@end ifset + +@ifset AMD29K +@node UDI29K Remote +@subsection @value{GDBN} and 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 @value{GDBN} and 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? ---pesch@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... ---pesch@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} will keep +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} will @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 + +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). ---pesch@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. + +@end ifset + +@ifset ST2000 +@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} will read 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 will get 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 +@end ifset + +@ifset VXWORKS +@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.) + +The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. + +The remote debugging interface (RDB) routines are installed and executed +on the VxWorks target. These routines are included in the VxWorks library +@file{rdb.a} and are incorporated into the system image when source-level +debugging is enabled in the VxWorks configuration. + +@kindex INCLUDE_RDB +If you wish, you can define @code{INCLUDE_RDB} in the VxWorks +configuration file @file{configAll.h} to include the RDB interface +routines and spawn 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 the RDB interface 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 + +@value{GDBN} displays messages like these: + +@smallexample +Attaching remote machine across net... +Connected to tt. +@end smallexample + +@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 + +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 will cause @value{GDBN} to 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. If running, it will be suspended at +the time of attachment. +@end ifset + +@ifset H8 +@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 (this 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); + +@ignore +@c this is only for Unix hosts, not currently of interest. +@item +what speed to use over the serial device. +@end ignore +@end enumerate + +@ifclear H8EXCLUSIVE +@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, +@end ifclear +@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. + +@ifset DOSHOST +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 +(eg-C:\H8300\TEST) mode com2:9600,n,8,1,p + +Resident portion of MODE loaded + +COM2: 9600, n, 8, 1, p + +(eg-C:\H8300\TEST) asynctsr 2 +@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} will see the effect of a @sc{reset} on the +development board as a ``normal exit'' of your program. +@end ifset +@end ifset + +@ifset MIPS +@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}. + +@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. + +You can also specify @var{port} as a TCP connection (for instance, to a +serial line managed by a terminal concentrator), using the syntax +@code{@var{hostname}:@var{portnumber}}. + +@cindex @code{remotedebug}, MIPS 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 1 using +@samp{set remotedebug 1} every packet will be displayed. If you set it +to 2 every character will be displayed. You can check the current value +at any time with the command @samp{show remotedebug}. + +@cindex @code{timeout}, MIPS protocol +@cindex @code{retransmit-timeout}, MIPS protocol +The timeout used while waiting for a packet is controlled by the +@code{timeout} variable. The default is 5 seconds. The timeout used +while waiting for an acknowledgement of a packet is controlled by the +@code{retransmit-timeout} variable. The default is 3 seconds. + +@kindex set mipsfpu off +@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 off} (you may +wish to put this in your @value{GDBINIT} file). This will tell +@value{GDBN} how to find the return value of functions which return +floating point values, and tell it to call functions on the board +without saving the floating point registers. +@end ifset + +@ifset SIMS +@node Simulator +@subsection Simulated CPU target + +@ifset GENERIC +@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, +a simulator is available when @value{GDBN} is configured to debug Zilog +Z8000 or Hitachi microprocessor targets. +@end ifset + +@ifclear GENERIC +@ifset H8 +@cindex simulator, H8/300 or H8/500 +@cindex Hitachi H8/300 or H8/500 simulator +@cindex simulator, Hitachi SH +@cindex Hitachi SH simulator +When configured for debugging Hitachi microprocessor targets, +@value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH, +H8/300, or H8/500). +@end ifset + +@ifset Z8K +@cindex simulator, Z8000 +@cindex Zilog Z8000 simulator +When configured for debugging Zilog Z8000 targets, @value{GDBN} includes +a Z8000 simulator. +@end ifset +@end ifclear + +@ifset Z8K +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. +@end ifset + +@table @code +@item target sim +@kindex sim +@kindex target sim +Debug programs on a simulated CPU +@ifset GENERIC +(which CPU depends on the @value{GDBN} configuration) +@end ifset +@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}), this debugging target 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 will suspend only after at least 5000 +simulated clock ticks. +@end ifset |