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}:
67 For @sc{sparc} architectures.
71 @cindex Motorola 680x0
73 For Motorola 680x0 architectures.
79 For Intel 386 and compatible architectures.
82 The @file{README} file in the @value{GDBN} distribution may list other
86 * Stub Contents:: What the stub can do for you
87 * Bootstrapping:: What you must do for the stub
88 * Debug Session:: Putting it all together
89 * Protocol:: Outline of the communication protocol
91 * Server:: Using the `gdbserver' program
94 * NetWare:: Using the `gdbserve.nlm' program
99 @subsubsection What the stub can do for you
101 @cindex remote serial stub
102 The debugging stub for your architecture supplies these three
106 @item set_debug_traps
107 @kindex set_debug_traps
108 @cindex remote serial stub, initialization
109 This routine arranges for @code{handle_exception} to run when your
110 program stops. You must call this subroutine explicitly near the
111 beginning of your program.
113 @item handle_exception
114 @kindex handle_exception
115 @cindex remote serial stub, main routine
116 This is the central workhorse, but your program never calls it
117 explicitly---the setup code arranges for @code{handle_exception} to
118 run when a trap is triggered.
120 @code{handle_exception} takes control when your program stops during
121 execution (for example, on a breakpoint), and mediates communications
122 with @value{GDBN} on the host machine. This is where the communications
123 protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
124 representative on the target machine; it begins by sending summary
125 information on the state of your program, then continues to execute,
126 retrieving and transmitting any information @value{GDBN} needs, until you
127 execute a @value{GDBN} command that makes your program resume; at that point,
128 @code{handle_exception} returns control to your own code on the target
132 @cindex @code{breakpoint} subroutine, remote
133 Use this auxiliary subroutine to make your program contain a
134 breakpoint. Depending on the particular situation, this may be the only
135 way for @value{GDBN} to get control. For instance, if your target
136 machine has some sort of interrupt button, you won't need to call this;
137 pressing the interrupt button transfers control to
138 @code{handle_exception}---in effect, to @value{GDBN}. On some machines,
139 simply receiving characters on the serial port may also trigger a trap;
140 again, in that situation, you don't need to call @code{breakpoint} from
141 your own program---simply running @samp{target remote} from the host
142 @value{GDBN} session gets control.
144 Call @code{breakpoint} if none of these is true, or if you simply want
145 to make certain your program stops at a predetermined point for the
146 start of your debugging session.
150 @subsubsection What you must do for the stub
152 @cindex remote stub, support routines
153 The debugging stubs that come with @value{GDBN} are set up for a particular
154 chip architecture, but they have no information about the rest of your
155 debugging target machine.
157 First of all you need to tell the stub how to communicate with the
161 @item int getDebugChar()
163 Write this subroutine to read a single character from the serial port.
164 It may be identical to @code{getchar} for your target system; a
165 different name is used to allow you to distinguish the two if you wish.
167 @item void putDebugChar(int)
169 Write this subroutine to write a single character to the serial port.
170 It may be identical to @code{putchar} for your target system; a
171 different name is used to allow you to distinguish the two if you wish.
174 @cindex control C, and remote debugging
175 @cindex interrupting remote targets
176 If you want @value{GDBN} to be able to stop your program while it is
177 running, you need to use an interrupt-driven serial driver, and arrange
178 for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
179 character). That is the character which @value{GDBN} uses to tell the
180 remote system to stop.
182 Getting the debugging target to return the proper status to @value{GDBN}
183 probably requires changes to the standard stub; one quick and dirty way
184 is to just execute a breakpoint instruction (the ``dirty'' part is that
185 @value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
187 Other routines you need to supply are:
190 @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
191 @kindex exceptionHandler
192 Write this function to install @var{exception_address} in the exception
193 handling tables. You need to do this because the stub does not have any
194 way of knowing what the exception handling tables on your target system
195 are like (for example, the processor's table might be in @sc{rom},
196 containing entries which point to a table in @sc{ram}).
197 @var{exception_number} is the exception number which should be changed;
198 its meaning is architecture-dependent (for example, different numbers
199 might represent divide by zero, misaligned access, etc). When this
200 exception occurs, control should be transferred directly to
201 @var{exception_address}, and the processor state (stack, registers,
202 and so on) should be just as it is when a processor exception occurs. So if
203 you want to use a jump instruction to reach @var{exception_address}, it
204 should be a simple jump, not a jump to subroutine.
206 For the 386, @var{exception_address} should be installed as an interrupt
207 gate so that interrupts are masked while the handler runs. The gate
208 should be at privilege level 0 (the most privileged level). The
209 @sc{sparc} and 68k stubs are able to mask interrup themselves without
210 help from @code{exceptionHandler}.
212 @item void flush_i_cache()
213 @kindex flush_i_cache
214 (sparc and sparclite only) Write this subroutine to flush the
215 instruction cache, if any, on your target machine. If there is no
216 instruction cache, this subroutine may be a no-op.
218 On target machines that have instruction caches, @value{GDBN} requires this
219 function to make certain that the state of your program is stable.
223 You must also make sure this library routine is available:
226 @item void *memset(void *, int, int)
228 This is the standard library function @code{memset} that sets an area of
229 memory to a known value. If you have one of the free versions of
230 @code{libc.a}, @code{memset} can be found there; otherwise, you must
231 either obtain it from your hardware manufacturer, or write your own.
234 If you do not use the GNU C compiler, you may need other standard
235 library subroutines as well; this varies from one stub to another,
236 but in general the stubs are likely to use any of the common library
237 subroutines which @code{gcc} generates as inline code.
241 @subsubsection Putting it all together
243 @cindex remote serial debugging summary
244 In summary, when your program is ready to debug, you must follow these
249 Make sure you have the supporting low-level routines
250 (@pxref{Bootstrapping,,What you must do for the stub}):
252 @code{getDebugChar}, @code{putDebugChar},
253 @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
257 Insert these lines near the top of your program:
265 For the 680x0 stub only, you need to provide a variable called
266 @code{exceptionHook}. Normally you just use:
269 void (*exceptionHook)() = 0;
272 but if before calling @code{set_debug_traps}, you set it to point to a
273 function in your program, that function is called when
274 @code{@value{GDBN}} continues after stopping on a trap (for example, bus
275 error). The function indicated by @code{exceptionHook} is called with
276 one parameter: an @code{int} which is the exception number.
279 Compile and link together: your program, the @value{GDBN} debugging stub for
280 your target architecture, and the supporting subroutines.
283 Make sure you have a serial connection between your target machine and
284 the @value{GDBN} host, and identify the serial port on the host.
287 @c The "remote" target now provides a `load' command, so we should
288 @c document that. FIXME.
289 Download your program to your target machine (or get it there by
290 whatever means the manufacturer provides), and start it.
293 To start remote debugging, run @value{GDBN} on the host machine, and specify
294 as an executable file the program that is running in the remote machine.
295 This tells @value{GDBN} how to find your program's symbols and the contents
298 @cindex serial line, @code{target remote}
299 Then establish communication using the @code{target remote} command.
300 Its argument specifies how to communicate with the target
301 machine---either via a devicename attached to a direct serial line, or a
302 TCP port (usually to a terminal server which in turn has a serial line
303 to the target). For example, to use a serial line connected to the
304 device named @file{/dev/ttyb}:
307 target remote /dev/ttyb
310 @cindex TCP port, @code{target remote}
311 To use a TCP connection, use an argument of the form
312 @code{@var{host}:port}. For example, to connect to port 2828 on a
313 terminal server named @code{manyfarms}:
316 target remote manyfarms:2828
320 Now you can use all the usual commands to examine and change data and to
321 step and continue the remote program.
323 To resume the remote program and stop debugging it, use the @code{detach}
326 @cindex interrupting remote programs
327 @cindex remote programs, interrupting
328 Whenever @value{GDBN} is waiting for the remote program, if you type the
329 interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
330 program. This may or may not succeed, depending in part on the hardware
331 and the serial drivers the remote system uses. If you type the
332 interrupt character once again, @value{GDBN} displays this prompt:
335 Interrupted while waiting for the program.
336 Give up (and stop debugging it)? (y or n)
339 If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
340 (If you decide you want to try again later, you can use @samp{target
341 remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
342 goes back to waiting.
345 @subsubsection Communication protocol
347 @cindex debugging stub, example
348 @cindex remote stub, example
349 @cindex stub example, remote debugging
350 The stub files provided with @value{GDBN} implement the target side of the
351 communication protocol, and the @value{GDBN} side is implemented in the
352 @value{GDBN} source file @file{remote.c}. Normally, you can simply allow
353 these subroutines to communicate, and ignore the details. (If you're
354 implementing your own stub file, you can still ignore the details: start
355 with one of the existing stub files. @file{sparc-stub.c} is the best
356 organized, and therefore the easiest to read.)
358 However, there may be occasions when you need to know something about
359 the protocol---for example, if there is only one serial port to your
360 target machine, you might want your program to do something special if
361 it recognizes a packet meant for @value{GDBN}.
363 @cindex protocol, @value{GDBN} remote serial
364 @cindex serial protocol, @value{GDBN} remote
365 @cindex remote serial protocol
366 All @value{GDBN} commands and responses (other than acknowledgements, which
367 are single characters) are sent as a packet which includes a
368 checksum. A packet is introduced with the character @samp{$}, and ends
369 with the character @samp{#} followed by a two-digit checksum:
372 $@var{packet info}#@var{checksum}
375 @cindex checksum, for @value{GDBN} remote
377 @var{checksum} is computed as the modulo 256 sum of the @var{packet
380 When either the host or the target machine receives a packet, the first
381 response expected is an acknowledgement: a single character, either
382 @samp{+} (to indicate the package was received correctly) or @samp{-}
383 (to request retransmission).
385 The host (@value{GDBN}) sends commands, and the target (the debugging stub
386 incorporated in your program) sends data in response. The target also
387 sends data when your program stops.
389 Command packets are distinguished by their first character, which
390 identifies the kind of command.
392 These are some of the commands currently supported (for a complete list of
393 commands, look in @file{gdb/remote.c.}):
397 Requests the values of CPU registers.
400 Sets the values of CPU registers.
402 @item m@var{addr},@var{count}
403 Read @var{count} bytes at location @var{addr}.
405 @item M@var{addr},@var{count}:@dots{}
406 Write @var{count} bytes at location @var{addr}.
411 Resume execution at the current address (or at @var{addr} if supplied).
416 Step the target program for one instruction, from either the current
417 program counter or from @var{addr} if supplied.
420 Kill the target program.
423 Report the most recent signal. To allow you to take advantage of the
424 @value{GDBN} signal handling commands, one of the functions of the debugging
425 stub is to report CPU traps as the corresponding POSIX signal values.
428 Allows the remote stub to send only the registers that @value{GDBN} needs
429 to make a quick decision about single-stepping or conditional breakpoints.
430 This eliminates the need to fetch the entire register set for each instruction
431 being stepped through.
433 The @value{GDBN} remote serial protocol now implements a write-through
434 cache for registers. @value{GDBN} only re-reads the registers if the
438 @kindex set remotedebug
439 @kindex show remotedebug
440 @cindex packets, reporting on stdout
441 @cindex serial connections, debugging
442 If you have trouble with the serial connection, you can use the command
443 @code{set remotedebug}. This makes @value{GDBN} report on all packets sent
444 back and forth across the serial line to the remote machine. The
445 packet-debugging information is printed on the @value{GDBN} standard output
446 stream. @code{set remotedebug off} turns it off, and @code{show
447 remotedebug} shows you its current state.
451 @subsubsection Using the @code{gdbserver} program
454 @cindex remote connection without stubs
455 @code{gdbserver} is a control program for Unix-like systems, which
456 allows you to connect your program with a remote @value{GDBN} via
457 @code{target remote}---but without linking in the usual debugging stub.
459 @code{gdbserver} is not a complete replacement for the debugging stubs,
460 because it requires essentially the same operating-system facilities
461 that @value{GDBN} itself does. In fact, a system that can run
462 @code{gdbserver} to connect to a remote @value{GDBN} could also run
463 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
464 because it is a much smaller program than @value{GDBN} itself. It is
465 also easier to port than all of @value{GDBN}, so you may be able to get
466 started more quickly on a new system by using @code{gdbserver}.
467 Finally, if you develop code for real-time systems, you may find that
468 the tradeoffs involved in real-time operation make it more convenient to
469 do as much development work as possible on another system, for example
470 by cross-compiling. You can use @code{gdbserver} to make a similar
471 choice for debugging.
473 @value{GDBN} and @code{gdbserver} communicate via either a serial line
474 or a TCP connection, using the standard @value{GDBN} remote serial
478 @item On the target machine,
479 you need to have a copy of the program you want to debug.
480 @code{gdbserver} does not need your program's symbol table, so you can
481 strip the program if necessary to save space. @value{GDBN} on the host
482 system does all the symbol handling.
484 To use the server, you must tell it how to communicate with @value{GDBN};
485 the name of your program; and the arguments for your program. The
489 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
492 @var{comm} is either a device name (to use a serial line) or a TCP
493 hostname and portnumber. For example, to debug Emacs with the argument
494 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
498 target> gdbserver /dev/com1 emacs foo.txt
501 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
504 To use a TCP connection instead of a serial line:
507 target> gdbserver host:2345 emacs foo.txt
510 The only difference from the previous example is the first argument,
511 specifying that you are communicating with the host @value{GDBN} via
512 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
513 expect a TCP connection from machine @samp{host} to local TCP port 2345.
514 (Currently, the @samp{host} part is ignored.) You can choose any number
515 you want for the port number as long as it does not conflict with any
516 TCP ports already in use on the target system (for example, @code{23} is
517 reserved for @code{telnet}).@footnote{If you choose a port number that
518 conflicts with another service, @code{gdbserver} prints an error message
519 and exits.} You must use the same port number with the host @value{GDBN}
520 @code{target remote} command.
522 @item On the @value{GDBN} host machine,
523 you need an unstripped copy of your program, since @value{GDBN} needs
524 symbols and debugging information. Start up @value{GDBN} as usual,
525 using the name of the local copy of your program as the first argument.
526 (You may also need the @w{@samp{--baud}} option if the serial line is
527 running at anything other than 9600 bps.) After that, use @code{target
528 remote} to establish communications with @code{gdbserver}. Its argument
529 is either a device name (usually a serial device, like
530 @file{/dev/ttyb}), or a TCP port descriptor in the form
531 @code{@var{host}:@var{PORT}}. For example:
534 (@value{GDBP}) target remote /dev/ttyb
538 communicates with the server via serial line @file{/dev/ttyb}, and
541 (@value{GDBP}) target remote the-target:2345
545 communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
546 For TCP connections, you must start up @code{gdbserver} prior to using
547 the @code{target remote} command. Otherwise you may get an error whose
548 text depends on the host system, but which usually looks something like
549 @samp{Connection refused}.
555 @subsubsection Using the @code{gdbserve.nlm} program
558 @code{gdbserve.nlm} is a control program for NetWare systems, which
559 allows you to connect your program with a remote @value{GDBN} via
560 @code{target remote}.
562 @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
563 using the standard @value{GDBN} remote serial protocol.
566 @item On the target machine,
567 you need to have a copy of the program you want to debug.
568 @code{gdbserve.nlm} does not need your program's symbol table, so you
569 can strip the program if necessary to save space. @value{GDBN} on the
570 host system does all the symbol handling.
572 To use the server, you must tell it how to communicate with
573 @value{GDBN}; the name of your program; and the arguments for your
574 program. The syntax is:
577 load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
578 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
581 @var{board} and @var{port} specify the serial line; @var{baud} specifies
582 the baud rate used by the connection. @var{port} and @var{node} default
583 to 0, @var{baud} defaults to 9600 bps.
585 For example, to debug Emacs with the argument @samp{foo.txt}and
586 communicate with @value{GDBN} over serial port number 2 or board 1
587 using a 19200 bps connection:
590 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
593 @item On the @value{GDBN} host machine,
594 you need an unstripped copy of your program, since @value{GDBN} needs
595 symbols and debugging information. Start up @value{GDBN} as usual,
596 using the name of the local copy of your program as the first argument.
597 (You may also need the @w{@samp{--baud}} option if the serial line is
598 running at anything other than 9600 bps. After that, use @code{target
599 remote} to establish communications with @code{gdbserve.nlm}. Its
600 argument is a device name (usually a serial device, like
601 @file{/dev/ttyb}). For example:
604 (@value{GDBP}) target remote /dev/ttyb
608 communications with the server via serial line @file{/dev/ttyb}.
615 @node i960-Nindy Remote
616 @subsection @value{GDBN} with a remote i960 (Nindy)
620 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
621 @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
622 tell @value{GDBN} how to connect to the 960 in several ways:
626 Through command line options specifying serial port, version of the
627 Nindy protocol, and communications speed;
630 By responding to a prompt on startup;
633 By using the @code{target} command at any point during your @value{GDBN}
634 session. @xref{Target Commands, ,Commands for managing targets}.
639 * Nindy Startup:: Startup with Nindy
640 * Nindy Options:: Options for Nindy
641 * Nindy Reset:: Nindy reset command
645 @subsubsection Startup with Nindy
647 If you simply start @code{@value{GDBP}} without using any command-line
648 options, you are prompted for what serial port to use, @emph{before} you
649 reach the ordinary @value{GDBN} prompt:
652 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
656 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
657 identifies the serial port you want to use. You can, if you choose,
658 simply start up with no Nindy connection by responding to the prompt
659 with an empty line. If you do this and later wish to attach to Nindy,
660 use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
663 @subsubsection Options for Nindy
665 These are the startup options for beginning your @value{GDBN} session with a
666 Nindy-960 board attached:
670 Specify the serial port name of a serial interface to be used to connect
671 to the target system. This option is only available when @value{GDBN} is
672 configured for the Intel 960 target architecture. You may specify
673 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
674 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
675 suffix for a specific @code{tty} (e.g. @samp{-r a}).
678 (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
679 the ``old'' Nindy monitor protocol to connect to the target system.
680 This option is only available when @value{GDBN} is configured for the Intel 960
684 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
685 connect to a target system that expects the newer protocol, the connection
686 fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
687 attempts to reconnect at several different line speeds. You can abort
688 this process with an interrupt.
692 Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
693 system, in an attempt to reset it, before connecting to a Nindy target.
696 @emph{Warning:} Many target systems do not have the hardware that this
697 requires; it only works with a few boards.
701 The standard @samp{-b} option controls the line speed used on the serial
706 @subsubsection Nindy reset command
711 For a Nindy target, this command sends a ``break'' to the remote target
712 system; this is only useful if the target has been equipped with a
713 circuit to perform a hard reset (or some other interesting action) when
721 @subsection The UDI protocol for AMD29K
724 @cindex AMD29K via UDI
725 @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
726 protocol for debugging the a29k processor family. To use this
727 configuration with AMD targets running the MiniMON monitor, you need the
728 program @code{MONTIP}, available from AMD at no charge. You can also
729 use @value{GDBN} with the UDI-conformant a29k simulator program
730 @code{ISSTIP}, also available from AMD.
733 @item target udi @var{keyword}
735 Select the UDI interface to a remote a29k board or simulator, where
736 @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
737 This file contains keyword entries which specify parameters used to
738 connect to a29k targets. If the @file{udi_soc} file is not in your
739 working directory, you must set the environment variable @samp{UDICONF}
744 @subsection The EBMON protocol for AMD29K
747 @cindex running 29K programs
749 AMD distributes a 29K development board meant to fit in a PC, together
750 with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
751 term, this development system is called the ``EB29K''. To use
752 @value{GDBN} from a Unix system to run programs on the EB29K board, you
753 must first connect a serial cable between the PC (which hosts the EB29K
754 board) and a serial port on the Unix system. In the following, we
755 assume you've hooked the cable between the PC's @file{COM1} port and
756 @file{/dev/ttya} on the Unix system.
759 * Comms (EB29K):: Communications setup
760 * gdb-EB29K:: EB29K cross-debugging
761 * Remote Log:: Remote log
765 @subsubsection Communications setup
767 The next step is to set up the PC's port, by doing something like this
771 C:\> MODE com1:9600,n,8,1,none
775 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
776 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
777 you must match the communications parameters when establishing the Unix
778 end of the connection as well.
779 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
780 @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91
782 To give control of the PC to the Unix side of the serial line, type
783 the following at the DOS console:
790 (Later, if you wish to return control to the DOS console, you can use
791 the command @code{CTTY con}---but you must send it over the device that
792 had control, in our example over the @file{COM1} serial line).
794 From the Unix host, use a communications program such as @code{tip} or
795 @code{cu} to communicate with the PC; for example,
798 cu -s 9600 -l /dev/ttya
802 The @code{cu} options shown specify, respectively, the linespeed and the
803 serial port to use. If you use @code{tip} instead, your command line
804 may look something like the following:
811 Your system may require a different name where we show
812 @file{/dev/ttya} as the argument to @code{tip}. The communications
813 parameters, including which port to use, are associated with the
814 @code{tip} argument in the ``remote'' descriptions file---normally the
815 system table @file{/etc/remote}.
816 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
817 @c the DOS side's comms setup? cu can support -o (odd
818 @c parity), -e (even parity)---apparently no settings for no parity or
819 @c for character size. Taken from stty maybe...? John points out tip
820 @c can set these as internal variables, eg ~s parity=none; man stty
821 @c suggests that it *might* work to stty these options with stdin or
822 @c stdout redirected... ---pesch@cygnus.com, 25feb91
825 Using the @code{tip} or @code{cu} connection, change the DOS working
826 directory to the directory containing a copy of your 29K program, then
827 start the PC program @code{EBMON} (an EB29K control program supplied
828 with your board by AMD). You should see an initial display from
829 @code{EBMON} similar to the one that follows, ending with the
830 @code{EBMON} prompt @samp{#}---
835 G:\> CD \usr\joe\work29k
837 G:\USR\JOE\WORK29K> EBMON
838 Am29000 PC Coprocessor Board Monitor, version 3.0-18
839 Copyright 1990 Advanced Micro Devices, Inc.
840 Written by Gibbons and Associates, Inc.
842 Enter '?' or 'H' for help
844 PC Coprocessor Type = EB29K
846 Memory Base = 0xd0000
848 Data Memory Size = 2048KB
849 Available I-RAM Range = 0x8000 to 0x1fffff
850 Available D-RAM Range = 0x80002000 to 0x801fffff
853 Register Stack Size = 0x800
854 Memory Stack Size = 0x1800
857 Am29027 Available = No
858 Byte Write Available = Yes
863 Then exit the @code{cu} or @code{tip} program (done in the example by
864 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
865 running, ready for @value{GDBN} to take over.
867 For this example, we've assumed what is probably the most convenient
868 way to make sure the same 29K program is on both the PC and the Unix
869 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
870 PC as a file system on the Unix host. If you do not have PC/NFS or
871 something similar connecting the two systems, you must arrange some
872 other way---perhaps floppy-disk transfer---of getting the 29K program
873 from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
877 @subsubsection EB29K cross-debugging
879 Finally, @code{cd} to the directory containing an image of your 29K
880 program on the Unix system, and start @value{GDBN}---specifying as argument the
881 name of your 29K program:
889 Now you can use the @code{target} command:
892 target amd-eb /dev/ttya 9600 MYFOO
893 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
894 @c emphasize that this is the name as seen by DOS (since I think DOS is
895 @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91
899 In this example, we've assumed your program is in a file called
900 @file{myfoo}. Note that the filename given as the last argument to
901 @code{target amd-eb} should be the name of the program as it appears to DOS.
902 In our example this is simply @code{MYFOO}, but in general it can include
903 a DOS path, and depending on your transfer mechanism may not resemble
904 the name on the Unix side.
906 At this point, you can set any breakpoints you wish; when you are ready
907 to see your program run on the 29K board, use the @value{GDBN} command
910 To stop debugging the remote program, use the @value{GDBN} @code{detach}
913 To return control of the PC to its console, use @code{tip} or @code{cu}
914 once again, after your @value{GDBN} session has concluded, to attach to
915 @code{EBMON}. You can then type the command @code{q} to shut down
916 @code{EBMON}, returning control to the DOS command-line interpreter.
917 Type @code{CTTY con} to return command input to the main DOS console,
918 and type @kbd{~.} to leave @code{tip} or @code{cu}.
921 @subsubsection Remote log
923 @cindex log file for EB29K
925 The @code{target amd-eb} command creates a file @file{eb.log} in the
926 current working directory, to help debug problems with the connection.
927 @file{eb.log} records all the output from @code{EBMON}, including echoes
928 of the commands sent to it. Running @samp{tail -f} on this file in
929 another window often helps to understand trouble with @code{EBMON}, or
930 unexpected events on the PC side of the connection.
936 @subsection @value{GDBN} with a Tandem ST2000
938 To connect your ST2000 to the host system, see the manufacturer's
939 manual. Once the ST2000 is physically attached, you can run:
942 target st2000 @var{dev} @var{speed}
946 to establish it as your debugging environment. @var{dev} is normally
947 the name of a serial device, such as @file{/dev/ttya}, connected to the
948 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
949 connection (for example, to a serial line attached via a terminal
950 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
952 The @code{load} and @code{attach} commands are @emph{not} defined for
953 this target; you must load your program into the ST2000 as you normally
954 would for standalone operation. @value{GDBN} reads debugging information
955 (such as symbols) from a separate, debugging version of the program
956 available on your host computer.
957 @c FIXME!! This is terribly vague; what little content is here is
958 @c basically hearsay.
960 @cindex ST2000 auxiliary commands
961 These auxiliary @value{GDBN} commands are available to help you with the ST2000
965 @item st2000 @var{command}
966 @kindex st2000 @var{cmd}
967 @cindex STDBUG commands (ST2000)
968 @cindex commands to STDBUG (ST2000)
969 Send a @var{command} to the STDBUG monitor. See the manufacturer's
970 manual for available commands.
973 @cindex connect (to STDBUG)
974 Connect the controlling terminal to the STDBUG command monitor. When
975 you are done interacting with STDBUG, typing either of two character
976 sequences gets you back to the @value{GDBN} command prompt:
977 @kbd{@key{RET}~.} (Return, followed by tilde and period) or
978 @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
984 @subsection @value{GDBN} and VxWorks
987 @value{GDBN} enables developers to spawn and debug tasks running on networked
988 VxWorks targets from a Unix host. Already-running tasks spawned from
989 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
990 both the Unix host and on the VxWorks target. The program
991 @code{gdb} is installed and executed on the Unix host. (It may be
992 installed with the name @code{vxgdb}, to distinguish it from a
993 @value{GDBN} for debugging programs on the host itself.)
996 @item VxWorks-timeout @var{args}
997 @kindex vxworks-timeout
998 All VxWorks-based targets now support the option @code{vxworks-timeout}.
999 This option is set by the user, and @var{args} represents the number of
1000 seconds @value{GDBN} waits for responses to rpc's. You might use this if
1001 your VxWorks target is a slow software simulator or is on the far side
1002 of a thin network line.
1005 The following information on connecting to VxWorks was current when
1006 this manual was produced; newer releases of VxWorks may use revised
1010 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
1011 to include the remote debugging interface routines in the VxWorks
1012 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
1013 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
1014 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
1015 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1016 information on configuring and remaking VxWorks, see the manufacturer's
1018 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
1020 Once you have included @file{rdb.a} in your VxWorks system image and set
1021 your Unix execution search path to find @value{GDBN}, you are ready to
1022 run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb},
1023 depending on your installation).
1025 @value{GDBN} comes up showing the prompt:
1032 * VxWorks Connection:: Connecting to VxWorks
1033 * VxWorks Download:: VxWorks download
1034 * VxWorks Attach:: Running tasks
1037 @node VxWorks Connection
1038 @subsubsection Connecting to VxWorks
1040 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
1041 network. To connect to a target whose host name is ``@code{tt}'', type:
1044 (vxgdb) target vxworks tt
1048 @value{GDBN} displays messages like these:
1051 Attaching remote machine across net...
1056 @value{GDBN} then attempts to read the symbol tables of any object modules
1057 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
1058 these files by searching the directories listed in the command search
1059 path (@pxref{Environment, ,Your program's environment}); if it fails
1060 to find an object file, it displays a message such as:
1063 prog.o: No such file or directory.
1066 When this happens, add the appropriate directory to the search path with
1067 the @value{GDBN} command @code{path}, and execute the @code{target}
1070 @node VxWorks Download
1071 @subsubsection VxWorks download
1073 @cindex download to VxWorks
1074 If you have connected to the VxWorks target and you want to debug an
1075 object that has not yet been loaded, you can use the @value{GDBN}
1076 @code{load} command to download a file from Unix to VxWorks
1077 incrementally. The object file given as an argument to the @code{load}
1078 command is actually opened twice: first by the VxWorks target in order
1079 to download the code, then by @value{GDBN} in order to read the symbol
1080 table. This can lead to problems if the current working directories on
1081 the two systems differ. If both systems have NFS mounted the same
1082 filesystems, you can avoid these problems by using absolute paths.
1083 Otherwise, it is simplest to set the working directory on both systems
1084 to the directory in which the object file resides, and then to reference
1085 the file by its name, without any path. For instance, a program
1086 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
1087 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
1088 program, type this on VxWorks:
1091 -> cd "@var{vxpath}/vw/demo/rdb"
1094 Then, in @value{GDBN}, type:
1097 (vxgdb) cd @var{hostpath}/vw/demo/rdb
1101 @value{GDBN} displays a response similar to this:
1104 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1107 You can also use the @code{load} command to reload an object module
1108 after editing and recompiling the corresponding source file. Note that
1109 this makes @value{GDBN} delete all currently-defined breakpoints,
1110 auto-displays, and convenience variables, and to clear the value
1111 history. (This is necessary in order to preserve the integrity of
1112 debugger data structures that reference the target system's symbol
1115 @node VxWorks Attach
1116 @subsubsection Running tasks
1118 @cindex running VxWorks tasks
1119 You can also attach to an existing task using the @code{attach} command as
1123 (vxgdb) attach @var{task}
1127 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1128 or suspended when you attach to it. Running tasks are suspended at
1129 the time of attachment.
1133 @node Hitachi Remote
1134 @subsection @value{GDBN} and Hitachi microprocessors
1135 @value{GDBN} needs to know these things to talk to your
1136 Hitachi SH, H8/300, or H8/500:
1140 that you want to use @samp{target hms}, the remote debugging interface
1141 for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
1142 emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
1143 the default when GDB is configured specifically for the Hitachi SH,
1147 what serial device connects your host to your Hitachi board (the first
1148 serial device available on your host is the default).
1150 @ifclear H8EXCLUSIVE
1151 @c this is only for Unix hosts, not of interest to Hitachi
1153 what speed to use over the serial device.
1158 * Hitachi Boards:: Connecting to Hitachi boards.
1159 * Hitachi ICE:: Using the E7000 In-Circuit Emulator.
1160 * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
1163 @node Hitachi Boards
1164 @subsubsection Connecting to Hitachi boards
1166 @ifclear H8EXCLUSIVE
1167 @c only for Unix hosts
1169 @cindex serial device, Hitachi micros
1170 Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
1171 need to explicitly set the serial device. The default @var{port} is the
1172 first available port on your host. This is only necessary on Unix
1173 hosts, where it is typically something like @file{/dev/ttya}.
1176 @cindex serial line speed, Hitachi micros
1177 @code{@value{GDBP}} has another special command to set the communications
1178 speed: @samp{speed @var{bps}}. This command also is only used from Unix
1179 hosts; on DOS hosts, set the line speed as usual from outside GDB with
1180 the DOS @kbd{mode} command (for instance, @w{@samp{mode
1181 com2:9600,n,8,1,p}} for a 9600 bps connection).
1183 The @samp{device} and @samp{speed} commands are available only when you
1184 use a Unix host to debug your Hitachi microprocessor programs. If you
1187 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
1188 called @code{asynctsr} to communicate with the development board
1189 through a PC serial port. You must also use the DOS @code{mode} command
1190 to set up the serial port on the DOS side.
1193 The following sample session illustrates the steps needed to start a
1194 program under @value{GDBN} control on an H8/300. The example uses a
1195 sample H8/300 program called @file{t.x}. The procedure is the same for
1196 the Hitachi SH and the H8/500.
1198 First hook up your development board. In this example, we use a
1199 board attached to serial port @code{COM2}; if you use a different serial
1200 port, substitute its name in the argument of the @code{mode} command.
1201 When you call @code{asynctsr}, the auxiliary comms program used by the
1202 degugger, you give it just the numeric part of the serial port's name;
1203 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
1207 C:\H8300\TEST> asynctsr 2
1208 C:\H8300\TEST> mode com2:9600,n,8,1,p
1210 Resident portion of MODE loaded
1212 COM2: 9600, n, 8, 1, p
1217 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
1218 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
1219 disable it, or even boot without it, to use @code{asynctsr} to control
1220 your development board.
1224 Now that serial communications are set up, and the development board is
1225 connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
1226 the name of your program as the argument. @code{@value{GDBP}} prompts
1227 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
1228 commands to begin your debugging session: @samp{target hms} to specify
1229 cross-debugging to the Hitachi board, and the @code{load} command to
1230 download your program to the board. @code{load} displays the names of
1231 the program's sections, and a @samp{*} for each 2K of data downloaded.
1232 (If you want to refresh @value{GDBN} data on symbols or on the
1233 executable file without downloading, use the @value{GDBN} commands
1234 @code{file} or @code{symbol-file}. These commands, and @code{load}
1235 itself, are described in @ref{Files,,Commands to specify files}.)
1238 (eg-C:\H8300\TEST) @value{GDBP} t.x
1239 GDB is free software and you are welcome to distribute copies
1240 of it under certain conditions; type "show copying" to see
1242 There is absolutely no warranty for GDB; type "show warranty"
1244 GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
1246 Connected to remote H8/300 HMS system.
1248 .text : 0x8000 .. 0xabde ***********
1249 .data : 0xabde .. 0xad30 *
1250 .stack : 0xf000 .. 0xf014 *
1253 At this point, you're ready to run or debug your program. From here on,
1254 you can use all the usual @value{GDBN} commands. The @code{break} command
1255 sets breakpoints; the @code{run} command starts your program;
1256 @code{print} or @code{x} display data; the @code{continue} command
1257 resumes execution after stopping at a breakpoint. You can use the
1258 @code{help} command at any time to find out more about @value{GDBN} commands.
1260 Remember, however, that @emph{operating system} facilities aren't
1261 available on your development board; for example, if your program hangs,
1262 you can't send an interrupt---but you can press the @sc{reset} switch!
1264 Use the @sc{reset} button on the development board
1267 to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
1268 no way to pass an interrupt signal to the development board); and
1271 to return to the @value{GDBN} command prompt after your program finishes
1272 normally. The communications protocol provides no other way for @value{GDBN}
1273 to detect program completion.
1276 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
1277 development board as a ``normal exit'' of your program.
1281 @subsubsection Using the E7000 in-circuit emulator
1283 @kindex target e7000
1284 You can use the E7000 in-circuit emulator to develop code for either the
1285 Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
1286 e7000} command to connect @value{GDBN} to your E7000:
1289 @item target e7000 @var{port} @var{speed}
1290 Use this form if your E7000 is connected to a serial port. The
1291 @var{port} argument identifies what serial port to use (for example,
1292 @samp{com2}). The third argument is the line speed in bits per second
1293 (for example, @samp{9600}).
1295 @item target e7000 @var{hostname}
1296 If your E7000 is installed as a host on a TCP/IP network, you can just
1297 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
1300 @node Hitachi Special
1301 @subsubsection Special @value{GDBN} commands for Hitachi micros
1303 Some @value{GDBN} commands are available only on the H8/300 or the
1304 H8/500 configurations:
1308 @kindex show machine
1309 @item set machine h8300
1310 @itemx set machine h8300h
1311 Condition @value{GDBN} for one of the two variants of the H8/300
1312 architecture with @samp{set machine}. You can use @samp{show machine}
1313 to check which variant is currently in effect.
1315 @kindex set memory @var{mod}
1316 @cindex memory models, H8/500
1317 @item set memory @var{mod}
1319 Specify which H8/500 memory model (@var{mod}) you are using with
1320 @samp{set memory}; check which memory model is in effect with @samp{show
1321 memory}. The accepted values for @var{mod} are @code{small},
1322 @code{big}, @code{medium}, and @code{compact}.
1329 @subsection @value{GDBN} and remote MIPS boards
1332 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
1333 MIPS board attached to a serial line. This is available when
1334 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
1337 Use these @value{GDBN} commands to specify the connection to your target board:
1340 @item target mips @var{port}
1341 @kindex target mips @var{port}
1342 To run a program on the board, start up @code{@value{GDBP}} with the
1343 name of your program as the argument. To connect to the board, use the
1344 command @samp{target mips @var{port}}, where @var{port} is the name of
1345 the serial port connected to the board. If the program has not already
1346 been downloaded to the board, you may use the @code{load} command to
1347 download it. You can then use all the usual @value{GDBN} commands.
1349 For example, this sequence connects to the target board through a serial
1350 port, and loads and runs a program called @var{prog} through the
1354 host$ @value{GDBP} @var{prog}
1355 GDB is free software and @dots{}
1356 (gdb) target mips /dev/ttyb
1357 (gdb) load @var{prog}
1361 @item target mips @var{hostname}:@var{portnumber}
1362 On some @value{GDBN} host configurations, you can specify a TCP
1363 connection (for instance, to a serial line managed by a terminal
1364 concentrator) instead of a serial port, using the syntax
1365 @samp{@var{hostname}:@var{portnumber}}.
1369 @value{GDBN} also supports these special commands for MIPS targets:
1372 @item set processor @var{args}
1373 @itemx show processor
1374 @kindex set processor @var{args}
1375 @kindex show processor
1376 Use the @code{set processor} command to set the type of MIPS
1377 processor when you want to access processor-type-specific registers.
1378 For example, @code{set processor @var{r3041}} tells @value{GDBN}
1379 to use the CPO registers appropriate for the 3041 chip.
1380 Use the @code{show processor} command to see what MIPS processor @value{GDBN}
1381 is using. Use the @code{info reg} command to see what registers
1382 @value{GDBN} is using.
1384 @item set mipsfpu double
1385 @itemx set mipsfpu single
1386 @itemx set mipsfpu none
1389 @kindex show mipsfpu
1390 @cindex MIPS remote floating point
1391 @cindex floating point, MIPS remote
1392 If your target board does not support the MIPS floating point
1393 coprocessor, you should use the command @samp{set mipsfpu none} (if you
1394 need this, you may wish to put the command in your @value{GDBINIT}
1395 file). This tells @value{GDBN} how to find the return value of
1396 functions which return floating point values. It also allows
1397 @value{GDBN} to avoid saving the floating point registers when calling
1398 functions on the board. If you are using a floating point coprocessor
1399 with only single precision floating point support, as on the @sc{r4650}
1400 processor, use the command @samp{set mipsfpu single}. The default
1401 double precision floating point coprocessor may be selected using
1402 @samp{set mipsfpu double}.
1404 In previous versions the only choices were double precision or no
1405 floating point, so @samp{set mipsfpu on} will select double precision
1406 and @samp{set mipsfpu off} will select no floating point.
1408 As usual, you can inquire about the @code{mipsfpu} variable with
1409 @samp{show mipsfpu}.
1411 @item set remotedebug @var{n}
1412 @itemx show remotedebug
1413 @kindex set remotedebug
1414 @kindex show remotedebug
1415 @cindex @code{remotedebug}, MIPS protocol
1416 @cindex MIPS @code{remotedebug} protocol
1417 @c FIXME! For this to be useful, you must know something about the MIPS
1418 @c FIXME...protocol. Where is it described?
1419 You can see some debugging information about communications with the board
1420 by setting the @code{remotedebug} variable. If you set it to @code{1} using
1421 @samp{set remotedebug 1}, every packet is displayed. If you set it
1422 to @code{2}, every character is displayed. You can check the current value
1423 at any time with the command @samp{show remotedebug}.
1425 @item set timeout @var{seconds}
1426 @itemx set retransmit-timeout @var{seconds}
1428 @itemx show retransmit-timeout
1429 @cindex @code{timeout}, MIPS protocol
1430 @cindex @code{retransmit-timeout}, MIPS protocol
1432 @kindex show timeout
1433 @kindex set retransmit-timeout
1434 @kindex show retransmit-timeout
1435 You can control the timeout used while waiting for a packet, in the MIPS
1436 remote protocol, with the @code{set timeout @var{seconds}} command. The
1437 default is 5 seconds. Similarly, you can control the timeout used while
1438 waiting for an acknowledgement of a packet with the @code{set
1439 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
1440 You can inspect both values with @code{show timeout} and @code{show
1441 retransmit-timeout}. (These commands are @emph{only} available when
1442 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
1444 The timeout set by @code{set timeout} does not apply when @value{GDBN}
1445 is waiting for your program to stop. In that case, @value{GDBN} waits
1446 forever because it has no way of knowing how long the program is going
1447 to run before stopping.
1453 @subsection Simulated CPU target
1457 @cindex simulator, Z8000
1458 @cindex Z8000 simulator
1459 @cindex simulator, H8/300 or H8/500
1460 @cindex H8/300 or H8/500 simulator
1461 @cindex simulator, Hitachi SH
1462 @cindex Hitachi SH simulator
1463 @cindex CPU simulator
1464 For some configurations, @value{GDBN} includes a CPU simulator that you
1465 can use instead of a hardware CPU to debug your programs. Currently,
1466 a simulator is available when @value{GDBN} is configured to debug Zilog
1467 Z8000 or Hitachi microprocessor targets.
1472 @cindex simulator, H8/300 or H8/500
1473 @cindex Hitachi H8/300 or H8/500 simulator
1474 @cindex simulator, Hitachi SH
1475 @cindex Hitachi SH simulator
1476 When configured for debugging Hitachi microprocessor targets,
1477 @value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH,
1482 @cindex simulator, Z8000
1483 @cindex Zilog Z8000 simulator
1484 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
1490 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
1491 unsegmented variant of the Z8000 architecture) or the Z8001 (the
1492 segmented variant). The simulator recognizes which architecture is
1493 appropriate by inspecting the object code.
1500 Debug programs on a simulated CPU
1502 (which CPU depends on the @value{GDBN} configuration)
1507 After specifying this target, you can debug programs for the simulated
1508 CPU in the same style as programs for your host computer; use the
1509 @code{file} command to load a new program image, the @code{run} command
1510 to run your program, and so on.
1512 As well as making available all the usual machine registers (see
1513 @code{info reg}), this debugging target provides three additional items
1514 of information as specially named registers:
1518 Counts clock-ticks in the simulator.
1521 Counts instructions run in the simulator.
1524 Execution time in 60ths of a second.
1527 You can refer to these values in @value{GDBN} expressions with the usual
1528 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
1529 conditional breakpoint that suspends only after at least 5000
1530 simulated clock ticks.