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.
4 @c This text diverted to "Remote Debugging" section in general case;
5 @c however, if we're doing a manual specifically for one of these, it
6 @c belongs up front (in "Getting In and Out" chapter).
10 @subsection The @value{GDBN} remote serial protocol
12 @cindex remote serial debugging, overview
13 To debug a program running on another machine (the debugging
14 @dfn{target} machine), you must first arrange for all the usual
15 prerequisites for the program to run by itself. For example, for a C
20 A startup routine to set up the C runtime environment; these usually
21 have a name like @file{crt0}. The startup routine may be supplied by
22 your hardware supplier, or you may have to write your own.
25 You probably need a C subroutine library to support your program's
26 subroutine calls, notably managing input and output.
29 A way of getting your program to the other machine---for example, a
30 download program. These are often supplied by the hardware
31 manufacturer, but you may have to write your own from hardware
35 The next step is to arrange for your program to use a serial port to
36 communicate with the machine where @value{GDBN} is running (the @dfn{host}
37 machine). In general terms, the scheme looks like this:
41 @value{GDBN} already understands how to use this protocol; when everything
42 else is set up, you can simply use the @samp{target remote} command
43 (@pxref{Targets,,Specifying a Debugging Target}).
46 you must link with your program a few special-purpose subroutines that
47 implement the @value{GDBN} remote serial protocol. The file containing these
48 subroutines is called a @dfn{debugging stub}.
51 On certain remote targets, you can use an auxiliary program
52 @code{gdbserver} instead of linking a stub into your program.
53 @xref{Server,,Using the @code{gdbserver} program}, for details.
57 The debugging stub is specific to the architecture of the remote
58 machine; for example, use @file{sparc-stub.c} to debug programs on
61 @cindex remote serial stub list
62 These working remote stubs are distributed with @value{GDBN}:
70 For Intel 386 and compatible architectures.
74 @cindex Motorola 680x0
76 For Motorola 680x0 architectures.
82 For Hitachi SH architectures.
87 For @sc{sparc} architectures.
93 For Fujitsu @sc{sparclite} architectures.
97 The @file{README} file in the @value{GDBN} distribution may list other
101 * Stub Contents:: What the stub can do for you
102 * Bootstrapping:: What you must do for the stub
103 * Debug Session:: Putting it all together
104 * Protocol:: Outline of the communication protocol
106 * Server:: Using the `gdbserver' program
109 * NetWare:: Using the `gdbserve.nlm' program
114 @subsubsection What the stub can do for you
116 @cindex remote serial stub
117 The debugging stub for your architecture supplies these three
121 @item set_debug_traps
122 @kindex set_debug_traps
123 @cindex remote serial stub, initialization
124 This routine arranges for @code{handle_exception} to run when your
125 program stops. You must call this subroutine explicitly near the
126 beginning of your program.
128 @item handle_exception
129 @kindex handle_exception
130 @cindex remote serial stub, main routine
131 This is the central workhorse, but your program never calls it
132 explicitly---the setup code arranges for @code{handle_exception} to
133 run when a trap is triggered.
135 @code{handle_exception} takes control when your program stops during
136 execution (for example, on a breakpoint), and mediates communications
137 with @value{GDBN} on the host machine. This is where the communications
138 protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
139 representative on the target machine; it begins by sending summary
140 information on the state of your program, then continues to execute,
141 retrieving and transmitting any information @value{GDBN} needs, until you
142 execute a @value{GDBN} command that makes your program resume; at that point,
143 @code{handle_exception} returns control to your own code on the target
147 @cindex @code{breakpoint} subroutine, remote
148 Use this auxiliary subroutine to make your program contain a
149 breakpoint. Depending on the particular situation, this may be the only
150 way for @value{GDBN} to get control. For instance, if your target
151 machine has some sort of interrupt button, you won't need to call this;
152 pressing the interrupt button transfers control to
153 @code{handle_exception}---in effect, to @value{GDBN}. On some machines,
154 simply receiving characters on the serial port may also trigger a trap;
155 again, in that situation, you don't need to call @code{breakpoint} from
156 your own program---simply running @samp{target remote} from the host
157 @value{GDBN} session gets control.
159 Call @code{breakpoint} if none of these is true, or if you simply want
160 to make certain your program stops at a predetermined point for the
161 start of your debugging session.
165 @subsubsection What you must do for the stub
167 @cindex remote stub, support routines
168 The debugging stubs that come with @value{GDBN} are set up for a particular
169 chip architecture, but they have no information about the rest of your
170 debugging target machine.
172 First of all you need to tell the stub how to communicate with the
176 @item int getDebugChar()
178 Write this subroutine to read a single character from the serial port.
179 It may be identical to @code{getchar} for your target system; a
180 different name is used to allow you to distinguish the two if you wish.
182 @item void putDebugChar(int)
184 Write this subroutine to write a single character to the serial port.
185 It may be identical to @code{putchar} for your target system; a
186 different name is used to allow you to distinguish the two if you wish.
189 @cindex control C, and remote debugging
190 @cindex interrupting remote targets
191 If you want @value{GDBN} to be able to stop your program while it is
192 running, you need to use an interrupt-driven serial driver, and arrange
193 for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
194 character). That is the character which @value{GDBN} uses to tell the
195 remote system to stop.
197 Getting the debugging target to return the proper status to @value{GDBN}
198 probably requires changes to the standard stub; one quick and dirty way
199 is to just execute a breakpoint instruction (the ``dirty'' part is that
200 @value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
202 Other routines you need to supply are:
205 @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
206 @kindex exceptionHandler
207 Write this function to install @var{exception_address} in the exception
208 handling tables. You need to do this because the stub does not have any
209 way of knowing what the exception handling tables on your target system
210 are like (for example, the processor's table might be in @sc{rom},
211 containing entries which point to a table in @sc{ram}).
212 @var{exception_number} is the exception number which should be changed;
213 its meaning is architecture-dependent (for example, different numbers
214 might represent divide by zero, misaligned access, etc). When this
215 exception occurs, control should be transferred directly to
216 @var{exception_address}, and the processor state (stack, registers,
217 and so on) should be just as it is when a processor exception occurs. So if
218 you want to use a jump instruction to reach @var{exception_address}, it
219 should be a simple jump, not a jump to subroutine.
221 For the 386, @var{exception_address} should be installed as an interrupt
222 gate so that interrupts are masked while the handler runs. The gate
223 should be at privilege level 0 (the most privileged level). The
224 @sc{sparc} and 68k stubs are able to mask interrup themselves without
225 help from @code{exceptionHandler}.
227 @item void flush_i_cache()
228 @kindex flush_i_cache
229 (sparc and sparclite only) Write this subroutine to flush the
230 instruction cache, if any, on your target machine. If there is no
231 instruction cache, this subroutine may be a no-op.
233 On target machines that have instruction caches, @value{GDBN} requires this
234 function to make certain that the state of your program is stable.
238 You must also make sure this library routine is available:
241 @item void *memset(void *, int, int)
243 This is the standard library function @code{memset} that sets an area of
244 memory to a known value. If you have one of the free versions of
245 @code{libc.a}, @code{memset} can be found there; otherwise, you must
246 either obtain it from your hardware manufacturer, or write your own.
249 If you do not use the GNU C compiler, you may need other standard
250 library subroutines as well; this varies from one stub to another,
251 but in general the stubs are likely to use any of the common library
252 subroutines which @code{gcc} generates as inline code.
256 @subsubsection Putting it all together
258 @cindex remote serial debugging summary
259 In summary, when your program is ready to debug, you must follow these
264 Make sure you have the supporting low-level routines
265 (@pxref{Bootstrapping,,What you must do for the stub}):
267 @code{getDebugChar}, @code{putDebugChar},
268 @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
272 Insert these lines near the top of your program:
280 For the 680x0 stub only, you need to provide a variable called
281 @code{exceptionHook}. Normally you just use:
284 void (*exceptionHook)() = 0;
287 but if before calling @code{set_debug_traps}, you set it to point to a
288 function in your program, that function is called when
289 @code{@value{GDBN}} continues after stopping on a trap (for example, bus
290 error). The function indicated by @code{exceptionHook} is called with
291 one parameter: an @code{int} which is the exception number.
294 Compile and link together: your program, the @value{GDBN} debugging stub for
295 your target architecture, and the supporting subroutines.
298 Make sure you have a serial connection between your target machine and
299 the @value{GDBN} host, and identify the serial port on the host.
302 @c The "remote" target now provides a `load' command, so we should
303 @c document that. FIXME.
304 Download your program to your target machine (or get it there by
305 whatever means the manufacturer provides), and start it.
308 To start remote debugging, run @value{GDBN} on the host machine, and specify
309 as an executable file the program that is running in the remote machine.
310 This tells @value{GDBN} how to find your program's symbols and the contents
313 @cindex serial line, @code{target remote}
314 Then establish communication using the @code{target remote} command.
315 Its argument specifies how to communicate with the target
316 machine---either via a devicename attached to a direct serial line, or a
317 TCP port (usually to a terminal server which in turn has a serial line
318 to the target). For example, to use a serial line connected to the
319 device named @file{/dev/ttyb}:
322 target remote /dev/ttyb
325 @cindex TCP port, @code{target remote}
326 To use a TCP connection, use an argument of the form
327 @code{@var{host}:port}. For example, to connect to port 2828 on a
328 terminal server named @code{manyfarms}:
331 target remote manyfarms:2828
335 Now you can use all the usual commands to examine and change data and to
336 step and continue the remote program.
338 To resume the remote program and stop debugging it, use the @code{detach}
341 @cindex interrupting remote programs
342 @cindex remote programs, interrupting
343 Whenever @value{GDBN} is waiting for the remote program, if you type the
344 interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
345 program. This may or may not succeed, depending in part on the hardware
346 and the serial drivers the remote system uses. If you type the
347 interrupt character once again, @value{GDBN} displays this prompt:
350 Interrupted while waiting for the program.
351 Give up (and stop debugging it)? (y or n)
354 If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
355 (If you decide you want to try again later, you can use @samp{target
356 remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
357 goes back to waiting.
360 @subsubsection Communication protocol
362 @cindex debugging stub, example
363 @cindex remote stub, example
364 @cindex stub example, remote debugging
365 The stub files provided with @value{GDBN} implement the target side of the
366 communication protocol, and the @value{GDBN} side is implemented in the
367 @value{GDBN} source file @file{remote.c}. Normally, you can simply allow
368 these subroutines to communicate, and ignore the details. (If you're
369 implementing your own stub file, you can still ignore the details: start
370 with one of the existing stub files. @file{sparc-stub.c} is the best
371 organized, and therefore the easiest to read.)
373 However, there may be occasions when you need to know something about
374 the protocol---for example, if there is only one serial port to your
375 target machine, you might want your program to do something special if
376 it recognizes a packet meant for @value{GDBN}.
378 @cindex protocol, @value{GDBN} remote serial
379 @cindex serial protocol, @value{GDBN} remote
380 @cindex remote serial protocol
381 All @value{GDBN} commands and responses (other than acknowledgements, which
382 are single characters) are sent as a packet which includes a
383 checksum. A packet is introduced with the character @samp{$}, and ends
384 with the character @samp{#} followed by a two-digit checksum:
387 $@var{packet info}#@var{checksum}
390 @cindex checksum, for @value{GDBN} remote
392 @var{checksum} is computed as the modulo 256 sum of the @var{packet
395 When either the host or the target machine receives a packet, the first
396 response expected is an acknowledgement: a single character, either
397 @samp{+} (to indicate the package was received correctly) or @samp{-}
398 (to request retransmission).
400 The host (@value{GDBN}) sends commands, and the target (the debugging stub
401 incorporated in your program) sends data in response. The target also
402 sends data when your program stops.
404 Command packets are distinguished by their first character, which
405 identifies the kind of command.
407 These are some of the commands currently supported (for a complete list of
408 commands, look in @file{gdb/remote.c.}):
412 Requests the values of CPU registers.
415 Sets the values of CPU registers.
417 @item m@var{addr},@var{count}
418 Read @var{count} bytes at location @var{addr}.
420 @item M@var{addr},@var{count}:@dots{}
421 Write @var{count} bytes at location @var{addr}.
426 Resume execution at the current address (or at @var{addr} if supplied).
431 Step the target program for one instruction, from either the current
432 program counter or from @var{addr} if supplied.
435 Kill the target program.
438 Report the most recent signal. To allow you to take advantage of the
439 @value{GDBN} signal handling commands, one of the functions of the debugging
440 stub is to report CPU traps as the corresponding POSIX signal values.
443 Allows the remote stub to send only the registers that @value{GDBN} needs
444 to make a quick decision about single-stepping or conditional breakpoints.
445 This eliminates the need to fetch the entire register set for each instruction
446 being stepped through.
448 The @value{GDBN} remote serial protocol now implements a write-through
449 cache for registers. @value{GDBN} only re-reads the registers if the
453 @kindex set remotedebug
454 @kindex show remotedebug
455 @cindex packets, reporting on stdout
456 @cindex serial connections, debugging
457 If you have trouble with the serial connection, you can use the command
458 @code{set remotedebug}. This makes @value{GDBN} report on all packets sent
459 back and forth across the serial line to the remote machine. The
460 packet-debugging information is printed on the @value{GDBN} standard output
461 stream. @code{set remotedebug off} turns it off, and @code{show
462 remotedebug} shows you its current state.
466 @subsubsection Using the @code{gdbserver} program
469 @cindex remote connection without stubs
470 @code{gdbserver} is a control program for Unix-like systems, which
471 allows you to connect your program with a remote @value{GDBN} via
472 @code{target remote}---but without linking in the usual debugging stub.
474 @code{gdbserver} is not a complete replacement for the debugging stubs,
475 because it requires essentially the same operating-system facilities
476 that @value{GDBN} itself does. In fact, a system that can run
477 @code{gdbserver} to connect to a remote @value{GDBN} could also run
478 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
479 because it is a much smaller program than @value{GDBN} itself. It is
480 also easier to port than all of @value{GDBN}, so you may be able to get
481 started more quickly on a new system by using @code{gdbserver}.
482 Finally, if you develop code for real-time systems, you may find that
483 the tradeoffs involved in real-time operation make it more convenient to
484 do as much development work as possible on another system, for example
485 by cross-compiling. You can use @code{gdbserver} to make a similar
486 choice for debugging.
488 @value{GDBN} and @code{gdbserver} communicate via either a serial line
489 or a TCP connection, using the standard @value{GDBN} remote serial
493 @item On the target machine,
494 you need to have a copy of the program you want to debug.
495 @code{gdbserver} does not need your program's symbol table, so you can
496 strip the program if necessary to save space. @value{GDBN} on the host
497 system does all the symbol handling.
499 To use the server, you must tell it how to communicate with @value{GDBN};
500 the name of your program; and the arguments for your program. The
504 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
507 @var{comm} is either a device name (to use a serial line) or a TCP
508 hostname and portnumber. For example, to debug Emacs with the argument
509 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
513 target> gdbserver /dev/com1 emacs foo.txt
516 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
519 To use a TCP connection instead of a serial line:
522 target> gdbserver host:2345 emacs foo.txt
525 The only difference from the previous example is the first argument,
526 specifying that you are communicating with the host @value{GDBN} via
527 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
528 expect a TCP connection from machine @samp{host} to local TCP port 2345.
529 (Currently, the @samp{host} part is ignored.) You can choose any number
530 you want for the port number as long as it does not conflict with any
531 TCP ports already in use on the target system (for example, @code{23} is
532 reserved for @code{telnet}).@footnote{If you choose a port number that
533 conflicts with another service, @code{gdbserver} prints an error message
534 and exits.} You must use the same port number with the host @value{GDBN}
535 @code{target remote} command.
537 @item On the @value{GDBN} host machine,
538 you need an unstripped copy of your program, since @value{GDBN} needs
539 symbols and debugging information. Start up @value{GDBN} as usual,
540 using the name of the local copy of your program as the first argument.
541 (You may also need the @w{@samp{--baud}} option if the serial line is
542 running at anything other than 9600 bps.) After that, use @code{target
543 remote} to establish communications with @code{gdbserver}. Its argument
544 is either a device name (usually a serial device, like
545 @file{/dev/ttyb}), or a TCP port descriptor in the form
546 @code{@var{host}:@var{PORT}}. For example:
549 (@value{GDBP}) target remote /dev/ttyb
553 communicates with the server via serial line @file{/dev/ttyb}, and
556 (@value{GDBP}) target remote the-target:2345
560 communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
561 For TCP connections, you must start up @code{gdbserver} prior to using
562 the @code{target remote} command. Otherwise you may get an error whose
563 text depends on the host system, but which usually looks something like
564 @samp{Connection refused}.
570 @subsubsection Using the @code{gdbserve.nlm} program
573 @code{gdbserve.nlm} is a control program for NetWare systems, which
574 allows you to connect your program with a remote @value{GDBN} via
575 @code{target remote}.
577 @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
578 using the standard @value{GDBN} remote serial protocol.
581 @item On the target machine,
582 you need to have a copy of the program you want to debug.
583 @code{gdbserve.nlm} does not need your program's symbol table, so you
584 can strip the program if necessary to save space. @value{GDBN} on the
585 host system does all the symbol handling.
587 To use the server, you must tell it how to communicate with
588 @value{GDBN}; the name of your program; and the arguments for your
589 program. The syntax is:
592 load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
593 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
596 @var{board} and @var{port} specify the serial line; @var{baud} specifies
597 the baud rate used by the connection. @var{port} and @var{node} default
598 to 0, @var{baud} defaults to 9600 bps.
600 For example, to debug Emacs with the argument @samp{foo.txt}and
601 communicate with @value{GDBN} over serial port number 2 or board 1
602 using a 19200 bps connection:
605 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
608 @item On the @value{GDBN} host machine,
609 you need an unstripped copy of your program, since @value{GDBN} needs
610 symbols and debugging information. Start up @value{GDBN} as usual,
611 using the name of the local copy of your program as the first argument.
612 (You may also need the @w{@samp{--baud}} option if the serial line is
613 running at anything other than 9600 bps. After that, use @code{target
614 remote} to establish communications with @code{gdbserve.nlm}. Its
615 argument is a device name (usually a serial device, like
616 @file{/dev/ttyb}). For example:
619 (@value{GDBP}) target remote /dev/ttyb
623 communications with the server via serial line @file{/dev/ttyb}.
630 @node i960-Nindy Remote
631 @subsection @value{GDBN} with a remote i960 (Nindy)
635 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
636 @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
637 tell @value{GDBN} how to connect to the 960 in several ways:
641 Through command line options specifying serial port, version of the
642 Nindy protocol, and communications speed;
645 By responding to a prompt on startup;
648 By using the @code{target} command at any point during your @value{GDBN}
649 session. @xref{Target Commands, ,Commands for managing targets}.
654 * Nindy Startup:: Startup with Nindy
655 * Nindy Options:: Options for Nindy
656 * Nindy Reset:: Nindy reset command
660 @subsubsection Startup with Nindy
662 If you simply start @code{@value{GDBP}} without using any command-line
663 options, you are prompted for what serial port to use, @emph{before} you
664 reach the ordinary @value{GDBN} prompt:
667 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
671 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
672 identifies the serial port you want to use. You can, if you choose,
673 simply start up with no Nindy connection by responding to the prompt
674 with an empty line. If you do this and later wish to attach to Nindy,
675 use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
678 @subsubsection Options for Nindy
680 These are the startup options for beginning your @value{GDBN} session with a
681 Nindy-960 board attached:
685 Specify the serial port name of a serial interface to be used to connect
686 to the target system. This option is only available when @value{GDBN} is
687 configured for the Intel 960 target architecture. You may specify
688 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
689 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
690 suffix for a specific @code{tty} (e.g. @samp{-r a}).
693 (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
694 the ``old'' Nindy monitor protocol to connect to the target system.
695 This option is only available when @value{GDBN} is configured for the Intel 960
699 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
700 connect to a target system that expects the newer protocol, the connection
701 fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
702 attempts to reconnect at several different line speeds. You can abort
703 this process with an interrupt.
707 Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
708 system, in an attempt to reset it, before connecting to a Nindy target.
711 @emph{Warning:} Many target systems do not have the hardware that this
712 requires; it only works with a few boards.
716 The standard @samp{-b} option controls the line speed used on the serial
721 @subsubsection Nindy reset command
726 For a Nindy target, this command sends a ``break'' to the remote target
727 system; this is only useful if the target has been equipped with a
728 circuit to perform a hard reset (or some other interesting action) when
736 @subsection The UDI protocol for AMD29K
739 @cindex AMD29K via UDI
740 @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
741 protocol for debugging the a29k processor family. To use this
742 configuration with AMD targets running the MiniMON monitor, you need the
743 program @code{MONTIP}, available from AMD at no charge. You can also
744 use @value{GDBN} with the UDI-conformant a29k simulator program
745 @code{ISSTIP}, also available from AMD.
748 @item target udi @var{keyword}
750 Select the UDI interface to a remote a29k board or simulator, where
751 @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
752 This file contains keyword entries which specify parameters used to
753 connect to a29k targets. If the @file{udi_soc} file is not in your
754 working directory, you must set the environment variable @samp{UDICONF}
759 @subsection The EBMON protocol for AMD29K
762 @cindex running 29K programs
764 AMD distributes a 29K development board meant to fit in a PC, together
765 with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
766 term, this development system is called the ``EB29K''. To use
767 @value{GDBN} from a Unix system to run programs on the EB29K board, you
768 must first connect a serial cable between the PC (which hosts the EB29K
769 board) and a serial port on the Unix system. In the following, we
770 assume you've hooked the cable between the PC's @file{COM1} port and
771 @file{/dev/ttya} on the Unix system.
774 * Comms (EB29K):: Communications setup
775 * gdb-EB29K:: EB29K cross-debugging
776 * Remote Log:: Remote log
780 @subsubsection Communications setup
782 The next step is to set up the PC's port, by doing something like this
786 C:\> MODE com1:9600,n,8,1,none
790 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
791 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
792 you must match the communications parameters when establishing the Unix
793 end of the connection as well.
794 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
795 @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
797 To give control of the PC to the Unix side of the serial line, type
798 the following at the DOS console:
805 (Later, if you wish to return control to the DOS console, you can use
806 the command @code{CTTY con}---but you must send it over the device that
807 had control, in our example over the @file{COM1} serial line).
809 From the Unix host, use a communications program such as @code{tip} or
810 @code{cu} to communicate with the PC; for example,
813 cu -s 9600 -l /dev/ttya
817 The @code{cu} options shown specify, respectively, the linespeed and the
818 serial port to use. If you use @code{tip} instead, your command line
819 may look something like the following:
826 Your system may require a different name where we show
827 @file{/dev/ttya} as the argument to @code{tip}. The communications
828 parameters, including which port to use, are associated with the
829 @code{tip} argument in the ``remote'' descriptions file---normally the
830 system table @file{/etc/remote}.
831 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
832 @c the DOS side's comms setup? cu can support -o (odd
833 @c parity), -e (even parity)---apparently no settings for no parity or
834 @c for character size. Taken from stty maybe...? John points out tip
835 @c can set these as internal variables, eg ~s parity=none; man stty
836 @c suggests that it *might* work to stty these options with stdin or
837 @c stdout redirected... ---doc@cygnus.com, 25feb91
840 Using the @code{tip} or @code{cu} connection, change the DOS working
841 directory to the directory containing a copy of your 29K program, then
842 start the PC program @code{EBMON} (an EB29K control program supplied
843 with your board by AMD). You should see an initial display from
844 @code{EBMON} similar to the one that follows, ending with the
845 @code{EBMON} prompt @samp{#}---
850 G:\> CD \usr\joe\work29k
852 G:\USR\JOE\WORK29K> EBMON
853 Am29000 PC Coprocessor Board Monitor, version 3.0-18
854 Copyright 1990 Advanced Micro Devices, Inc.
855 Written by Gibbons and Associates, Inc.
857 Enter '?' or 'H' for help
859 PC Coprocessor Type = EB29K
861 Memory Base = 0xd0000
863 Data Memory Size = 2048KB
864 Available I-RAM Range = 0x8000 to 0x1fffff
865 Available D-RAM Range = 0x80002000 to 0x801fffff
868 Register Stack Size = 0x800
869 Memory Stack Size = 0x1800
872 Am29027 Available = No
873 Byte Write Available = Yes
878 Then exit the @code{cu} or @code{tip} program (done in the example by
879 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
880 running, ready for @value{GDBN} to take over.
882 For this example, we've assumed what is probably the most convenient
883 way to make sure the same 29K program is on both the PC and the Unix
884 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
885 PC as a file system on the Unix host. If you do not have PC/NFS or
886 something similar connecting the two systems, you must arrange some
887 other way---perhaps floppy-disk transfer---of getting the 29K program
888 from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
892 @subsubsection EB29K cross-debugging
894 Finally, @code{cd} to the directory containing an image of your 29K
895 program on the Unix system, and start @value{GDBN}---specifying as argument the
896 name of your 29K program:
904 Now you can use the @code{target} command:
907 target amd-eb /dev/ttya 9600 MYFOO
908 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
909 @c emphasize that this is the name as seen by DOS (since I think DOS is
910 @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
914 In this example, we've assumed your program is in a file called
915 @file{myfoo}. Note that the filename given as the last argument to
916 @code{target amd-eb} should be the name of the program as it appears to DOS.
917 In our example this is simply @code{MYFOO}, but in general it can include
918 a DOS path, and depending on your transfer mechanism may not resemble
919 the name on the Unix side.
921 At this point, you can set any breakpoints you wish; when you are ready
922 to see your program run on the 29K board, use the @value{GDBN} command
925 To stop debugging the remote program, use the @value{GDBN} @code{detach}
928 To return control of the PC to its console, use @code{tip} or @code{cu}
929 once again, after your @value{GDBN} session has concluded, to attach to
930 @code{EBMON}. You can then type the command @code{q} to shut down
931 @code{EBMON}, returning control to the DOS command-line interpreter.
932 Type @code{CTTY con} to return command input to the main DOS console,
933 and type @kbd{~.} to leave @code{tip} or @code{cu}.
936 @subsubsection Remote log
938 @cindex log file for EB29K
940 The @code{target amd-eb} command creates a file @file{eb.log} in the
941 current working directory, to help debug problems with the connection.
942 @file{eb.log} records all the output from @code{EBMON}, including echoes
943 of the commands sent to it. Running @samp{tail -f} on this file in
944 another window often helps to understand trouble with @code{EBMON}, or
945 unexpected events on the PC side of the connection.
951 @subsection @value{GDBN} with a Tandem ST2000
953 To connect your ST2000 to the host system, see the manufacturer's
954 manual. Once the ST2000 is physically attached, you can run:
957 target st2000 @var{dev} @var{speed}
961 to establish it as your debugging environment. @var{dev} is normally
962 the name of a serial device, such as @file{/dev/ttya}, connected to the
963 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
964 connection (for example, to a serial line attached via a terminal
965 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
967 The @code{load} and @code{attach} commands are @emph{not} defined for
968 this target; you must load your program into the ST2000 as you normally
969 would for standalone operation. @value{GDBN} reads debugging information
970 (such as symbols) from a separate, debugging version of the program
971 available on your host computer.
972 @c FIXME!! This is terribly vague; what little content is here is
973 @c basically hearsay.
975 @cindex ST2000 auxiliary commands
976 These auxiliary @value{GDBN} commands are available to help you with the ST2000
980 @item st2000 @var{command}
981 @kindex st2000 @var{cmd}
982 @cindex STDBUG commands (ST2000)
983 @cindex commands to STDBUG (ST2000)
984 Send a @var{command} to the STDBUG monitor. See the manufacturer's
985 manual for available commands.
988 @cindex connect (to STDBUG)
989 Connect the controlling terminal to the STDBUG command monitor. When
990 you are done interacting with STDBUG, typing either of two character
991 sequences gets you back to the @value{GDBN} command prompt:
992 @kbd{@key{RET}~.} (Return, followed by tilde and period) or
993 @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
999 @subsection @value{GDBN} and VxWorks
1002 @value{GDBN} enables developers to spawn and debug tasks running on networked
1003 VxWorks targets from a Unix host. Already-running tasks spawned from
1004 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
1005 both the Unix host and on the VxWorks target. The program
1006 @code{gdb} is installed and executed on the Unix host. (It may be
1007 installed with the name @code{vxgdb}, to distinguish it from a
1008 @value{GDBN} for debugging programs on the host itself.)
1011 @item VxWorks-timeout @var{args}
1012 @kindex vxworks-timeout
1013 All VxWorks-based targets now support the option @code{vxworks-timeout}.
1014 This option is set by the user, and @var{args} represents the number of
1015 seconds @value{GDBN} waits for responses to rpc's. You might use this if
1016 your VxWorks target is a slow software simulator or is on the far side
1017 of a thin network line.
1020 The following information on connecting to VxWorks was current when
1021 this manual was produced; newer releases of VxWorks may use revised
1025 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
1026 to include the remote debugging interface routines in the VxWorks
1027 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
1028 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
1029 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
1030 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1031 information on configuring and remaking VxWorks, see the manufacturer's
1033 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
1035 Once you have included @file{rdb.a} in your VxWorks system image and set
1036 your Unix execution search path to find @value{GDBN}, you are ready to
1037 run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb},
1038 depending on your installation).
1040 @value{GDBN} comes up showing the prompt:
1047 * VxWorks Connection:: Connecting to VxWorks
1048 * VxWorks Download:: VxWorks download
1049 * VxWorks Attach:: Running tasks
1052 @node VxWorks Connection
1053 @subsubsection Connecting to VxWorks
1055 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
1056 network. To connect to a target whose host name is ``@code{tt}'', type:
1059 (vxgdb) target vxworks tt
1063 @value{GDBN} displays messages like these:
1066 Attaching remote machine across net...
1071 @value{GDBN} then attempts to read the symbol tables of any object modules
1072 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
1073 these files by searching the directories listed in the command search
1074 path (@pxref{Environment, ,Your program's environment}); if it fails
1075 to find an object file, it displays a message such as:
1078 prog.o: No such file or directory.
1081 When this happens, add the appropriate directory to the search path with
1082 the @value{GDBN} command @code{path}, and execute the @code{target}
1085 @node VxWorks Download
1086 @subsubsection VxWorks download
1088 @cindex download to VxWorks
1089 If you have connected to the VxWorks target and you want to debug an
1090 object that has not yet been loaded, you can use the @value{GDBN}
1091 @code{load} command to download a file from Unix to VxWorks
1092 incrementally. The object file given as an argument to the @code{load}
1093 command is actually opened twice: first by the VxWorks target in order
1094 to download the code, then by @value{GDBN} in order to read the symbol
1095 table. This can lead to problems if the current working directories on
1096 the two systems differ. If both systems have NFS mounted the same
1097 filesystems, you can avoid these problems by using absolute paths.
1098 Otherwise, it is simplest to set the working directory on both systems
1099 to the directory in which the object file resides, and then to reference
1100 the file by its name, without any path. For instance, a program
1101 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
1102 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
1103 program, type this on VxWorks:
1106 -> cd "@var{vxpath}/vw/demo/rdb"
1109 Then, in @value{GDBN}, type:
1112 (vxgdb) cd @var{hostpath}/vw/demo/rdb
1116 @value{GDBN} displays a response similar to this:
1119 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1122 You can also use the @code{load} command to reload an object module
1123 after editing and recompiling the corresponding source file. Note that
1124 this makes @value{GDBN} delete all currently-defined breakpoints,
1125 auto-displays, and convenience variables, and to clear the value
1126 history. (This is necessary in order to preserve the integrity of
1127 debugger data structures that reference the target system's symbol
1130 @node VxWorks Attach
1131 @subsubsection Running tasks
1133 @cindex running VxWorks tasks
1134 You can also attach to an existing task using the @code{attach} command as
1138 (vxgdb) attach @var{task}
1142 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1143 or suspended when you attach to it. Running tasks are suspended at
1144 the time of attachment.
1148 @node Sparclet Remote
1149 @subsection @value{GDBN} and Sparclet
1152 @value{GDBN} enables developers to debug tasks running on
1153 Sparclet targets from a Unix host.
1154 @value{GDBN} uses code that runs on
1155 both the Unix host and on the Sparclet target. The program
1156 @code{gdb} is installed and executed on the Unix host.
1159 @item timeout @var{args}
1160 @kindex remotetimeout
1161 @value{GDBN} now supports the option @code{remotetimeout}.
1162 This option is set by the user, and @var{args} represents the number of
1163 seconds @value{GDBN} waits for responses.
1167 When compiling for debugging, include the options "-g" to get debug
1168 information and "-Ttext" to relocate the program to where you wish to
1169 load it on the target. You may also want to add the options "-n" or
1170 "-N" in order to reduce the size of the sections.
1173 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
1176 You can use objdump to verify that the addresses are what you intended.
1179 sparclet-aout-objdump --headers --syms prog
1184 your Unix execution search path to find @value{GDBN}, you are ready to
1185 run @value{GDBN}. From your Unix host, run @code{gdb}
1186 (or @code{sparclet-aout-gdb}, depending on your installation).
1188 @value{GDBN} comes up showing the prompt:
1195 * Sparclet File:: Setting the file to debug
1196 * Sparclet Connection:: Connecting to Sparclet
1197 * Sparclet Download:: Sparclet download
1198 * Sparclet Execution:: Running and debugging
1202 @subsubsection Setting file to debug
1204 The @value{GDBN} command @code{file} lets you choose with program to debug.
1211 @value{GDBN} then attempts to read the symbol table of @file{prog}.
1212 @value{GDBN} locates
1213 the file by searching the directories listed in the command search
1215 If the file was compiled with debug information (option "-g"), source
1216 files will be searched as well.
1217 @value{GDBN} locates
1218 the source files by searching the directories listed in the directory search
1219 path (@pxref{Environment, ,Your program's environment}).
1221 to find a file, it displays a message such as:
1224 prog: No such file or directory.
1227 When this happens, add the appropriate directories to the search paths with
1228 the @value{GDBN} commands @code{path} and @code{dir}, and execute the
1229 @code{target} command again.
1231 @node Sparclet Connection
1232 @subsubsection Connecting to Sparclet
1234 The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
1235 To connect to a target on serial port ``@code{ttya}'', type:
1238 (gdbslet) target sparclet /dev/ttya
1239 Remote target sparclet connected to /dev/ttya
1240 main () at ../prog.c:3
1244 @value{GDBN} displays messages like these:
1250 @node Sparclet Download
1251 @subsubsection Sparclet download
1253 @cindex download to Sparclet
1254 Once connected to the Sparclet target,
1255 you can use the @value{GDBN}
1256 @code{load} command to download the file from the host to the target.
1257 The file name and load offset should be given as arguments to the @code{load}
1259 Since the file format is aout, the program must be loaded to the starting
1260 address. You can use objdump to find out what this value is. The load
1261 offset is an offset which is added to the VMA (virtual memory address)
1262 of each of the file's sections.
1263 For instance, if the program
1264 @file{prog} was linked to text address 0x1201000, with data at 0x12010160
1265 and bss at 0x12010170, in @value{GDBN}, type:
1268 (gdbslet) load prog 0x12010000
1269 Loading section .text, size 0xdb0 vma 0x12010000
1272 If the code is loaded at a different address then what the program was linked
1273 to, you may need to use the @code{section} and @code{add-symbol-file} commands
1274 to tell @value{GDBN} where to map the symbol table.
1276 @node Sparclet Execution
1277 @subsubsection Running and debugging
1279 @cindex running and debugging Sparclet programs
1280 You can now begin debugging the task using @value{GDBN}'s execution control
1281 commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
1282 manual for the list of commands.
1286 Breakpoint 1 at 0x12010000: file prog.c, line 3.
1288 Starting program: prog
1289 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
1292 4 char *execarg = "hello!";
1299 @node Hitachi Remote
1300 @subsection @value{GDBN} and Hitachi microprocessors
1301 @value{GDBN} needs to know these things to talk to your
1302 Hitachi SH, H8/300, or H8/500:
1306 that you want to use @samp{target hms}, the remote debugging interface
1307 for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
1308 emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
1309 the default when GDB is configured specifically for the Hitachi SH,
1313 what serial device connects your host to your Hitachi board (the first
1314 serial device available on your host is the default).
1316 @ifclear H8EXCLUSIVE
1317 @c this is only for Unix hosts, not of interest to Hitachi
1319 what speed to use over the serial device.
1324 * Hitachi Boards:: Connecting to Hitachi boards.
1325 * Hitachi ICE:: Using the E7000 In-Circuit Emulator.
1326 * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
1329 @node Hitachi Boards
1330 @subsubsection Connecting to Hitachi boards
1332 @ifclear H8EXCLUSIVE
1333 @c only for Unix hosts
1335 @cindex serial device, Hitachi micros
1336 Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
1337 need to explicitly set the serial device. The default @var{port} is the
1338 first available port on your host. This is only necessary on Unix
1339 hosts, where it is typically something like @file{/dev/ttya}.
1342 @cindex serial line speed, Hitachi micros
1343 @code{@value{GDBP}} has another special command to set the communications
1344 speed: @samp{speed @var{bps}}. This command also is only used from Unix
1345 hosts; on DOS hosts, set the line speed as usual from outside GDB with
1346 the DOS @kbd{mode} command (for instance, @w{@samp{mode
1347 com2:9600,n,8,1,p}} for a 9600 bps connection).
1349 The @samp{device} and @samp{speed} commands are available only when you
1350 use a Unix host to debug your Hitachi microprocessor programs. If you
1353 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
1354 called @code{asynctsr} to communicate with the development board
1355 through a PC serial port. You must also use the DOS @code{mode} command
1356 to set up the serial port on the DOS side.
1359 The following sample session illustrates the steps needed to start a
1360 program under @value{GDBN} control on an H8/300. The example uses a
1361 sample H8/300 program called @file{t.x}. The procedure is the same for
1362 the Hitachi SH and the H8/500.
1364 First hook up your development board. In this example, we use a
1365 board attached to serial port @code{COM2}; if you use a different serial
1366 port, substitute its name in the argument of the @code{mode} command.
1367 When you call @code{asynctsr}, the auxiliary comms program used by the
1368 degugger, you give it just the numeric part of the serial port's name;
1369 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
1373 C:\H8300\TEST> asynctsr 2
1374 C:\H8300\TEST> mode com2:9600,n,8,1,p
1376 Resident portion of MODE loaded
1378 COM2: 9600, n, 8, 1, p
1383 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
1384 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
1385 disable it, or even boot without it, to use @code{asynctsr} to control
1386 your development board.
1390 Now that serial communications are set up, and the development board is
1391 connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
1392 the name of your program as the argument. @code{@value{GDBP}} prompts
1393 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
1394 commands to begin your debugging session: @samp{target hms} to specify
1395 cross-debugging to the Hitachi board, and the @code{load} command to
1396 download your program to the board. @code{load} displays the names of
1397 the program's sections, and a @samp{*} for each 2K of data downloaded.
1398 (If you want to refresh @value{GDBN} data on symbols or on the
1399 executable file without downloading, use the @value{GDBN} commands
1400 @code{file} or @code{symbol-file}. These commands, and @code{load}
1401 itself, are described in @ref{Files,,Commands to specify files}.)
1404 (eg-C:\H8300\TEST) @value{GDBP} t.x
1405 GDB is free software and you are welcome to distribute copies
1406 of it under certain conditions; type "show copying" to see
1408 There is absolutely no warranty for GDB; type "show warranty"
1410 GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
1412 Connected to remote H8/300 HMS system.
1414 .text : 0x8000 .. 0xabde ***********
1415 .data : 0xabde .. 0xad30 *
1416 .stack : 0xf000 .. 0xf014 *
1419 At this point, you're ready to run or debug your program. From here on,
1420 you can use all the usual @value{GDBN} commands. The @code{break} command
1421 sets breakpoints; the @code{run} command starts your program;
1422 @code{print} or @code{x} display data; the @code{continue} command
1423 resumes execution after stopping at a breakpoint. You can use the
1424 @code{help} command at any time to find out more about @value{GDBN} commands.
1426 Remember, however, that @emph{operating system} facilities aren't
1427 available on your development board; for example, if your program hangs,
1428 you can't send an interrupt---but you can press the @sc{reset} switch!
1430 Use the @sc{reset} button on the development board
1433 to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
1434 no way to pass an interrupt signal to the development board); and
1437 to return to the @value{GDBN} command prompt after your program finishes
1438 normally. The communications protocol provides no other way for @value{GDBN}
1439 to detect program completion.
1442 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
1443 development board as a ``normal exit'' of your program.
1447 @subsubsection Using the E7000 in-circuit emulator
1449 @kindex target e7000
1450 You can use the E7000 in-circuit emulator to develop code for either the
1451 Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
1452 e7000} command to connect @value{GDBN} to your E7000:
1455 @item target e7000 @var{port} @var{speed}
1456 Use this form if your E7000 is connected to a serial port. The
1457 @var{port} argument identifies what serial port to use (for example,
1458 @samp{com2}). The third argument is the line speed in bits per second
1459 (for example, @samp{9600}).
1461 @item target e7000 @var{hostname}
1462 If your E7000 is installed as a host on a TCP/IP network, you can just
1463 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
1466 @node Hitachi Special
1467 @subsubsection Special @value{GDBN} commands for Hitachi micros
1469 Some @value{GDBN} commands are available only on the H8/300 or the
1470 H8/500 configurations:
1474 @kindex show machine
1475 @item set machine h8300
1476 @itemx set machine h8300h
1477 Condition @value{GDBN} for one of the two variants of the H8/300
1478 architecture with @samp{set machine}. You can use @samp{show machine}
1479 to check which variant is currently in effect.
1481 @kindex set memory @var{mod}
1482 @cindex memory models, H8/500
1483 @item set memory @var{mod}
1485 Specify which H8/500 memory model (@var{mod}) you are using with
1486 @samp{set memory}; check which memory model is in effect with @samp{show
1487 memory}. The accepted values for @var{mod} are @code{small},
1488 @code{big}, @code{medium}, and @code{compact}.
1495 @subsection @value{GDBN} and remote MIPS boards
1498 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
1499 MIPS board attached to a serial line. This is available when
1500 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
1503 Use these @value{GDBN} commands to specify the connection to your target board:
1506 @item target mips @var{port}
1507 @kindex target mips @var{port}
1508 To run a program on the board, start up @code{@value{GDBP}} with the
1509 name of your program as the argument. To connect to the board, use the
1510 command @samp{target mips @var{port}}, where @var{port} is the name of
1511 the serial port connected to the board. If the program has not already
1512 been downloaded to the board, you may use the @code{load} command to
1513 download it. You can then use all the usual @value{GDBN} commands.
1515 For example, this sequence connects to the target board through a serial
1516 port, and loads and runs a program called @var{prog} through the
1520 host$ @value{GDBP} @var{prog}
1521 GDB is free software and @dots{}
1522 (gdb) target mips /dev/ttyb
1523 (gdb) load @var{prog}
1527 @item target mips @var{hostname}:@var{portnumber}
1528 On some @value{GDBN} host configurations, you can specify a TCP
1529 connection (for instance, to a serial line managed by a terminal
1530 concentrator) instead of a serial port, using the syntax
1531 @samp{@var{hostname}:@var{portnumber}}.
1533 @item target pmon @var{port}
1534 @kindex target pmon @var{port}
1536 @item target ddb @var{port}
1537 @kindex target ddb @var{port}
1539 @item target lsi @var{port}
1540 @kindex target lsi @var{port}
1546 @value{GDBN} also supports these special commands for MIPS targets:
1549 @item set processor @var{args}
1550 @itemx show processor
1551 @kindex set processor @var{args}
1552 @kindex show processor
1553 Use the @code{set processor} command to set the type of MIPS
1554 processor when you want to access processor-type-specific registers.
1555 For example, @code{set processor @var{r3041}} tells @value{GDBN}
1556 to use the CPO registers appropriate for the 3041 chip.
1557 Use the @code{show processor} command to see what MIPS processor @value{GDBN}
1558 is using. Use the @code{info reg} command to see what registers
1559 @value{GDBN} is using.
1561 @item set mipsfpu double
1562 @itemx set mipsfpu single
1563 @itemx set mipsfpu none
1566 @kindex show mipsfpu
1567 @cindex MIPS remote floating point
1568 @cindex floating point, MIPS remote
1569 If your target board does not support the MIPS floating point
1570 coprocessor, you should use the command @samp{set mipsfpu none} (if you
1571 need this, you may wish to put the command in your @value{GDBINIT}
1572 file). This tells @value{GDBN} how to find the return value of
1573 functions which return floating point values. It also allows
1574 @value{GDBN} to avoid saving the floating point registers when calling
1575 functions on the board. If you are using a floating point coprocessor
1576 with only single precision floating point support, as on the @sc{r4650}
1577 processor, use the command @samp{set mipsfpu single}. The default
1578 double precision floating point coprocessor may be selected using
1579 @samp{set mipsfpu double}.
1581 In previous versions the only choices were double precision or no
1582 floating point, so @samp{set mipsfpu on} will select double precision
1583 and @samp{set mipsfpu off} will select no floating point.
1585 As usual, you can inquire about the @code{mipsfpu} variable with
1586 @samp{show mipsfpu}.
1588 @item set remotedebug @var{n}
1589 @itemx show remotedebug
1590 @kindex set remotedebug
1591 @kindex show remotedebug
1592 @cindex @code{remotedebug}, MIPS protocol
1593 @cindex MIPS @code{remotedebug} protocol
1594 @c FIXME! For this to be useful, you must know something about the MIPS
1595 @c FIXME...protocol. Where is it described?
1596 You can see some debugging information about communications with the board
1597 by setting the @code{remotedebug} variable. If you set it to @code{1} using
1598 @samp{set remotedebug 1}, every packet is displayed. If you set it
1599 to @code{2}, every character is displayed. You can check the current value
1600 at any time with the command @samp{show remotedebug}.
1602 @item set timeout @var{seconds}
1603 @itemx set retransmit-timeout @var{seconds}
1605 @itemx show retransmit-timeout
1606 @cindex @code{timeout}, MIPS protocol
1607 @cindex @code{retransmit-timeout}, MIPS protocol
1609 @kindex show timeout
1610 @kindex set retransmit-timeout
1611 @kindex show retransmit-timeout
1612 You can control the timeout used while waiting for a packet, in the MIPS
1613 remote protocol, with the @code{set timeout @var{seconds}} command. The
1614 default is 5 seconds. Similarly, you can control the timeout used while
1615 waiting for an acknowledgement of a packet with the @code{set
1616 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
1617 You can inspect both values with @code{show timeout} and @code{show
1618 retransmit-timeout}. (These commands are @emph{only} available when
1619 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
1621 The timeout set by @code{set timeout} does not apply when @value{GDBN}
1622 is waiting for your program to stop. In that case, @value{GDBN} waits
1623 forever because it has no way of knowing how long the program is going
1624 to run before stopping.
1630 @subsection Simulated CPU target
1634 @cindex simulator, Z8000
1635 @cindex Z8000 simulator
1636 @cindex simulator, H8/300 or H8/500
1637 @cindex H8/300 or H8/500 simulator
1638 @cindex simulator, Hitachi SH
1639 @cindex Hitachi SH simulator
1640 @cindex CPU simulator
1641 For some configurations, @value{GDBN} includes a CPU simulator that you
1642 can use instead of a hardware CPU to debug your programs. Currently,
1643 a simulator is available when @value{GDBN} is configured to debug Zilog
1644 Z8000 or Hitachi microprocessor targets.
1649 @cindex simulator, H8/300 or H8/500
1650 @cindex Hitachi H8/300 or H8/500 simulator
1651 @cindex simulator, Hitachi SH
1652 @cindex Hitachi SH simulator
1653 When configured for debugging Hitachi microprocessor targets,
1654 @value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH,
1659 @cindex simulator, Z8000
1660 @cindex Zilog Z8000 simulator
1661 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
1667 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
1668 unsegmented variant of the Z8000 architecture) or the Z8001 (the
1669 segmented variant). The simulator recognizes which architecture is
1670 appropriate by inspecting the object code.
1677 Debug programs on a simulated CPU
1679 (which CPU depends on the @value{GDBN} configuration)
1684 After specifying this target, you can debug programs for the simulated
1685 CPU in the same style as programs for your host computer; use the
1686 @code{file} command to load a new program image, the @code{run} command
1687 to run your program, and so on.
1689 As well as making available all the usual machine registers (see
1690 @code{info reg}), this debugging target provides three additional items
1691 of information as specially named registers:
1695 Counts clock-ticks in the simulator.
1698 Counts instructions run in the simulator.
1701 Execution time in 60ths of a second.
1704 You can refer to these values in @value{GDBN} expressions with the usual
1705 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
1706 conditional breakpoint that suspends only after at least 5000
1707 simulated clock ticks.