2 @c Copyright (c) 1990 1991 1992 1993 Free Software Foundation, Inc.
3 @c This file is part of the source for the GDB manual.
6 @subsection The @value{GDBN} remote serial protocol
8 @cindex remote serial debugging, overview
9 To debug a program running on another machine (the debugging
10 @dfn{target} machine), you must first arrange for all the usual
11 prerequisites for the program to run by itself. For example, for a C
16 A startup routine to set up the C runtime environment; these usually
17 have a name like @file{crt0}. The startup routine may be supplied by
18 your hardware supplier, or you may have to write your own.
21 You probably need a C subroutine library to support your program's
22 subroutine calls, notably managing input and output.
25 A way of getting your program to the other machine---for example, a
26 download program. These are often supplied by the hardware
27 manufacturer, but you may have to write your own from hardware
31 The next step is to arrange for your program to use a serial port to
32 communicate with the machine where @value{GDBN} is running (the @dfn{host}
33 machine). In general terms, the scheme looks like this:
37 @value{GDBN} already understands how to use this protocol; when everything
38 else is set up, you can simply use the @samp{target remote} command
39 (@pxref{Targets,,Specifying a Debugging Target}).
42 you must link with your program a few special-purpose subroutines that
43 implement the @value{GDBN} remote serial protocol. The file containing these
44 subroutines is called a @dfn{debugging stub}.
46 On certain remote targets, you can use an auxiliary program
47 @code{gdbserver} instead of linking a stub into your program.
48 @xref{Server,,Using the @code{gdbserver} program}, for details.
51 The debugging stub is specific to the architecture of the remote
52 machine; for example, use @file{sparc-stub.c} to debug programs on
55 @cindex remote serial stub list
56 These working remote stubs are distributed with @value{GDBN}:
64 For Intel 386 and compatible architectures.
68 @cindex Motorola 680x0
70 For Motorola 680x0 architectures.
76 For Hitachi SH architectures.
81 For @sc{sparc} architectures.
87 For Fujitsu @sc{sparclite} architectures.
91 The @file{README} file in the @value{GDBN} distribution may list other
95 * Stub Contents:: What the stub can do for you
96 * Bootstrapping:: What you must do for the stub
97 * Debug Session:: Putting it all together
98 * Protocol:: Outline of the communication protocol
99 * Server:: Using the `gdbserver' program
100 * NetWare:: Using the `gdbserve.nlm' program
104 @subsubsection What the stub can do for you
106 @cindex remote serial stub
107 The debugging stub for your architecture supplies these three
111 @item set_debug_traps
112 @kindex set_debug_traps
113 @cindex remote serial stub, initialization
114 This routine arranges for @code{handle_exception} to run when your
115 program stops. You must call this subroutine explicitly near the
116 beginning of your program.
118 @item handle_exception
119 @kindex handle_exception
120 @cindex remote serial stub, main routine
121 This is the central workhorse, but your program never calls it
122 explicitly---the setup code arranges for @code{handle_exception} to
123 run when a trap is triggered.
125 @code{handle_exception} takes control when your program stops during
126 execution (for example, on a breakpoint), and mediates communications
127 with @value{GDBN} on the host machine. This is where the communications
128 protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
129 representative on the target machine; it begins by sending summary
130 information on the state of your program, then continues to execute,
131 retrieving and transmitting any information @value{GDBN} needs, until you
132 execute a @value{GDBN} command that makes your program resume; at that point,
133 @code{handle_exception} returns control to your own code on the target
137 @cindex @code{breakpoint} subroutine, remote
138 Use this auxiliary subroutine to make your program contain a
139 breakpoint. Depending on the particular situation, this may be the only
140 way for @value{GDBN} to get control. For instance, if your target
141 machine has some sort of interrupt button, you won't need to call this;
142 pressing the interrupt button transfers control to
143 @code{handle_exception}---in effect, to @value{GDBN}. On some machines,
144 simply receiving characters on the serial port may also trigger a trap;
145 again, in that situation, you don't need to call @code{breakpoint} from
146 your own program---simply running @samp{target remote} from the host
147 @value{GDBN} session gets control.
149 Call @code{breakpoint} if none of these is true, or if you simply want
150 to make certain your program stops at a predetermined point for the
151 start of your debugging session.
155 @subsubsection What you must do for the stub
157 @cindex remote stub, support routines
158 The debugging stubs that come with @value{GDBN} are set up for a particular
159 chip architecture, but they have no information about the rest of your
160 debugging target machine.
162 First of all you need to tell the stub how to communicate with the
166 @item int getDebugChar()
168 Write this subroutine to read a single character from the serial port.
169 It may be identical to @code{getchar} for your target system; a
170 different name is used to allow you to distinguish the two if you wish.
172 @item void putDebugChar(int)
174 Write this subroutine to write a single character to the serial port.
175 It may be identical to @code{putchar} for your target system; a
176 different name is used to allow you to distinguish the two if you wish.
179 @cindex control C, and remote debugging
180 @cindex interrupting remote targets
181 If you want @value{GDBN} to be able to stop your program while it is
182 running, you need to use an interrupt-driven serial driver, and arrange
183 for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
184 character). That is the character which @value{GDBN} uses to tell the
185 remote system to stop.
187 Getting the debugging target to return the proper status to @value{GDBN}
188 probably requires changes to the standard stub; one quick and dirty way
189 is to just execute a breakpoint instruction (the ``dirty'' part is that
190 @value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
192 Other routines you need to supply are:
195 @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
196 @kindex exceptionHandler
197 Write this function to install @var{exception_address} in the exception
198 handling tables. You need to do this because the stub does not have any
199 way of knowing what the exception handling tables on your target system
200 are like (for example, the processor's table might be in @sc{rom},
201 containing entries which point to a table in @sc{ram}).
202 @var{exception_number} is the exception number which should be changed;
203 its meaning is architecture-dependent (for example, different numbers
204 might represent divide by zero, misaligned access, etc). When this
205 exception occurs, control should be transferred directly to
206 @var{exception_address}, and the processor state (stack, registers,
207 and so on) should be just as it is when a processor exception occurs. So if
208 you want to use a jump instruction to reach @var{exception_address}, it
209 should be a simple jump, not a jump to subroutine.
211 For the 386, @var{exception_address} should be installed as an interrupt
212 gate so that interrupts are masked while the handler runs. The gate
213 should be at privilege level 0 (the most privileged level). The
214 @sc{sparc} and 68k stubs are able to mask interrupts themselves without
215 help from @code{exceptionHandler}.
217 @item void flush_i_cache()
218 @kindex flush_i_cache
219 (sparc and sparclite only) Write this subroutine to flush the
220 instruction cache, if any, on your target machine. If there is no
221 instruction cache, this subroutine may be a no-op.
223 On target machines that have instruction caches, @value{GDBN} requires this
224 function to make certain that the state of your program is stable.
228 You must also make sure this library routine is available:
231 @item void *memset(void *, int, int)
233 This is the standard library function @code{memset} that sets an area of
234 memory to a known value. If you have one of the free versions of
235 @code{libc.a}, @code{memset} can be found there; otherwise, you must
236 either obtain it from your hardware manufacturer, or write your own.
239 If you do not use the GNU C compiler, you may need other standard
240 library subroutines as well; this varies from one stub to another,
241 but in general the stubs are likely to use any of the common library
242 subroutines which @code{gcc} generates as inline code.
246 @subsubsection Putting it all together
248 @cindex remote serial debugging summary
249 In summary, when your program is ready to debug, you must follow these
254 Make sure you have the supporting low-level routines
255 (@pxref{Bootstrapping,,What you must do for the stub}):
257 @code{getDebugChar}, @code{putDebugChar},
258 @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
262 Insert these lines near the top of your program:
270 For the 680x0 stub only, you need to provide a variable called
271 @code{exceptionHook}. Normally you just use:
274 void (*exceptionHook)() = 0;
277 but if before calling @code{set_debug_traps}, you set it to point to a
278 function in your program, that function is called when
279 @code{@value{GDBN}} continues after stopping on a trap (for example, bus
280 error). The function indicated by @code{exceptionHook} is called with
281 one parameter: an @code{int} which is the exception number.
284 Compile and link together: your program, the @value{GDBN} debugging stub for
285 your target architecture, and the supporting subroutines.
288 Make sure you have a serial connection between your target machine and
289 the @value{GDBN} host, and identify the serial port on the host.
292 @c The "remote" target now provides a `load' command, so we should
293 @c document that. FIXME.
294 Download your program to your target machine (or get it there by
295 whatever means the manufacturer provides), and start it.
298 To start remote debugging, run @value{GDBN} on the host machine, and specify
299 as an executable file the program that is running in the remote machine.
300 This tells @value{GDBN} how to find your program's symbols and the contents
303 @cindex serial line, @code{target remote}
304 Then establish communication using the @code{target remote} command.
305 Its argument specifies how to communicate with the target
306 machine---either via a devicename attached to a direct serial line, or a
307 TCP port (usually to a terminal server which in turn has a serial line
308 to the target). For example, to use a serial line connected to the
309 device named @file{/dev/ttyb}:
312 target remote /dev/ttyb
315 @cindex TCP port, @code{target remote}
316 To use a TCP connection, use an argument of the form
317 @code{@var{host}:port}. For example, to connect to port 2828 on a
318 terminal server named @code{manyfarms}:
321 target remote manyfarms:2828
325 Now you can use all the usual commands to examine and change data and to
326 step and continue the remote program.
328 To resume the remote program and stop debugging it, use the @code{detach}
331 @cindex interrupting remote programs
332 @cindex remote programs, interrupting
333 Whenever @value{GDBN} is waiting for the remote program, if you type the
334 interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
335 program. This may or may not succeed, depending in part on the hardware
336 and the serial drivers the remote system uses. If you type the
337 interrupt character once again, @value{GDBN} displays this prompt:
340 Interrupted while waiting for the program.
341 Give up (and stop debugging it)? (y or n)
344 If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
345 (If you decide you want to try again later, you can use @samp{target
346 remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
347 goes back to waiting.
350 @subsubsection Communication protocol
352 @cindex debugging stub, example
353 @cindex remote stub, example
354 @cindex stub example, remote debugging
355 The stub files provided with @value{GDBN} implement the target side of the
356 communication protocol, and the @value{GDBN} side is implemented in the
357 @value{GDBN} source file @file{remote.c}. Normally, you can simply allow
358 these subroutines to communicate, and ignore the details. (If you're
359 implementing your own stub file, you can still ignore the details: start
360 with one of the existing stub files. @file{sparc-stub.c} is the best
361 organized, and therefore the easiest to read.)
363 However, there may be occasions when you need to know something about
364 the protocol---for example, if there is only one serial port to your
365 target machine, you might want your program to do something special if
366 it recognizes a packet meant for @value{GDBN}.
368 @cindex protocol, @value{GDBN} remote serial
369 @cindex serial protocol, @value{GDBN} remote
370 @cindex remote serial protocol
371 All @value{GDBN} commands and responses (other than acknowledgements, which
372 are single characters) are sent as a packet which includes a
373 checksum. A packet is introduced with the character @samp{$}, and ends
374 with the character @samp{#} followed by a two-digit checksum:
377 $@var{packet info}#@var{checksum}
380 @cindex checksum, for @value{GDBN} remote
382 @var{checksum} is computed as the modulo 256 sum of the @var{packet
385 When either the host or the target machine receives a packet, the first
386 response expected is an acknowledgement: a single character, either
387 @samp{+} (to indicate the package was received correctly) or @samp{-}
388 (to request retransmission).
390 The host (@value{GDBN}) sends commands, and the target (the debugging stub
391 incorporated in your program) sends data in response. The target also
392 sends data when your program stops.
394 Command packets are distinguished by their first character, which
395 identifies the kind of command.
397 These are some of the commands currently supported (for a complete list of
398 commands, look in @file{gdb/remote.c.}):
402 Requests the values of CPU registers.
405 Sets the values of CPU registers.
407 @item m@var{addr},@var{count}
408 Read @var{count} bytes at location @var{addr}.
410 @item M@var{addr},@var{count}:@dots{}
411 Write @var{count} bytes at location @var{addr}.
416 Resume execution at the current address (or at @var{addr} if supplied).
421 Step the target program for one instruction, from either the current
422 program counter or from @var{addr} if supplied.
425 Kill the target program.
428 Report the most recent signal. To allow you to take advantage of the
429 @value{GDBN} signal handling commands, one of the functions of the debugging
430 stub is to report CPU traps as the corresponding POSIX signal values.
433 Allows the remote stub to send only the registers that @value{GDBN} needs
434 to make a quick decision about single-stepping or conditional breakpoints.
435 This eliminates the need to fetch the entire register set for each instruction
436 being stepped through.
438 @value{GDBN} now implements a write-through cache for registers and only
439 re-reads the registers if the target has run.
442 @kindex set remotedebug
443 @kindex show remotedebug
444 @cindex packets, reporting on stdout
445 @cindex serial connections, debugging
446 If you have trouble with the serial connection, you can use the command
447 @code{set remotedebug}. This makes @value{GDBN} report on all packets sent
448 back and forth across the serial line to the remote machine. The
449 packet-debugging information is printed on the @value{GDBN} standard output
450 stream. @code{set remotedebug off} turns it off, and @code{show
451 remotedebug} shows you its current state.
454 @subsubsection Using the @code{gdbserver} program
457 @cindex remote connection without stubs
458 @code{gdbserver} is a control program for Unix-like systems, which
459 allows you to connect your program with a remote @value{GDBN} via
460 @code{target remote}---but without linking in the usual debugging stub.
462 @code{gdbserver} is not a complete replacement for the debugging stubs,
463 because it requires essentially the same operating-system facilities
464 that @value{GDBN} itself does. In fact, a system that can run
465 @code{gdbserver} to connect to a remote @value{GDBN} could also run
466 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
467 because it is a much smaller program than @value{GDBN} itself. It is
468 also easier to port than all of @value{GDBN}, so you may be able to get
469 started more quickly on a new system by using @code{gdbserver}.
470 Finally, if you develop code for real-time systems, you may find that
471 the tradeoffs involved in real-time operation make it more convenient to
472 do as much development work as possible on another system, for example
473 by cross-compiling. You can use @code{gdbserver} to make a similar
474 choice for debugging.
476 @value{GDBN} and @code{gdbserver} communicate via either a serial line
477 or a TCP connection, using the standard @value{GDBN} remote serial
481 @item On the target machine,
482 you need to have a copy of the program you want to debug.
483 @code{gdbserver} does not need your program's symbol table, so you can
484 strip the program if necessary to save space. @value{GDBN} on the host
485 system does all the symbol handling.
487 To use the server, you must tell it how to communicate with @value{GDBN};
488 the name of your program; and the arguments for your program. The
492 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
495 @var{comm} is either a device name (to use a serial line) or a TCP
496 hostname and portnumber. For example, to debug Emacs with the argument
497 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
501 target> gdbserver /dev/com1 emacs foo.txt
504 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
507 To use a TCP connection instead of a serial line:
510 target> gdbserver host:2345 emacs foo.txt
513 The only difference from the previous example is the first argument,
514 specifying that you are communicating with the host @value{GDBN} via
515 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
516 expect a TCP connection from machine @samp{host} to local TCP port 2345.
517 (Currently, the @samp{host} part is ignored.) You can choose any number
518 you want for the port number as long as it does not conflict with any
519 TCP ports already in use on the target system (for example, @code{23} is
520 reserved for @code{telnet}).@footnote{If you choose a port number that
521 conflicts with another service, @code{gdbserver} prints an error message
522 and exits.} You must use the same port number with the host @value{GDBN}
523 @code{target remote} command.
525 @item On the @value{GDBN} host machine,
526 you need an unstripped copy of your program, since @value{GDBN} needs
527 symbols and debugging information. Start up @value{GDBN} as usual,
528 using the name of the local copy of your program as the first argument.
529 (You may also need the @w{@samp{--baud}} option if the serial line is
530 running at anything other than 9600 bps.) After that, use @code{target
531 remote} to establish communications with @code{gdbserver}. Its argument
532 is either a device name (usually a serial device, like
533 @file{/dev/ttyb}), or a TCP port descriptor in the form
534 @code{@var{host}:@var{PORT}}. For example:
537 (@value{GDBP}) target remote /dev/ttyb
541 communicates with the server via serial line @file{/dev/ttyb}, and
544 (@value{GDBP}) target remote the-target:2345
548 communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
549 For TCP connections, you must start up @code{gdbserver} prior to using
550 the @code{target remote} command. Otherwise you may get an error whose
551 text depends on the host system, but which usually looks something like
552 @samp{Connection refused}.
556 @subsubsection Using the @code{gdbserve.nlm} program
559 @code{gdbserve.nlm} is a control program for NetWare systems, which
560 allows you to connect your program with a remote @value{GDBN} via
561 @code{target remote}.
563 @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
564 using the standard @value{GDBN} remote serial protocol.
567 @item On the target machine,
568 you need to have a copy of the program you want to debug.
569 @code{gdbserve.nlm} does not need your program's symbol table, so you
570 can strip the program if necessary to save space. @value{GDBN} on the
571 host system does all the symbol handling.
573 To use the server, you must tell it how to communicate with
574 @value{GDBN}; the name of your program; and the arguments for your
575 program. The syntax is:
578 load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
579 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
582 @var{board} and @var{port} specify the serial line; @var{baud} specifies
583 the baud rate used by the connection. @var{port} and @var{node} default
584 to 0, @var{baud} defaults to 9600 bps.
586 For example, to debug Emacs with the argument @samp{foo.txt}and
587 communicate with @value{GDBN} over serial port number 2 or board 1
588 using a 19200 bps connection:
591 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
594 @item On the @value{GDBN} host machine,
595 you need an unstripped copy of your program, since @value{GDBN} needs
596 symbols and debugging information. Start up @value{GDBN} as usual,
597 using the name of the local copy of your program as the first argument.
598 (You may also need the @w{@samp{--baud}} option if the serial line is
599 running at anything other than 9600 bps. After that, use @code{target
600 remote} to establish communications with @code{gdbserve.nlm}. Its
601 argument is a device name (usually a serial device, like
602 @file{/dev/ttyb}). For example:
605 (@value{GDBP}) target remote /dev/ttyb
609 communications with the server via serial line @file{/dev/ttyb}.
612 @node i960-Nindy Remote
613 @subsection @value{GDBN} with a remote i960 (Nindy)
617 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
618 @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
619 tell @value{GDBN} how to connect to the 960 in several ways:
623 Through command line options specifying serial port, version of the
624 Nindy protocol, and communications speed;
627 By responding to a prompt on startup;
630 By using the @code{target} command at any point during your @value{GDBN}
631 session. @xref{Target Commands, ,Commands for managing targets}.
636 * Nindy Startup:: Startup with Nindy
637 * Nindy Options:: Options for Nindy
638 * Nindy Reset:: Nindy reset command
642 @subsubsection Startup with Nindy
644 If you simply start @code{@value{GDBP}} without using any command-line
645 options, you are prompted for what serial port to use, @emph{before} you
646 reach the ordinary @value{GDBN} prompt:
649 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
653 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
654 identifies the serial port you want to use. You can, if you choose,
655 simply start up with no Nindy connection by responding to the prompt
656 with an empty line. If you do this and later wish to attach to Nindy,
657 use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
660 @subsubsection Options for Nindy
662 These are the startup options for beginning your @value{GDBN} session with a
663 Nindy-960 board attached:
667 Specify the serial port name of a serial interface to be used to connect
668 to the target system. This option is only available when @value{GDBN} is
669 configured for the Intel 960 target architecture. You may specify
670 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
671 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
672 suffix for a specific @code{tty} (e.g. @samp{-r a}).
675 (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
676 the ``old'' Nindy monitor protocol to connect to the target system.
677 This option is only available when @value{GDBN} is configured for the Intel 960
681 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
682 connect to a target system that expects the newer protocol, the connection
683 fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
684 attempts to reconnect at several different line speeds. You can abort
685 this process with an interrupt.
689 Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
690 system, in an attempt to reset it, before connecting to a Nindy target.
693 @emph{Warning:} Many target systems do not have the hardware that this
694 requires; it only works with a few boards.
698 The standard @samp{-b} option controls the line speed used on the serial
703 @subsubsection Nindy reset command
708 For a Nindy target, this command sends a ``break'' to the remote target
709 system; this is only useful if the target has been equipped with a
710 circuit to perform a hard reset (or some other interesting action) when
716 @subsection The UDI protocol for AMD29K
719 @cindex AMD29K via UDI
720 @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
721 protocol for debugging the a29k processor family. To use this
722 configuration with AMD targets running the MiniMON monitor, you need the
723 program @code{MONTIP}, available from AMD at no charge. You can also
724 use @value{GDBN} with the UDI-conformant a29k simulator program
725 @code{ISSTIP}, also available from AMD.
728 @item target udi @var{keyword}
730 Select the UDI interface to a remote a29k board or simulator, where
731 @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
732 This file contains keyword entries which specify parameters used to
733 connect to a29k targets. If the @file{udi_soc} file is not in your
734 working directory, you must set the environment variable @samp{UDICONF}
739 @subsection The EBMON protocol for AMD29K
742 @cindex running 29K programs
744 AMD distributes a 29K development board meant to fit in a PC, together
745 with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
746 term, this development system is called the ``EB29K''. To use
747 @value{GDBN} from a Unix system to run programs on the EB29K board, you
748 must first connect a serial cable between the PC (which hosts the EB29K
749 board) and a serial port on the Unix system. In the following, we
750 assume you've hooked the cable between the PC's @file{COM1} port and
751 @file{/dev/ttya} on the Unix system.
754 * Comms (EB29K):: Communications setup
755 * gdb-EB29K:: EB29K cross-debugging
756 * Remote Log:: Remote log
760 @subsubsection Communications setup
762 The next step is to set up the PC's port, by doing something like this
766 C:\> MODE com1:9600,n,8,1,none
770 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
771 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
772 you must match the communications parameters when establishing the Unix
773 end of the connection as well.
774 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
775 @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
777 To give control of the PC to the Unix side of the serial line, type
778 the following at the DOS console:
785 (Later, if you wish to return control to the DOS console, you can use
786 the command @code{CTTY con}---but you must send it over the device that
787 had control, in our example over the @file{COM1} serial line).
789 From the Unix host, use a communications program such as @code{tip} or
790 @code{cu} to communicate with the PC; for example,
793 cu -s 9600 -l /dev/ttya
797 The @code{cu} options shown specify, respectively, the linespeed and the
798 serial port to use. If you use @code{tip} instead, your command line
799 may look something like the following:
806 Your system may require a different name where we show
807 @file{/dev/ttya} as the argument to @code{tip}. The communications
808 parameters, including which port to use, are associated with the
809 @code{tip} argument in the ``remote'' descriptions file---normally the
810 system table @file{/etc/remote}.
811 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
812 @c the DOS side's comms setup? cu can support -o (odd
813 @c parity), -e (even parity)---apparently no settings for no parity or
814 @c for character size. Taken from stty maybe...? John points out tip
815 @c can set these as internal variables, eg ~s parity=none; man stty
816 @c suggests that it *might* work to stty these options with stdin or
817 @c stdout redirected... ---doc@cygnus.com, 25feb91
820 Using the @code{tip} or @code{cu} connection, change the DOS working
821 directory to the directory containing a copy of your 29K program, then
822 start the PC program @code{EBMON} (an EB29K control program supplied
823 with your board by AMD). You should see an initial display from
824 @code{EBMON} similar to the one that follows, ending with the
825 @code{EBMON} prompt @samp{#}---
830 G:\> CD \usr\joe\work29k
832 G:\USR\JOE\WORK29K> EBMON
833 Am29000 PC Coprocessor Board Monitor, version 3.0-18
834 Copyright 1990 Advanced Micro Devices, Inc.
835 Written by Gibbons and Associates, Inc.
837 Enter '?' or 'H' for help
839 PC Coprocessor Type = EB29K
841 Memory Base = 0xd0000
843 Data Memory Size = 2048KB
844 Available I-RAM Range = 0x8000 to 0x1fffff
845 Available D-RAM Range = 0x80002000 to 0x801fffff
848 Register Stack Size = 0x800
849 Memory Stack Size = 0x1800
852 Am29027 Available = No
853 Byte Write Available = Yes
858 Then exit the @code{cu} or @code{tip} program (done in the example by
859 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
860 running, ready for @value{GDBN} to take over.
862 For this example, we've assumed what is probably the most convenient
863 way to make sure the same 29K program is on both the PC and the Unix
864 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
865 PC as a file system on the Unix host. If you do not have PC/NFS or
866 something similar connecting the two systems, you must arrange some
867 other way---perhaps floppy-disk transfer---of getting the 29K program
868 from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
872 @subsubsection EB29K cross-debugging
874 Finally, @code{cd} to the directory containing an image of your 29K
875 program on the Unix system, and start @value{GDBN}---specifying as argument the
876 name of your 29K program:
884 Now you can use the @code{target} command:
887 target amd-eb /dev/ttya 9600 MYFOO
888 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
889 @c emphasize that this is the name as seen by DOS (since I think DOS is
890 @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
894 In this example, we've assumed your program is in a file called
895 @file{myfoo}. Note that the filename given as the last argument to
896 @code{target amd-eb} should be the name of the program as it appears to DOS.
897 In our example this is simply @code{MYFOO}, but in general it can include
898 a DOS path, and depending on your transfer mechanism may not resemble
899 the name on the Unix side.
901 At this point, you can set any breakpoints you wish; when you are ready
902 to see your program run on the 29K board, use the @value{GDBN} command
905 To stop debugging the remote program, use the @value{GDBN} @code{detach}
908 To return control of the PC to its console, use @code{tip} or @code{cu}
909 once again, after your @value{GDBN} session has concluded, to attach to
910 @code{EBMON}. You can then type the command @code{q} to shut down
911 @code{EBMON}, returning control to the DOS command-line interpreter.
912 Type @code{CTTY con} to return command input to the main DOS console,
913 and type @kbd{~.} to leave @code{tip} or @code{cu}.
916 @subsubsection Remote log
918 @cindex log file for EB29K
920 The @code{target amd-eb} command creates a file @file{eb.log} in the
921 current working directory, to help debug problems with the connection.
922 @file{eb.log} records all the output from @code{EBMON}, including echoes
923 of the commands sent to it. Running @samp{tail -f} on this file in
924 another window often helps to understand trouble with @code{EBMON}, or
925 unexpected events on the PC side of the connection.
928 @subsection @value{GDBN} with a Tandem ST2000
930 To connect your ST2000 to the host system, see the manufacturer's
931 manual. Once the ST2000 is physically attached, you can run:
934 target st2000 @var{dev} @var{speed}
938 to establish it as your debugging environment. @var{dev} is normally
939 the name of a serial device, such as @file{/dev/ttya}, connected to the
940 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
941 connection (for example, to a serial line attached via a terminal
942 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
944 The @code{load} and @code{attach} commands are @emph{not} defined for
945 this target; you must load your program into the ST2000 as you normally
946 would for standalone operation. @value{GDBN} reads debugging information
947 (such as symbols) from a separate, debugging version of the program
948 available on your host computer.
949 @c FIXME!! This is terribly vague; what little content is here is
950 @c basically hearsay.
952 @cindex ST2000 auxiliary commands
953 These auxiliary @value{GDBN} commands are available to help you with the ST2000
957 @item st2000 @var{command}
958 @kindex st2000 @var{cmd}
959 @cindex STDBUG commands (ST2000)
960 @cindex commands to STDBUG (ST2000)
961 Send a @var{command} to the STDBUG monitor. See the manufacturer's
962 manual for available commands.
965 @cindex connect (to STDBUG)
966 Connect the controlling terminal to the STDBUG command monitor. When
967 you are done interacting with STDBUG, typing either of two character
968 sequences gets you back to the @value{GDBN} command prompt:
969 @kbd{@key{RET}~.} (Return, followed by tilde and period) or
970 @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
974 @subsection @value{GDBN} and VxWorks
978 @value{GDBN} enables developers to spawn and debug tasks running on networked
979 VxWorks targets from a Unix host. Already-running tasks spawned from
980 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
981 both the Unix host and on the VxWorks target. The program
982 @code{gdb} is installed and executed on the Unix host. (It may be
983 installed with the name @code{vxgdb}, to distinguish it from a
984 @value{GDBN} for debugging programs on the host itself.)
987 @item VxWorks-timeout @var{args}
988 @kindex vxworks-timeout
989 All VxWorks-based targets now support the option @code{vxworks-timeout}.
990 This option is set by the user, and @var{args} represents the number of
991 seconds @value{GDBN} waits for responses to rpc's. You might use this if
992 your VxWorks target is a slow software simulator or is on the far side
993 of a thin network line.
996 The following information on connecting to VxWorks was current when
997 this manual was produced; newer releases of VxWorks may use revised
1001 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
1002 to include the remote debugging interface routines in the VxWorks
1003 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
1004 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
1005 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
1006 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1007 information on configuring and remaking VxWorks, see the manufacturer's
1009 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
1011 Once you have included @file{rdb.a} in your VxWorks system image and set
1012 your Unix execution search path to find @value{GDBN}, you are ready to
1013 run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb},
1014 depending on your installation).
1016 @value{GDBN} comes up showing the prompt:
1023 * VxWorks Connection:: Connecting to VxWorks
1024 * VxWorks Download:: VxWorks download
1025 * VxWorks Attach:: Running tasks
1028 @node VxWorks Connection
1029 @subsubsection Connecting to VxWorks
1031 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
1032 network. To connect to a target whose host name is ``@code{tt}'', type:
1035 (vxgdb) target vxworks tt
1039 @value{GDBN} displays messages like these:
1042 Attaching remote machine across net...
1047 @value{GDBN} then attempts to read the symbol tables of any object modules
1048 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
1049 these files by searching the directories listed in the command search
1050 path (@pxref{Environment, ,Your program's environment}); if it fails
1051 to find an object file, it displays a message such as:
1054 prog.o: No such file or directory.
1057 When this happens, add the appropriate directory to the search path with
1058 the @value{GDBN} command @code{path}, and execute the @code{target}
1061 @node VxWorks Download
1062 @subsubsection VxWorks download
1064 @cindex download to VxWorks
1065 If you have connected to the VxWorks target and you want to debug an
1066 object that has not yet been loaded, you can use the @value{GDBN}
1067 @code{load} command to download a file from Unix to VxWorks
1068 incrementally. The object file given as an argument to the @code{load}
1069 command is actually opened twice: first by the VxWorks target in order
1070 to download the code, then by @value{GDBN} in order to read the symbol
1071 table. This can lead to problems if the current working directories on
1072 the two systems differ. If both systems have NFS mounted the same
1073 filesystems, you can avoid these problems by using absolute paths.
1074 Otherwise, it is simplest to set the working directory on both systems
1075 to the directory in which the object file resides, and then to reference
1076 the file by its name, without any path. For instance, a program
1077 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
1078 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
1079 program, type this on VxWorks:
1082 -> cd "@var{vxpath}/vw/demo/rdb"
1085 Then, in @value{GDBN}, type:
1088 (vxgdb) cd @var{hostpath}/vw/demo/rdb
1092 @value{GDBN} displays a response similar to this:
1095 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1098 You can also use the @code{load} command to reload an object module
1099 after editing and recompiling the corresponding source file. Note that
1100 this makes @value{GDBN} delete all currently-defined breakpoints,
1101 auto-displays, and convenience variables, and to clear the value
1102 history. (This is necessary in order to preserve the integrity of
1103 debugger data structures that reference the target system's symbol
1106 @node VxWorks Attach
1107 @subsubsection Running tasks
1109 @cindex running VxWorks tasks
1110 You can also attach to an existing task using the @code{attach} command as
1114 (vxgdb) attach @var{task}
1118 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1119 or suspended when you attach to it. Running tasks are suspended at
1120 the time of attachment.
1122 @node Sparclet Remote
1123 @subsection @value{GDBN} and Sparclet
1126 @value{GDBN} enables developers to debug tasks running on
1127 Sparclet targets from a Unix host.
1128 @value{GDBN} uses code that runs on
1129 both the Unix host and on the Sparclet target. The program
1130 @code{gdb} is installed and executed on the Unix host.
1133 @item timeout @var{args}
1134 @kindex remotetimeout
1135 @value{GDBN} now supports the option @code{remotetimeout}.
1136 This option is set by the user, and @var{args} represents the number of
1137 seconds @value{GDBN} waits for responses.
1141 When compiling for debugging, include the options "-g" to get debug
1142 information and "-Ttext" to relocate the program to where you wish to
1143 load it on the target. You may also want to add the options "-n" or
1144 "-N" in order to reduce the size of the sections.
1147 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
1150 You can use objdump to verify that the addresses are what you intended.
1153 sparclet-aout-objdump --headers --syms prog
1158 your Unix execution search path to find @value{GDBN}, you are ready to
1159 run @value{GDBN}. From your Unix host, run @code{gdb}
1160 (or @code{sparclet-aout-gdb}, depending on your installation).
1162 @value{GDBN} comes up showing the prompt:
1169 * Sparclet File:: Setting the file to debug
1170 * Sparclet Connection:: Connecting to Sparclet
1171 * Sparclet Download:: Sparclet download
1172 * Sparclet Execution:: Running and debugging
1176 @subsubsection Setting file to debug
1178 The @value{GDBN} command @code{file} lets you choose with program to debug.
1185 @value{GDBN} then attempts to read the symbol table of @file{prog}.
1186 @value{GDBN} locates
1187 the file by searching the directories listed in the command search
1189 If the file was compiled with debug information (option "-g"), source
1190 files will be searched as well.
1191 @value{GDBN} locates
1192 the source files by searching the directories listed in the directory search
1193 path (@pxref{Environment, ,Your program's environment}).
1195 to find a file, it displays a message such as:
1198 prog: No such file or directory.
1201 When this happens, add the appropriate directories to the search paths with
1202 the @value{GDBN} commands @code{path} and @code{dir}, and execute the
1203 @code{target} command again.
1205 @node Sparclet Connection
1206 @subsubsection Connecting to Sparclet
1208 The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
1209 To connect to a target on serial port ``@code{ttya}'', type:
1212 (gdbslet) target sparclet /dev/ttya
1213 Remote target sparclet connected to /dev/ttya
1214 main () at ../prog.c:3
1218 @value{GDBN} displays messages like these:
1224 @node Sparclet Download
1225 @subsubsection Sparclet download
1227 @cindex download to Sparclet
1228 Once connected to the Sparclet target,
1229 you can use the @value{GDBN}
1230 @code{load} command to download the file from the host to the target.
1231 The file name and load offset should be given as arguments to the @code{load}
1233 Since the file format is aout, the program must be loaded to the starting
1234 address. You can use objdump to find out what this value is. The load
1235 offset is an offset which is added to the VMA (virtual memory address)
1236 of each of the file's sections.
1237 For instance, if the program
1238 @file{prog} was linked to text address 0x1201000, with data at 0x12010160
1239 and bss at 0x12010170, in @value{GDBN}, type:
1242 (gdbslet) load prog 0x12010000
1243 Loading section .text, size 0xdb0 vma 0x12010000
1246 If the code is loaded at a different address then what the program was linked
1247 to, you may need to use the @code{section} and @code{add-symbol-file} commands
1248 to tell @value{GDBN} where to map the symbol table.
1250 @node Sparclet Execution
1251 @subsubsection Running and debugging
1253 @cindex running and debugging Sparclet programs
1254 You can now begin debugging the task using @value{GDBN}'s execution control
1255 commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
1256 manual for the list of commands.
1260 Breakpoint 1 at 0x12010000: file prog.c, line 3.
1262 Starting program: prog
1263 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
1266 4 char *execarg = "hello!";
1270 @node Hitachi Remote
1271 @subsection @value{GDBN} and Hitachi microprocessors
1272 @value{GDBN} needs to know these things to talk to your
1273 Hitachi SH, H8/300, or H8/500:
1277 that you want to use @samp{target hms}, the remote debugging interface
1278 for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
1279 emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
1280 the default when GDB is configured specifically for the Hitachi SH,
1284 what serial device connects your host to your Hitachi board (the first
1285 serial device available on your host is the default).
1288 what speed to use over the serial device.
1292 * Hitachi Boards:: Connecting to Hitachi boards.
1293 * Hitachi ICE:: Using the E7000 In-Circuit Emulator.
1294 * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
1297 @node Hitachi Boards
1298 @subsubsection Connecting to Hitachi boards
1300 @c only for Unix hosts
1302 @cindex serial device, Hitachi micros
1303 Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
1304 need to explicitly set the serial device. The default @var{port} is the
1305 first available port on your host. This is only necessary on Unix
1306 hosts, where it is typically something like @file{/dev/ttya}.
1309 @cindex serial line speed, Hitachi micros
1310 @code{@value{GDBP}} has another special command to set the communications
1311 speed: @samp{speed @var{bps}}. This command also is only used from Unix
1312 hosts; on DOS hosts, set the line speed as usual from outside GDB with
1313 the DOS @kbd{mode} command (for instance, @w{@samp{mode
1314 com2:9600,n,8,1,p}} for a 9600 bps connection).
1316 The @samp{device} and @samp{speed} commands are available only when you
1317 use a Unix host to debug your Hitachi microprocessor programs. If you
1319 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
1320 called @code{asynctsr} to communicate with the development board
1321 through a PC serial port. You must also use the DOS @code{mode} command
1322 to set up the serial port on the DOS side.
1324 The following sample session illustrates the steps needed to start a
1325 program under @value{GDBN} control on an H8/300. The example uses a
1326 sample H8/300 program called @file{t.x}. The procedure is the same for
1327 the Hitachi SH and the H8/500.
1329 First hook up your development board. In this example, we use a
1330 board attached to serial port @code{COM2}; if you use a different serial
1331 port, substitute its name in the argument of the @code{mode} command.
1332 When you call @code{asynctsr}, the auxiliary comms program used by the
1333 degugger, you give it just the numeric part of the serial port's name;
1334 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
1338 C:\H8300\TEST> asynctsr 2
1339 C:\H8300\TEST> mode com2:9600,n,8,1,p
1341 Resident portion of MODE loaded
1343 COM2: 9600, n, 8, 1, p
1348 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
1349 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
1350 disable it, or even boot without it, to use @code{asynctsr} to control
1351 your development board.
1355 Now that serial communications are set up, and the development board is
1356 connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
1357 the name of your program as the argument. @code{@value{GDBP}} prompts
1358 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
1359 commands to begin your debugging session: @samp{target hms} to specify
1360 cross-debugging to the Hitachi board, and the @code{load} command to
1361 download your program to the board. @code{load} displays the names of
1362 the program's sections, and a @samp{*} for each 2K of data downloaded.
1363 (If you want to refresh @value{GDBN} data on symbols or on the
1364 executable file without downloading, use the @value{GDBN} commands
1365 @code{file} or @code{symbol-file}. These commands, and @code{load}
1366 itself, are described in @ref{Files,,Commands to specify files}.)
1369 (eg-C:\H8300\TEST) @value{GDBP} t.x
1370 GDB is free software and you are welcome to distribute copies
1371 of it under certain conditions; type "show copying" to see
1373 There is absolutely no warranty for GDB; type "show warranty"
1375 GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
1377 Connected to remote H8/300 HMS system.
1379 .text : 0x8000 .. 0xabde ***********
1380 .data : 0xabde .. 0xad30 *
1381 .stack : 0xf000 .. 0xf014 *
1384 At this point, you're ready to run or debug your program. From here on,
1385 you can use all the usual @value{GDBN} commands. The @code{break} command
1386 sets breakpoints; the @code{run} command starts your program;
1387 @code{print} or @code{x} display data; the @code{continue} command
1388 resumes execution after stopping at a breakpoint. You can use the
1389 @code{help} command at any time to find out more about @value{GDBN} commands.
1391 Remember, however, that @emph{operating system} facilities aren't
1392 available on your development board; for example, if your program hangs,
1393 you can't send an interrupt---but you can press the @sc{reset} switch!
1395 Use the @sc{reset} button on the development board
1398 to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
1399 no way to pass an interrupt signal to the development board); and
1402 to return to the @value{GDBN} command prompt after your program finishes
1403 normally. The communications protocol provides no other way for @value{GDBN}
1404 to detect program completion.
1407 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
1408 development board as a ``normal exit'' of your program.
1411 @subsubsection Using the E7000 in-circuit emulator
1413 @kindex target e7000
1414 You can use the E7000 in-circuit emulator to develop code for either the
1415 Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
1416 e7000} command to connect @value{GDBN} to your E7000:
1419 @item target e7000 @var{port} @var{speed}
1420 Use this form if your E7000 is connected to a serial port. The
1421 @var{port} argument identifies what serial port to use (for example,
1422 @samp{com2}). The third argument is the line speed in bits per second
1423 (for example, @samp{9600}).
1425 @item target e7000 @var{hostname}
1426 If your E7000 is installed as a host on a TCP/IP network, you can just
1427 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
1430 @node Hitachi Special
1431 @subsubsection Special @value{GDBN} commands for Hitachi micros
1433 Some @value{GDBN} commands are available only on the H8/300 or the
1434 H8/500 configurations:
1438 @kindex show machine
1439 @item set machine h8300
1440 @itemx set machine h8300h
1441 Condition @value{GDBN} for one of the two variants of the H8/300
1442 architecture with @samp{set machine}. You can use @samp{show machine}
1443 to check which variant is currently in effect.
1445 @kindex set memory @var{mod}
1446 @cindex memory models, H8/500
1447 @item set memory @var{mod}
1449 Specify which H8/500 memory model (@var{mod}) you are using with
1450 @samp{set memory}; check which memory model is in effect with @samp{show
1451 memory}. The accepted values for @var{mod} are @code{small},
1452 @code{big}, @code{medium}, and @code{compact}.
1456 @subsection @value{GDBN} and remote MIPS boards
1459 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
1460 MIPS board attached to a serial line. This is available when
1461 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
1464 Use these @value{GDBN} commands to specify the connection to your target board:
1467 @item target mips @var{port}
1468 @kindex target mips @var{port}
1469 To run a program on the board, start up @code{@value{GDBP}} with the
1470 name of your program as the argument. To connect to the board, use the
1471 command @samp{target mips @var{port}}, where @var{port} is the name of
1472 the serial port connected to the board. If the program has not already
1473 been downloaded to the board, you may use the @code{load} command to
1474 download it. You can then use all the usual @value{GDBN} commands.
1476 For example, this sequence connects to the target board through a serial
1477 port, and loads and runs a program called @var{prog} through the
1481 host$ @value{GDBP} @var{prog}
1482 GDB is free software and @dots{}
1483 (gdb) target mips /dev/ttyb
1484 (gdb) load @var{prog}
1488 @item target mips @var{hostname}:@var{portnumber}
1489 On some @value{GDBN} host configurations, you can specify a TCP
1490 connection (for instance, to a serial line managed by a terminal
1491 concentrator) instead of a serial port, using the syntax
1492 @samp{@var{hostname}:@var{portnumber}}.
1494 @item target pmon @var{port}
1495 @kindex target pmon @var{port}
1497 @item target ddb @var{port}
1498 @kindex target ddb @var{port}
1500 @item target lsi @var{port}
1501 @kindex target lsi @var{port}
1507 @value{GDBN} also supports these special commands for MIPS targets:
1510 @item set processor @var{args}
1511 @itemx show processor
1512 @kindex set processor @var{args}
1513 @kindex show processor
1514 Use the @code{set processor} command to set the type of MIPS
1515 processor when you want to access processor-type-specific registers.
1516 For example, @code{set processor @var{r3041}} tells @value{GDBN}
1517 to use the CPO registers appropriate for the 3041 chip.
1518 Use the @code{show processor} command to see what MIPS processor @value{GDBN}
1519 is using. Use the @code{info reg} command to see what registers
1520 @value{GDBN} is using.
1522 @item set mipsfpu double
1523 @itemx set mipsfpu single
1524 @itemx set mipsfpu none
1527 @kindex show mipsfpu
1528 @cindex MIPS remote floating point
1529 @cindex floating point, MIPS remote
1530 If your target board does not support the MIPS floating point
1531 coprocessor, you should use the command @samp{set mipsfpu none} (if you
1532 need this, you may wish to put the command in your @value{GDBINIT}
1533 file). This tells @value{GDBN} how to find the return value of
1534 functions which return floating point values. It also allows
1535 @value{GDBN} to avoid saving the floating point registers when calling
1536 functions on the board. If you are using a floating point coprocessor
1537 with only single precision floating point support, as on the @sc{r4650}
1538 processor, use the command @samp{set mipsfpu single}. The default
1539 double precision floating point coprocessor may be selected using
1540 @samp{set mipsfpu double}.
1542 In previous versions the only choices were double precision or no
1543 floating point, so @samp{set mipsfpu on} will select double precision
1544 and @samp{set mipsfpu off} will select no floating point.
1546 As usual, you can inquire about the @code{mipsfpu} variable with
1547 @samp{show mipsfpu}.
1549 @item set remotedebug @var{n}
1550 @itemx show remotedebug
1551 @kindex set remotedebug
1552 @kindex show remotedebug
1553 @cindex @code{remotedebug}, MIPS protocol
1554 @cindex MIPS @code{remotedebug} protocol
1555 @c FIXME! For this to be useful, you must know something about the MIPS
1556 @c FIXME...protocol. Where is it described?
1557 You can see some debugging information about communications with the board
1558 by setting the @code{remotedebug} variable. If you set it to @code{1} using
1559 @samp{set remotedebug 1}, every packet is displayed. If you set it
1560 to @code{2}, every character is displayed. You can check the current value
1561 at any time with the command @samp{show remotedebug}.
1563 @item set timeout @var{seconds}
1564 @itemx set retransmit-timeout @var{seconds}
1566 @itemx show retransmit-timeout
1567 @cindex @code{timeout}, MIPS protocol
1568 @cindex @code{retransmit-timeout}, MIPS protocol
1570 @kindex show timeout
1571 @kindex set retransmit-timeout
1572 @kindex show retransmit-timeout
1573 You can control the timeout used while waiting for a packet, in the MIPS
1574 remote protocol, with the @code{set timeout @var{seconds}} command. The
1575 default is 5 seconds. Similarly, you can control the timeout used while
1576 waiting for an acknowledgement of a packet with the @code{set
1577 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
1578 You can inspect both values with @code{show timeout} and @code{show
1579 retransmit-timeout}. (These commands are @emph{only} available when
1580 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
1582 The timeout set by @code{set timeout} does not apply when @value{GDBN}
1583 is waiting for your program to stop. In that case, @value{GDBN} waits
1584 forever because it has no way of knowing how long the program is going
1585 to run before stopping.
1589 @subsection Simulated CPU target
1592 @cindex simulator, Z8000
1593 @cindex Z8000 simulator
1594 @cindex simulator, H8/300 or H8/500
1595 @cindex H8/300 or H8/500 simulator
1596 @cindex simulator, Hitachi SH
1597 @cindex Hitachi SH simulator
1598 @cindex CPU simulator
1599 For some configurations, @value{GDBN} includes a CPU simulator that you
1600 can use instead of a hardware CPU to debug your programs.
1601 Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300,
1602 H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
1605 @cindex simulator, Z8000
1606 @cindex Zilog Z8000 simulator
1607 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
1610 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
1611 unsegmented variant of the Z8000 architecture) or the Z8001 (the
1612 segmented variant). The simulator recognizes which architecture is
1613 appropriate by inspecting the object code.
1616 @item target sim @var{args}
1619 Debug programs on a simulated CPU. If the simulator supports setup
1620 options, specify them via @var{args}.
1624 After specifying this target, you can debug programs for the simulated
1625 CPU in the same style as programs for your host computer; use the
1626 @code{file} command to load a new program image, the @code{run} command
1627 to run your program, and so on.
1629 As well as making available all the usual machine registers (see
1630 @code{info reg}), the Z8000 simulator provides three additional items
1631 of information as specially named registers:
1635 Counts clock-ticks in the simulator.
1638 Counts instructions run in the simulator.
1641 Execution time in 60ths of a second.
1644 You can refer to these values in @value{GDBN} expressions with the usual
1645 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
1646 conditional breakpoint that suspends only after at least 5000
1647 simulated clock ticks.
1649 @c need to add much more detail about sims!