2 @c Copyright (c) 1990 1991 1992 1993 Free Software Foundation, Inc.
3 @c This file is part of the source for the GDB manual.
6 @subsection The @value{GDBN} remote serial protocol
8 @cindex remote serial debugging, overview
9 To debug a program running on another machine (the debugging
10 @dfn{target} machine), you must first arrange for all the usual
11 prerequisites for the program to run by itself. For example, for a C
16 A startup routine to set up the C runtime environment; these usually
17 have a name like @file{crt0}. The startup routine may be supplied by
18 your hardware supplier, or you may have to write your own.
21 You probably need a C subroutine library to support your program's
22 subroutine calls, notably managing input and output.
25 A way of getting your program to the other machine---for example, a
26 download program. These are often supplied by the hardware
27 manufacturer, but you may have to write your own from hardware
31 The next step is to arrange for your program to use a serial port to
32 communicate with the machine where @value{GDBN} is running (the @dfn{host}
33 machine). In general terms, the scheme looks like this:
37 @value{GDBN} already understands how to use this protocol; when everything
38 else is set up, you can simply use the @samp{target remote} command
39 (@pxref{Targets,,Specifying a Debugging Target}).
42 you must link with your program a few special-purpose subroutines that
43 implement the @value{GDBN} remote serial protocol. The file containing these
44 subroutines is called a @dfn{debugging stub}.
46 On certain remote targets, you can use an auxiliary program
47 @code{gdbserver} instead of linking a stub into your program.
48 @xref{Server,,Using the @code{gdbserver} program}, for details.
51 The debugging stub is specific to the architecture of the remote
52 machine; for example, use @file{sparc-stub.c} to debug programs on
55 @cindex remote serial stub list
56 These working remote stubs are distributed with @value{GDBN}:
64 For Intel 386 and compatible architectures.
68 @cindex Motorola 680x0
70 For Motorola 680x0 architectures.
76 For Hitachi SH architectures.
81 For @sc{sparc} architectures.
87 For Fujitsu @sc{sparclite} architectures.
91 The @file{README} file in the @value{GDBN} distribution may list other
95 * Stub Contents:: What the stub can do for you
96 * Bootstrapping:: What you must do for the stub
97 * Debug Session:: Putting it all together
98 * Protocol:: Definition of the communication protocol
99 * Server:: Using the `gdbserver' program
100 * NetWare:: Using the `gdbserve.nlm' program
104 @subsubsection What the stub can do for you
106 @cindex remote serial stub
107 The debugging stub for your architecture supplies these three
111 @item set_debug_traps
112 @kindex set_debug_traps
113 @cindex remote serial stub, initialization
114 This routine arranges for @code{handle_exception} to run when your
115 program stops. You must call this subroutine explicitly near the
116 beginning of your program.
118 @item handle_exception
119 @kindex handle_exception
120 @cindex remote serial stub, main routine
121 This is the central workhorse, but your program never calls it
122 explicitly---the setup code arranges for @code{handle_exception} to
123 run when a trap is triggered.
125 @code{handle_exception} takes control when your program stops during
126 execution (for example, on a breakpoint), and mediates communications
127 with @value{GDBN} on the host machine. This is where the communications
128 protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
129 representative on the target machine; it begins by sending summary
130 information on the state of your program, then continues to execute,
131 retrieving and transmitting any information @value{GDBN} needs, until you
132 execute a @value{GDBN} command that makes your program resume; at that point,
133 @code{handle_exception} returns control to your own code on the target
137 @cindex @code{breakpoint} subroutine, remote
138 Use this auxiliary subroutine to make your program contain a
139 breakpoint. Depending on the particular situation, this may be the only
140 way for @value{GDBN} to get control. For instance, if your target
141 machine has some sort of interrupt button, you won't need to call this;
142 pressing the interrupt button transfers control to
143 @code{handle_exception}---in effect, to @value{GDBN}. On some machines,
144 simply receiving characters on the serial port may also trigger a trap;
145 again, in that situation, you don't need to call @code{breakpoint} from
146 your own program---simply running @samp{target remote} from the host
147 @value{GDBN} session gets control.
149 Call @code{breakpoint} if none of these is true, or if you simply want
150 to make certain your program stops at a predetermined point for the
151 start of your debugging session.
155 @subsubsection What you must do for the stub
157 @cindex remote stub, support routines
158 The debugging stubs that come with @value{GDBN} are set up for a particular
159 chip architecture, but they have no information about the rest of your
160 debugging target machine.
162 First of all you need to tell the stub how to communicate with the
166 @item int getDebugChar()
168 Write this subroutine to read a single character from the serial port.
169 It may be identical to @code{getchar} for your target system; a
170 different name is used to allow you to distinguish the two if you wish.
172 @item void putDebugChar(int)
174 Write this subroutine to write a single character to the serial port.
175 It may be identical to @code{putchar} for your target system; a
176 different name is used to allow you to distinguish the two if you wish.
179 @cindex control C, and remote debugging
180 @cindex interrupting remote targets
181 If you want @value{GDBN} to be able to stop your program while it is
182 running, you need to use an interrupt-driven serial driver, and arrange
183 for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
184 character). That is the character which @value{GDBN} uses to tell the
185 remote system to stop.
187 Getting the debugging target to return the proper status to @value{GDBN}
188 probably requires changes to the standard stub; one quick and dirty way
189 is to just execute a breakpoint instruction (the ``dirty'' part is that
190 @value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
192 Other routines you need to supply are:
195 @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
196 @kindex exceptionHandler
197 Write this function to install @var{exception_address} in the exception
198 handling tables. You need to do this because the stub does not have any
199 way of knowing what the exception handling tables on your target system
200 are like (for example, the processor's table might be in @sc{rom},
201 containing entries which point to a table in @sc{ram}).
202 @var{exception_number} is the exception number which should be changed;
203 its meaning is architecture-dependent (for example, different numbers
204 might represent divide by zero, misaligned access, etc). When this
205 exception occurs, control should be transferred directly to
206 @var{exception_address}, and the processor state (stack, registers,
207 and so on) should be just as it is when a processor exception occurs. So if
208 you want to use a jump instruction to reach @var{exception_address}, it
209 should be a simple jump, not a jump to subroutine.
211 For the 386, @var{exception_address} should be installed as an interrupt
212 gate so that interrupts are masked while the handler runs. The gate
213 should be at privilege level 0 (the most privileged level). The
214 @sc{sparc} and 68k stubs are able to mask interrupts themselves without
215 help from @code{exceptionHandler}.
217 @item void flush_i_cache()
218 @kindex flush_i_cache
219 (sparc and sparclite only) Write this subroutine to flush the
220 instruction cache, if any, on your target machine. If there is no
221 instruction cache, this subroutine may be a no-op.
223 On target machines that have instruction caches, @value{GDBN} requires this
224 function to make certain that the state of your program is stable.
228 You must also make sure this library routine is available:
231 @item void *memset(void *, int, int)
233 This is the standard library function @code{memset} that sets an area of
234 memory to a known value. If you have one of the free versions of
235 @code{libc.a}, @code{memset} can be found there; otherwise, you must
236 either obtain it from your hardware manufacturer, or write your own.
239 If you do not use the GNU C compiler, you may need other standard
240 library subroutines as well; this varies from one stub to another,
241 but in general the stubs are likely to use any of the common library
242 subroutines which @code{gcc} generates as inline code.
246 @subsubsection Putting it all together
248 @cindex remote serial debugging summary
249 In summary, when your program is ready to debug, you must follow these
254 Make sure you have the supporting low-level routines
255 (@pxref{Bootstrapping,,What you must do for the stub}):
257 @code{getDebugChar}, @code{putDebugChar},
258 @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
262 Insert these lines near the top of your program:
270 For the 680x0 stub only, you need to provide a variable called
271 @code{exceptionHook}. Normally you just use:
274 void (*exceptionHook)() = 0;
277 but if before calling @code{set_debug_traps}, you set it to point to a
278 function in your program, that function is called when
279 @code{@value{GDBN}} continues after stopping on a trap (for example, bus
280 error). The function indicated by @code{exceptionHook} is called with
281 one parameter: an @code{int} which is the exception number.
284 Compile and link together: your program, the @value{GDBN} debugging stub for
285 your target architecture, and the supporting subroutines.
288 Make sure you have a serial connection between your target machine and
289 the @value{GDBN} host, and identify the serial port on the host.
292 @c The "remote" target now provides a `load' command, so we should
293 @c document that. FIXME.
294 Download your program to your target machine (or get it there by
295 whatever means the manufacturer provides), and start it.
298 To start remote debugging, run @value{GDBN} on the host machine, and specify
299 as an executable file the program that is running in the remote machine.
300 This tells @value{GDBN} how to find your program's symbols and the contents
303 @cindex serial line, @code{target remote}
304 Then establish communication using the @code{target remote} command.
305 Its argument specifies how to communicate with the target
306 machine---either via a devicename attached to a direct serial line, or a
307 TCP port (usually to a terminal server which in turn has a serial line
308 to the target). For example, to use a serial line connected to the
309 device named @file{/dev/ttyb}:
312 target remote /dev/ttyb
315 @cindex TCP port, @code{target remote}
316 To use a TCP connection, use an argument of the form
317 @code{@var{host}:port}. For example, to connect to port 2828 on a
318 terminal server named @code{manyfarms}:
321 target remote manyfarms:2828
325 Now you can use all the usual commands to examine and change data and to
326 step and continue the remote program.
328 To resume the remote program and stop debugging it, use the @code{detach}
331 @cindex interrupting remote programs
332 @cindex remote programs, interrupting
333 Whenever @value{GDBN} is waiting for the remote program, if you type the
334 interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
335 program. This may or may not succeed, depending in part on the hardware
336 and the serial drivers the remote system uses. If you type the
337 interrupt character once again, @value{GDBN} displays this prompt:
340 Interrupted while waiting for the program.
341 Give up (and stop debugging it)? (y or n)
344 If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
345 (If you decide you want to try again later, you can use @samp{target
346 remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
347 goes back to waiting.
350 @subsubsection Communication protocol
352 @cindex debugging stub, example
353 @cindex remote stub, example
354 @cindex stub example, remote debugging
355 The stub files provided with @value{GDBN} implement the target side of the
356 communication protocol, and the @value{GDBN} side is implemented in the
357 @value{GDBN} source file @file{remote.c}. Normally, you can simply allow
358 these subroutines to communicate, and ignore the details. (If you're
359 implementing your own stub file, you can still ignore the details: start
360 with one of the existing stub files. @file{sparc-stub.c} is the best
361 organized, and therefore the easiest to read.)
363 However, there may be occasions when you need to know something about
364 the protocol---for example, if there is only one serial port to your
365 target machine, you might want your program to do something special if
366 it recognizes a packet meant for @value{GDBN}.
368 In the examples below, @samp{<-} and @samp{->} are used to indicate
369 transmitted and received data respectfully.
371 @cindex protocol, @value{GDBN} remote serial
372 @cindex serial protocol, @value{GDBN} remote
373 @cindex remote serial protocol
374 All @value{GDBN} commands and responses (other than acknowledgments)
375 are sent as a @var{packet}. A @var{packet} is introduced with the
376 character @samp{$}, this is followed by an optional two-digit
377 @var{sequence-id} and the character @samp{:}, the actual
378 @var{packet-data}, and the terminating character @samp{#} followed by a
379 two-digit @var{checksum}:
382 @code{$}@var{packet-data}@code{#}@var{checksum}
385 or, with the optional @var{sequence-id}:
387 @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
390 @cindex checksum, for @value{GDBN} remote
392 The two-digit @var{checksum} is computed as the modulo 256 sum of all
393 characters between the leading @samp{$} and the trailing @samp{#} (that
394 consisting of both the optional @var{sequence-id}@code{:} and the actual
397 @cindex sequence-id, for @value{GDBN} remote
399 The two-digit @var{sequence-id}, when present, is returned with the
400 acknowledgment. Beyond that its meaning is poorly defined.
401 @value{GDBN} is not known to output @var{sequence-id}s.
403 When either the host or the target machine receives a packet, the first
404 response expected is an acknowledgment: either @samp{+} (to indicate
405 the package was received correctly) or @samp{-} (to request
409 <- @code{$}@var{packet-data}@code{#}@var{checksum}
413 If the received packet included a @var{sequence-id} than that is
414 appended to a positive acknowledgment:
417 <- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
418 -> @code{+}@var{sequence-id}
421 The host (@value{GDBN}) sends @var{command}s, and the target (the
422 debugging stub incorporated in your program) sends a @var{response}. In
423 the case of step and continue @var{command}s, the response is only sent
424 when the operation has completed (the target has again stopped).
426 @var{packet-data} consists of a sequence of characters with the
427 exception of @samp{#} and @samp{$} (see @samp{X} packet for an
428 exception). @samp{:} can not appear as the third character in a packet.
429 Fields within the packet should be separated using @samp{,} and @samp{;}
430 (unfortunately some packets chose to use @samp{:}). Except where
431 otherwise noted all numbers are represented in HEX with leading zeros
434 Response @var{data} can be run-length encoded to save space. A @samp{*}
435 means that the next character is an ASCII encoding giving a repeat count
436 which stands for that many repetitions of the character preceding the
437 @samp{*}. The encoding is @code{n+29}, yielding a printable character
438 where @code{n >=3} (which is where rle starts to win). Don't use an
446 means the same as "0000".
448 The error response, returned for some packets includes a two character
449 error number. That number is not well defined.
451 For any @var{command} not supported by the stub, an empty response
452 (@samp{$#00}) should be returned. That way it is possible to extend the
453 protocol. A newer @value{GDBN} can tell if a packet is supported based
456 Below is a complete list of all currently defined @var{command}s and
457 their corresponding response @var{data}:
459 @multitable @columnfractions .30 .30 .40
464 @item extended ops @emph{(optional)}
467 Use the extended remote protocol. Sticky -- only needs to be set once.
468 The extended remote protocol support the @samp{R} packet.
472 Stubs that support the extended remote protocol return @samp{} which,
473 unfortunately, is identical to the response returned by stubs that do not
474 support protocol extensions.
479 Reply the current reason for stopping. This is the same reply as is
480 generated for step or cont : @code{S}@var{AA} where @var{AA} is the
485 @tab Reserved for future use
487 @item set program arguments @strong{(reserved)} @emph{(optional)}
488 @tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
490 Initialized @samp{argv[]} array passed into program. @var{arglen}
491 specifies the number of bytes in the hex encoded byte stream @var{arg}.
495 @tab reply @code{E}@var{NN}
497 @item set baud @strong{(deprecated)}
498 @tab @code{b}@var{baud}
500 Change the serial line speed to @var{baud}. JTC: @emph{When does the
501 transport layer state change? When it's received, or after the ACK is
502 transmitted. In either case, there are problems if the command or the
503 acknowledgment packet is dropped.} Stan: @emph{If people really wanted
504 to add something like this, and get it working for the first time, they
505 ought to modify ser-unix.c to send some kind of out-of-band message to a
506 specially-setup stub and have the switch happen "in between" packets, so
507 that from remote protocol's point of view, nothing actually
510 @item set breakpoint @strong{(deprecated)}
511 @tab @code{B}@var{addr},@var{mode}
513 Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
514 breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
518 @tab @code{c}@var{addr}
520 @var{addr} is address to resume. If @var{addr} is omitted, resume at
526 @item continue with signal @emph{(optional)}
527 @tab @code{C}@var{sig}@code{;}@var{addr}
529 Continue with signal @var{sig} (hex signal number). If
530 @code{;}@var{addr} is omitted, resume at same address.
535 @item toggle debug @emph{(optional)}
538 toggle debug flag (see 386 & 68k stubs)
540 @item detach @emph{(optional)}
546 @tab Reserved for future use
550 @tab Reserved for future use
554 @tab Reserved for future use
558 @tab Reserved for future use
562 @tab Read general registers.
564 @tab reply @var{XX...}
566 Each byte of register data is described by two hex digits. The bytes
567 with the register are transmitted in target byte order. The size of
568 each register and their position within the @samp{g} @var{packet} is
569 determined by the @var{REGISTER_RAW_SIZE} and @var{REGISTER_NAME}
572 @tab @code{E}@var{NN}
576 @tab @code{G}@var{XX...}
578 See @samp{g} for a description of the @var{XX...} data.
583 @tab reply @code{E}@var{NN}
588 @tab Reserved for future use
590 @item set thread @emph{(optional)}
591 @tab @code{H}@var{c}@var{t...}
593 Set thread for subsequent operations. @var{c} = @samp{c} for thread
594 used in step and continue; @var{t...} can be -1 for all threads.
595 @var{c} = @samp{g} for thread used in other operations. If zero, pick a
601 @tab reply @code{E}@var{NN}
604 @item cycle step @strong{(draft)} @emph{(optional)}
605 @tab @code{i}@var{addr}@code{,}@var{nnn}
607 Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
608 present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
609 step starting at that address.
611 @item signal then cycle step @strong{(reserved)} @emph{(optional)}
614 See @samp{i} and @samp{S} for likely syntax and semantics.
618 @tab Reserved for future use
622 @tab Reserved for future use
624 @item kill request @emph{(optional)}
630 @tab Reserved for future use
634 @tab Reserved for future use
637 @tab @code{m}@var{addr}@code{,}@var{length}
639 Read @var{length} bytes of memory starting at address @var{addr}.
641 @tab reply @var{XX...}
643 @var{XX...} is mem contents. Can be fewer bytes than requested if able to
644 read only part of the data.
646 @tab reply @code{E}@var{NN}
647 @tab @var{NN} is errno
650 @tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
652 Write @var{length} bytes of memory starting at address @var{addr}.
653 @var{XX...} is the data.
658 @tab reply @code{E}@var{NN}
660 for an error (this includes the case where only part of the data was
665 @tab Reserved for future use
669 @tab Reserved for future use
673 @tab Reserved for future use
677 @tab Reserved for future use
679 @item read reg @strong{(reserved)}
680 @tab @code{p}@var{n...}
684 @tab return @var{r....}
685 @tab The hex encoded value of the register in target byte order.
687 @item write reg @emph{(optional)}
688 @tab @code{P}@var{n...}@code{=}@var{r...}
690 Write register @var{n...} with value @var{r...}, which contains two hex
691 digits for each byte in the register (target byte order).
696 @tab reply @code{E}@var{NN}
699 @item general query @emph{(optional)}
700 @tab @code{q}@var{query}
702 Request info about @var{query}. In general @value{GDBN} @var{query}'s
703 have a leading upper case letter. Custom vendor queries should use a
704 leading lower case letter and a company prefix, ex: @samp{qfsf.var}.
705 @var{query} may optionally be followed by a @samp{,} or @samp{;}
706 separated list. Stubs should ensure that they fully match any
709 @tab reply @code{XX...}
710 @tab Hex encoded data from query. The reply can not be empty.
712 @tab reply @code{E}@var{NN}
716 @tab Indicating an unrecognized @var{query}.
719 @tab @code{q}@code{C}
720 @tab Return the current thread id.
722 @tab reply @code{QC}@var{pid}
724 Where @var{pid} is a HEX encoded 16 bit process id.
727 @tab Any other reply implies the old pid.
729 @item compute CRC of memory block
730 @tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
733 @tab reply @code{E}@var{NN}
734 @tab An error (such as memory fault)
736 @tab reply @code{C}@var{CRC32}
737 @tab A 32 bit cyclic redundancy check of the specified memory region.
739 @item query @var{LIST} or @var{threadLIST}
740 @tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
742 Obtain thread information from RTOS. @var{startflag} is one hex digit;
743 @var{threadcount} is two hex digits; and @var{nextthread} is 16 hex
748 See @code{remote.c:parse_threadlist_response()}.
750 @item query sect offs
751 @tab @code{q}@code{Offsets}
752 @tab Get section offsets.
754 @tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
756 @item thread info request
757 @tab @code{q}@code{P}@var{mode}@var{threadid}
759 Returns information on @var{threadid}. Where: @var{mode} is a hex
760 encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
764 See @code{remote.c:remote_unpack_thread_info_response()}.
766 @item remote command @strong{(reserved)}
767 @tab @code{q}@code{Rcmd,}@var{COMMAND}
769 @var{COMMAND} (hex encoded) is passed to the local interpreter for
770 execution. @emph{Implementors should note that providing access to a
771 stubs's interpreter may have security implications}.
773 @tab reply @var{OUTPUT}
775 The @var{OUTPUT} (hex encoded). Must be non-empty.
779 When @samp{q}@samp{Rcmd} is not recognized.
781 @item general set @emph{(optional)}
782 @tab @code{Q}@var{var}@code{=}@var{val}
784 Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
787 @item reset @emph{(optional)}
789 @tab reset -- see sparc stub.
791 @item remote restart @emph{(optional)}
792 @tab @code{R}@var{XX}
794 Restart the remote server. @var{XX} while needed has no clear
797 @item step @emph{(optional)}
798 @tab @code{s}@var{addr}
800 @var{addr} is address to resume. If @var{addr} is omitted, resume at
806 @item step with signal @emph{(optional)}
807 @tab @code{S}@var{sig}@code{;}@var{addr}
809 Like @samp{C} but step not continue.
814 @item search @emph{(optional)}
815 @tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
817 Search backwards starting at address @var{addr} for a match with pattern
818 @var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
819 bytes. @var{addr} must be at least 3 digits.
821 @item thread alive @emph{(optional)}
822 @tab @code{T}@var{XX}
823 @tab Find out if the thread XX is alive.
826 @tab thread is still alive
828 @tab reply @code{E}@var{NN}
833 @tab Reserved for future use
837 @tab Reserved for future use
841 @tab Reserved for future use
845 @tab Reserved for future use
849 @tab Reserved for future use
853 @tab Reserved for future use
857 @tab Reserved for future use
859 @item write mem (binary) @emph{(optional)}
860 @tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
862 @var{addr} is address, @var{length} is number of bytes, @var{XX...} is
868 @tab reply @code{E}@var{NN}
873 @tab Reserved for future use
877 @tab Reserved for future use
879 @item remove break or watchpoint @strong{(draft)} @emph{(optional)}
880 @tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
884 @item insert break or watchpoint @strong{(draft)} @emph{(optional)}
885 @tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
887 @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
888 breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
889 @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
890 bytes. For a software breakpoint, @var{length} specifies the size of
891 the instruction to be patched. For hardware breakpoints and watchpoints
892 @var{length} specifies the memory region to be monitored.
894 @tab reply @code{E}@var{NN}
901 @tab If not supported.
905 @tab Reserved for future use
909 In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets,
910 there is no immediate response. The reply, described below, comes when
913 @multitable @columnfractions .4 .6
915 @item @code{S}@var{AA}
916 @tab @var{AA} is the signal number
918 @item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
920 @var{AA} = two hex digit signal number; @var{n...} = register number
921 (hex), @var{r...} = target byte ordered register contents, size defined
922 by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
923 thread process ID, this is a hex integer; @var{n...} = other string not
924 starting with valid hex digit. @value{GDBN} should ignore this
925 @var{n...}, @var{r...} pair and go on to the next. This way we can
928 @item @code{W}@var{AA}
930 The process exited, and @var{AA} is the exit status. This is only
931 applicable for certains sorts of targets.
933 @item @code{X}@var{AA}
935 The process terminated with signal @var{AA}.
937 @item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)}
939 @var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
940 @var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss
941 section. @emph{Note: only used by Cisco Systems targets. The difference
942 between this reply and the "qOffsets" query is that the 'N' packet may
943 arrive spontaneously whereas the 'qOffsets' is a query initiated by the
946 @item @code{O}@var{XX...}
948 @var{XX...} is hex encoding of ASCII data. This can happen at any time
949 while the program is running and the debugger should continue to wait
954 Example sequence of a target being re-started. Notice how the restart
955 does not get any direct output:
960 @emph{target restarts}
963 -> @code{T001:1234123412341234}
967 Example sequence of a target being stepped by a single instruction:
975 -> @code{T001:1234123412341234}
983 @kindex set remotedebug
984 @kindex show remotedebug
985 @cindex packets, reporting on stdout
986 @cindex serial connections, debugging
987 If you have trouble with the serial connection, you can use the command
988 @code{set remotedebug}. This makes @value{GDBN} report on all packets sent
989 back and forth across the serial line to the remote machine. The
990 packet-debugging information is printed on the @value{GDBN} standard output
991 stream. @code{set remotedebug off} turns it off, and @code{show
992 remotedebug} shows you its current state.
995 @subsubsection Using the @code{gdbserver} program
998 @cindex remote connection without stubs
999 @code{gdbserver} is a control program for Unix-like systems, which
1000 allows you to connect your program with a remote @value{GDBN} via
1001 @code{target remote}---but without linking in the usual debugging stub.
1003 @code{gdbserver} is not a complete replacement for the debugging stubs,
1004 because it requires essentially the same operating-system facilities
1005 that @value{GDBN} itself does. In fact, a system that can run
1006 @code{gdbserver} to connect to a remote @value{GDBN} could also run
1007 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
1008 because it is a much smaller program than @value{GDBN} itself. It is
1009 also easier to port than all of @value{GDBN}, so you may be able to get
1010 started more quickly on a new system by using @code{gdbserver}.
1011 Finally, if you develop code for real-time systems, you may find that
1012 the tradeoffs involved in real-time operation make it more convenient to
1013 do as much development work as possible on another system, for example
1014 by cross-compiling. You can use @code{gdbserver} to make a similar
1015 choice for debugging.
1017 @value{GDBN} and @code{gdbserver} communicate via either a serial line
1018 or a TCP connection, using the standard @value{GDBN} remote serial
1022 @item On the target machine,
1023 you need to have a copy of the program you want to debug.
1024 @code{gdbserver} does not need your program's symbol table, so you can
1025 strip the program if necessary to save space. @value{GDBN} on the host
1026 system does all the symbol handling.
1028 To use the server, you must tell it how to communicate with @value{GDBN};
1029 the name of your program; and the arguments for your program. The
1033 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
1036 @var{comm} is either a device name (to use a serial line) or a TCP
1037 hostname and portnumber. For example, to debug Emacs with the argument
1038 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
1042 target> gdbserver /dev/com1 emacs foo.txt
1045 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
1048 To use a TCP connection instead of a serial line:
1051 target> gdbserver host:2345 emacs foo.txt
1054 The only difference from the previous example is the first argument,
1055 specifying that you are communicating with the host @value{GDBN} via
1056 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
1057 expect a TCP connection from machine @samp{host} to local TCP port 2345.
1058 (Currently, the @samp{host} part is ignored.) You can choose any number
1059 you want for the port number as long as it does not conflict with any
1060 TCP ports already in use on the target system (for example, @code{23} is
1061 reserved for @code{telnet}).@footnote{If you choose a port number that
1062 conflicts with another service, @code{gdbserver} prints an error message
1063 and exits.} You must use the same port number with the host @value{GDBN}
1064 @code{target remote} command.
1066 @item On the @value{GDBN} host machine,
1067 you need an unstripped copy of your program, since @value{GDBN} needs
1068 symbols and debugging information. Start up @value{GDBN} as usual,
1069 using the name of the local copy of your program as the first argument.
1070 (You may also need the @w{@samp{--baud}} option if the serial line is
1071 running at anything other than 9600 bps.) After that, use @code{target
1072 remote} to establish communications with @code{gdbserver}. Its argument
1073 is either a device name (usually a serial device, like
1074 @file{/dev/ttyb}), or a TCP port descriptor in the form
1075 @code{@var{host}:@var{PORT}}. For example:
1078 (@value{GDBP}) target remote /dev/ttyb
1082 communicates with the server via serial line @file{/dev/ttyb}, and
1085 (@value{GDBP}) target remote the-target:2345
1089 communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
1090 For TCP connections, you must start up @code{gdbserver} prior to using
1091 the @code{target remote} command. Otherwise you may get an error whose
1092 text depends on the host system, but which usually looks something like
1093 @samp{Connection refused}.
1097 @subsubsection Using the @code{gdbserve.nlm} program
1099 @kindex gdbserve.nlm
1100 @code{gdbserve.nlm} is a control program for NetWare systems, which
1101 allows you to connect your program with a remote @value{GDBN} via
1102 @code{target remote}.
1104 @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
1105 using the standard @value{GDBN} remote serial protocol.
1108 @item On the target machine,
1109 you need to have a copy of the program you want to debug.
1110 @code{gdbserve.nlm} does not need your program's symbol table, so you
1111 can strip the program if necessary to save space. @value{GDBN} on the
1112 host system does all the symbol handling.
1114 To use the server, you must tell it how to communicate with
1115 @value{GDBN}; the name of your program; and the arguments for your
1116 program. The syntax is:
1119 load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
1120 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
1123 @var{board} and @var{port} specify the serial line; @var{baud} specifies
1124 the baud rate used by the connection. @var{port} and @var{node} default
1125 to 0, @var{baud} defaults to 9600 bps.
1127 For example, to debug Emacs with the argument @samp{foo.txt}and
1128 communicate with @value{GDBN} over serial port number 2 or board 1
1129 using a 19200 bps connection:
1132 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
1135 @item On the @value{GDBN} host machine,
1136 you need an unstripped copy of your program, since @value{GDBN} needs
1137 symbols and debugging information. Start up @value{GDBN} as usual,
1138 using the name of the local copy of your program as the first argument.
1139 (You may also need the @w{@samp{--baud}} option if the serial line is
1140 running at anything other than 9600 bps. After that, use @code{target
1141 remote} to establish communications with @code{gdbserve.nlm}. Its
1142 argument is a device name (usually a serial device, like
1143 @file{/dev/ttyb}). For example:
1146 (@value{GDBP}) target remote /dev/ttyb
1150 communications with the server via serial line @file{/dev/ttyb}.
1153 @node i960-Nindy Remote
1154 @subsection @value{GDBN} with a remote i960 (Nindy)
1158 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
1159 @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
1160 tell @value{GDBN} how to connect to the 960 in several ways:
1164 Through command line options specifying serial port, version of the
1165 Nindy protocol, and communications speed;
1168 By responding to a prompt on startup;
1171 By using the @code{target} command at any point during your @value{GDBN}
1172 session. @xref{Target Commands, ,Commands for managing targets}.
1177 * Nindy Startup:: Startup with Nindy
1178 * Nindy Options:: Options for Nindy
1179 * Nindy Reset:: Nindy reset command
1183 @subsubsection Startup with Nindy
1185 If you simply start @code{@value{GDBP}} without using any command-line
1186 options, you are prompted for what serial port to use, @emph{before} you
1187 reach the ordinary @value{GDBN} prompt:
1190 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
1194 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
1195 identifies the serial port you want to use. You can, if you choose,
1196 simply start up with no Nindy connection by responding to the prompt
1197 with an empty line. If you do this and later wish to attach to Nindy,
1198 use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
1201 @subsubsection Options for Nindy
1203 These are the startup options for beginning your @value{GDBN} session with a
1204 Nindy-960 board attached:
1208 Specify the serial port name of a serial interface to be used to connect
1209 to the target system. This option is only available when @value{GDBN} is
1210 configured for the Intel 960 target architecture. You may specify
1211 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
1212 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
1213 suffix for a specific @code{tty} (e.g. @samp{-r a}).
1216 (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
1217 the ``old'' Nindy monitor protocol to connect to the target system.
1218 This option is only available when @value{GDBN} is configured for the Intel 960
1219 target architecture.
1222 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
1223 connect to a target system that expects the newer protocol, the connection
1224 fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
1225 attempts to reconnect at several different line speeds. You can abort
1226 this process with an interrupt.
1230 Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
1231 system, in an attempt to reset it, before connecting to a Nindy target.
1234 @emph{Warning:} Many target systems do not have the hardware that this
1235 requires; it only works with a few boards.
1239 The standard @samp{-b} option controls the line speed used on the serial
1244 @subsubsection Nindy reset command
1249 For a Nindy target, this command sends a ``break'' to the remote target
1250 system; this is only useful if the target has been equipped with a
1251 circuit to perform a hard reset (or some other interesting action) when
1252 a break is detected.
1257 @subsection The UDI protocol for AMD29K
1260 @cindex AMD29K via UDI
1261 @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
1262 protocol for debugging the a29k processor family. To use this
1263 configuration with AMD targets running the MiniMON monitor, you need the
1264 program @code{MONTIP}, available from AMD at no charge. You can also
1265 use @value{GDBN} with the UDI-conformant a29k simulator program
1266 @code{ISSTIP}, also available from AMD.
1269 @item target udi @var{keyword}
1271 Select the UDI interface to a remote a29k board or simulator, where
1272 @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
1273 This file contains keyword entries which specify parameters used to
1274 connect to a29k targets. If the @file{udi_soc} file is not in your
1275 working directory, you must set the environment variable @samp{UDICONF}
1280 @subsection The EBMON protocol for AMD29K
1283 @cindex running 29K programs
1285 AMD distributes a 29K development board meant to fit in a PC, together
1286 with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
1287 term, this development system is called the ``EB29K''. To use
1288 @value{GDBN} from a Unix system to run programs on the EB29K board, you
1289 must first connect a serial cable between the PC (which hosts the EB29K
1290 board) and a serial port on the Unix system. In the following, we
1291 assume you've hooked the cable between the PC's @file{COM1} port and
1292 @file{/dev/ttya} on the Unix system.
1295 * Comms (EB29K):: Communications setup
1296 * gdb-EB29K:: EB29K cross-debugging
1297 * Remote Log:: Remote log
1301 @subsubsection Communications setup
1303 The next step is to set up the PC's port, by doing something like this
1307 C:\> MODE com1:9600,n,8,1,none
1311 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
1312 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
1313 you must match the communications parameters when establishing the Unix
1314 end of the connection as well.
1315 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
1316 @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
1318 To give control of the PC to the Unix side of the serial line, type
1319 the following at the DOS console:
1326 (Later, if you wish to return control to the DOS console, you can use
1327 the command @code{CTTY con}---but you must send it over the device that
1328 had control, in our example over the @file{COM1} serial line).
1330 From the Unix host, use a communications program such as @code{tip} or
1331 @code{cu} to communicate with the PC; for example,
1334 cu -s 9600 -l /dev/ttya
1338 The @code{cu} options shown specify, respectively, the linespeed and the
1339 serial port to use. If you use @code{tip} instead, your command line
1340 may look something like the following:
1347 Your system may require a different name where we show
1348 @file{/dev/ttya} as the argument to @code{tip}. The communications
1349 parameters, including which port to use, are associated with the
1350 @code{tip} argument in the ``remote'' descriptions file---normally the
1351 system table @file{/etc/remote}.
1352 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
1353 @c the DOS side's comms setup? cu can support -o (odd
1354 @c parity), -e (even parity)---apparently no settings for no parity or
1355 @c for character size. Taken from stty maybe...? John points out tip
1356 @c can set these as internal variables, eg ~s parity=none; man stty
1357 @c suggests that it *might* work to stty these options with stdin or
1358 @c stdout redirected... ---doc@cygnus.com, 25feb91
1361 Using the @code{tip} or @code{cu} connection, change the DOS working
1362 directory to the directory containing a copy of your 29K program, then
1363 start the PC program @code{EBMON} (an EB29K control program supplied
1364 with your board by AMD). You should see an initial display from
1365 @code{EBMON} similar to the one that follows, ending with the
1366 @code{EBMON} prompt @samp{#}---
1371 G:\> CD \usr\joe\work29k
1373 G:\USR\JOE\WORK29K> EBMON
1374 Am29000 PC Coprocessor Board Monitor, version 3.0-18
1375 Copyright 1990 Advanced Micro Devices, Inc.
1376 Written by Gibbons and Associates, Inc.
1378 Enter '?' or 'H' for help
1380 PC Coprocessor Type = EB29K
1382 Memory Base = 0xd0000
1384 Data Memory Size = 2048KB
1385 Available I-RAM Range = 0x8000 to 0x1fffff
1386 Available D-RAM Range = 0x80002000 to 0x801fffff
1389 Register Stack Size = 0x800
1390 Memory Stack Size = 0x1800
1393 Am29027 Available = No
1394 Byte Write Available = Yes
1399 Then exit the @code{cu} or @code{tip} program (done in the example by
1400 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
1401 running, ready for @value{GDBN} to take over.
1403 For this example, we've assumed what is probably the most convenient
1404 way to make sure the same 29K program is on both the PC and the Unix
1405 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
1406 PC as a file system on the Unix host. If you do not have PC/NFS or
1407 something similar connecting the two systems, you must arrange some
1408 other way---perhaps floppy-disk transfer---of getting the 29K program
1409 from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
1413 @subsubsection EB29K cross-debugging
1415 Finally, @code{cd} to the directory containing an image of your 29K
1416 program on the Unix system, and start @value{GDBN}---specifying as argument the
1417 name of your 29K program:
1425 Now you can use the @code{target} command:
1428 target amd-eb /dev/ttya 9600 MYFOO
1429 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
1430 @c emphasize that this is the name as seen by DOS (since I think DOS is
1431 @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
1435 In this example, we've assumed your program is in a file called
1436 @file{myfoo}. Note that the filename given as the last argument to
1437 @code{target amd-eb} should be the name of the program as it appears to DOS.
1438 In our example this is simply @code{MYFOO}, but in general it can include
1439 a DOS path, and depending on your transfer mechanism may not resemble
1440 the name on the Unix side.
1442 At this point, you can set any breakpoints you wish; when you are ready
1443 to see your program run on the 29K board, use the @value{GDBN} command
1446 To stop debugging the remote program, use the @value{GDBN} @code{detach}
1449 To return control of the PC to its console, use @code{tip} or @code{cu}
1450 once again, after your @value{GDBN} session has concluded, to attach to
1451 @code{EBMON}. You can then type the command @code{q} to shut down
1452 @code{EBMON}, returning control to the DOS command-line interpreter.
1453 Type @code{CTTY con} to return command input to the main DOS console,
1454 and type @kbd{~.} to leave @code{tip} or @code{cu}.
1457 @subsubsection Remote log
1459 @cindex log file for EB29K
1461 The @code{target amd-eb} command creates a file @file{eb.log} in the
1462 current working directory, to help debug problems with the connection.
1463 @file{eb.log} records all the output from @code{EBMON}, including echoes
1464 of the commands sent to it. Running @samp{tail -f} on this file in
1465 another window often helps to understand trouble with @code{EBMON}, or
1466 unexpected events on the PC side of the connection.
1469 @subsection @value{GDBN} with a Tandem ST2000
1471 To connect your ST2000 to the host system, see the manufacturer's
1472 manual. Once the ST2000 is physically attached, you can run:
1475 target st2000 @var{dev} @var{speed}
1479 to establish it as your debugging environment. @var{dev} is normally
1480 the name of a serial device, such as @file{/dev/ttya}, connected to the
1481 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
1482 connection (for example, to a serial line attached via a terminal
1483 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
1485 The @code{load} and @code{attach} commands are @emph{not} defined for
1486 this target; you must load your program into the ST2000 as you normally
1487 would for standalone operation. @value{GDBN} reads debugging information
1488 (such as symbols) from a separate, debugging version of the program
1489 available on your host computer.
1490 @c FIXME!! This is terribly vague; what little content is here is
1491 @c basically hearsay.
1493 @cindex ST2000 auxiliary commands
1494 These auxiliary @value{GDBN} commands are available to help you with the ST2000
1498 @item st2000 @var{command}
1499 @kindex st2000 @var{cmd}
1500 @cindex STDBUG commands (ST2000)
1501 @cindex commands to STDBUG (ST2000)
1502 Send a @var{command} to the STDBUG monitor. See the manufacturer's
1503 manual for available commands.
1506 @cindex connect (to STDBUG)
1507 Connect the controlling terminal to the STDBUG command monitor. When
1508 you are done interacting with STDBUG, typing either of two character
1509 sequences gets you back to the @value{GDBN} command prompt:
1510 @kbd{@key{RET}~.} (Return, followed by tilde and period) or
1511 @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
1514 @node VxWorks Remote
1515 @subsection @value{GDBN} and VxWorks
1519 @value{GDBN} enables developers to spawn and debug tasks running on networked
1520 VxWorks targets from a Unix host. Already-running tasks spawned from
1521 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
1522 both the Unix host and on the VxWorks target. The program
1523 @code{gdb} is installed and executed on the Unix host. (It may be
1524 installed with the name @code{vxgdb}, to distinguish it from a
1525 @value{GDBN} for debugging programs on the host itself.)
1528 @item VxWorks-timeout @var{args}
1529 @kindex vxworks-timeout
1530 All VxWorks-based targets now support the option @code{vxworks-timeout}.
1531 This option is set by the user, and @var{args} represents the number of
1532 seconds @value{GDBN} waits for responses to rpc's. You might use this if
1533 your VxWorks target is a slow software simulator or is on the far side
1534 of a thin network line.
1537 The following information on connecting to VxWorks was current when
1538 this manual was produced; newer releases of VxWorks may use revised
1542 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
1543 to include the remote debugging interface routines in the VxWorks
1544 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
1545 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
1546 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
1547 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1548 information on configuring and remaking VxWorks, see the manufacturer's
1550 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
1552 Once you have included @file{rdb.a} in your VxWorks system image and set
1553 your Unix execution search path to find @value{GDBN}, you are ready to
1554 run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb},
1555 depending on your installation).
1557 @value{GDBN} comes up showing the prompt:
1564 * VxWorks Connection:: Connecting to VxWorks
1565 * VxWorks Download:: VxWorks download
1566 * VxWorks Attach:: Running tasks
1569 @node VxWorks Connection
1570 @subsubsection Connecting to VxWorks
1572 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
1573 network. To connect to a target whose host name is ``@code{tt}'', type:
1576 (vxgdb) target vxworks tt
1580 @value{GDBN} displays messages like these:
1583 Attaching remote machine across net...
1588 @value{GDBN} then attempts to read the symbol tables of any object modules
1589 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
1590 these files by searching the directories listed in the command search
1591 path (@pxref{Environment, ,Your program's environment}); if it fails
1592 to find an object file, it displays a message such as:
1595 prog.o: No such file or directory.
1598 When this happens, add the appropriate directory to the search path with
1599 the @value{GDBN} command @code{path}, and execute the @code{target}
1602 @node VxWorks Download
1603 @subsubsection VxWorks download
1605 @cindex download to VxWorks
1606 If you have connected to the VxWorks target and you want to debug an
1607 object that has not yet been loaded, you can use the @value{GDBN}
1608 @code{load} command to download a file from Unix to VxWorks
1609 incrementally. The object file given as an argument to the @code{load}
1610 command is actually opened twice: first by the VxWorks target in order
1611 to download the code, then by @value{GDBN} in order to read the symbol
1612 table. This can lead to problems if the current working directories on
1613 the two systems differ. If both systems have NFS mounted the same
1614 filesystems, you can avoid these problems by using absolute paths.
1615 Otherwise, it is simplest to set the working directory on both systems
1616 to the directory in which the object file resides, and then to reference
1617 the file by its name, without any path. For instance, a program
1618 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
1619 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
1620 program, type this on VxWorks:
1623 -> cd "@var{vxpath}/vw/demo/rdb"
1626 Then, in @value{GDBN}, type:
1629 (vxgdb) cd @var{hostpath}/vw/demo/rdb
1633 @value{GDBN} displays a response similar to this:
1636 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1639 You can also use the @code{load} command to reload an object module
1640 after editing and recompiling the corresponding source file. Note that
1641 this makes @value{GDBN} delete all currently-defined breakpoints,
1642 auto-displays, and convenience variables, and to clear the value
1643 history. (This is necessary in order to preserve the integrity of
1644 debugger data structures that reference the target system's symbol
1647 @node VxWorks Attach
1648 @subsubsection Running tasks
1650 @cindex running VxWorks tasks
1651 You can also attach to an existing task using the @code{attach} command as
1655 (vxgdb) attach @var{task}
1659 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1660 or suspended when you attach to it. Running tasks are suspended at
1661 the time of attachment.
1663 @node Sparclet Remote
1664 @subsection @value{GDBN} and Sparclet
1667 @value{GDBN} enables developers to debug tasks running on
1668 Sparclet targets from a Unix host.
1669 @value{GDBN} uses code that runs on
1670 both the Unix host and on the Sparclet target. The program
1671 @code{gdb} is installed and executed on the Unix host.
1674 @item timeout @var{args}
1675 @kindex remotetimeout
1676 @value{GDBN} now supports the option @code{remotetimeout}.
1677 This option is set by the user, and @var{args} represents the number of
1678 seconds @value{GDBN} waits for responses.
1682 When compiling for debugging, include the options "-g" to get debug
1683 information and "-Ttext" to relocate the program to where you wish to
1684 load it on the target. You may also want to add the options "-n" or
1685 "-N" in order to reduce the size of the sections.
1688 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
1691 You can use objdump to verify that the addresses are what you intended.
1694 sparclet-aout-objdump --headers --syms prog
1699 your Unix execution search path to find @value{GDBN}, you are ready to
1700 run @value{GDBN}. From your Unix host, run @code{gdb}
1701 (or @code{sparclet-aout-gdb}, depending on your installation).
1703 @value{GDBN} comes up showing the prompt:
1710 * Sparclet File:: Setting the file to debug
1711 * Sparclet Connection:: Connecting to Sparclet
1712 * Sparclet Download:: Sparclet download
1713 * Sparclet Execution:: Running and debugging
1717 @subsubsection Setting file to debug
1719 The @value{GDBN} command @code{file} lets you choose with program to debug.
1726 @value{GDBN} then attempts to read the symbol table of @file{prog}.
1727 @value{GDBN} locates
1728 the file by searching the directories listed in the command search
1730 If the file was compiled with debug information (option "-g"), source
1731 files will be searched as well.
1732 @value{GDBN} locates
1733 the source files by searching the directories listed in the directory search
1734 path (@pxref{Environment, ,Your program's environment}).
1736 to find a file, it displays a message such as:
1739 prog: No such file or directory.
1742 When this happens, add the appropriate directories to the search paths with
1743 the @value{GDBN} commands @code{path} and @code{dir}, and execute the
1744 @code{target} command again.
1746 @node Sparclet Connection
1747 @subsubsection Connecting to Sparclet
1749 The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
1750 To connect to a target on serial port ``@code{ttya}'', type:
1753 (gdbslet) target sparclet /dev/ttya
1754 Remote target sparclet connected to /dev/ttya
1755 main () at ../prog.c:3
1759 @value{GDBN} displays messages like these:
1765 @node Sparclet Download
1766 @subsubsection Sparclet download
1768 @cindex download to Sparclet
1769 Once connected to the Sparclet target,
1770 you can use the @value{GDBN}
1771 @code{load} command to download the file from the host to the target.
1772 The file name and load offset should be given as arguments to the @code{load}
1774 Since the file format is aout, the program must be loaded to the starting
1775 address. You can use objdump to find out what this value is. The load
1776 offset is an offset which is added to the VMA (virtual memory address)
1777 of each of the file's sections.
1778 For instance, if the program
1779 @file{prog} was linked to text address 0x1201000, with data at 0x12010160
1780 and bss at 0x12010170, in @value{GDBN}, type:
1783 (gdbslet) load prog 0x12010000
1784 Loading section .text, size 0xdb0 vma 0x12010000
1787 If the code is loaded at a different address then what the program was linked
1788 to, you may need to use the @code{section} and @code{add-symbol-file} commands
1789 to tell @value{GDBN} where to map the symbol table.
1791 @node Sparclet Execution
1792 @subsubsection Running and debugging
1794 @cindex running and debugging Sparclet programs
1795 You can now begin debugging the task using @value{GDBN}'s execution control
1796 commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
1797 manual for the list of commands.
1801 Breakpoint 1 at 0x12010000: file prog.c, line 3.
1803 Starting program: prog
1804 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
1807 4 char *execarg = "hello!";
1811 @node Hitachi Remote
1812 @subsection @value{GDBN} and Hitachi microprocessors
1813 @value{GDBN} needs to know these things to talk to your
1814 Hitachi SH, H8/300, or H8/500:
1818 that you want to use @samp{target hms}, the remote debugging interface
1819 for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
1820 emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
1821 the default when GDB is configured specifically for the Hitachi SH,
1825 what serial device connects your host to your Hitachi board (the first
1826 serial device available on your host is the default).
1829 what speed to use over the serial device.
1833 * Hitachi Boards:: Connecting to Hitachi boards.
1834 * Hitachi ICE:: Using the E7000 In-Circuit Emulator.
1835 * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
1838 @node Hitachi Boards
1839 @subsubsection Connecting to Hitachi boards
1841 @c only for Unix hosts
1843 @cindex serial device, Hitachi micros
1844 Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
1845 need to explicitly set the serial device. The default @var{port} is the
1846 first available port on your host. This is only necessary on Unix
1847 hosts, where it is typically something like @file{/dev/ttya}.
1850 @cindex serial line speed, Hitachi micros
1851 @code{@value{GDBP}} has another special command to set the communications
1852 speed: @samp{speed @var{bps}}. This command also is only used from Unix
1853 hosts; on DOS hosts, set the line speed as usual from outside GDB with
1854 the DOS @kbd{mode} command (for instance, @w{@samp{mode
1855 com2:9600,n,8,1,p}} for a 9600 bps connection).
1857 The @samp{device} and @samp{speed} commands are available only when you
1858 use a Unix host to debug your Hitachi microprocessor programs. If you
1860 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
1861 called @code{asynctsr} to communicate with the development board
1862 through a PC serial port. You must also use the DOS @code{mode} command
1863 to set up the serial port on the DOS side.
1865 The following sample session illustrates the steps needed to start a
1866 program under @value{GDBN} control on an H8/300. The example uses a
1867 sample H8/300 program called @file{t.x}. The procedure is the same for
1868 the Hitachi SH and the H8/500.
1870 First hook up your development board. In this example, we use a
1871 board attached to serial port @code{COM2}; if you use a different serial
1872 port, substitute its name in the argument of the @code{mode} command.
1873 When you call @code{asynctsr}, the auxiliary comms program used by the
1874 degugger, you give it just the numeric part of the serial port's name;
1875 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
1879 C:\H8300\TEST> asynctsr 2
1880 C:\H8300\TEST> mode com2:9600,n,8,1,p
1882 Resident portion of MODE loaded
1884 COM2: 9600, n, 8, 1, p
1889 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
1890 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
1891 disable it, or even boot without it, to use @code{asynctsr} to control
1892 your development board.
1896 Now that serial communications are set up, and the development board is
1897 connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
1898 the name of your program as the argument. @code{@value{GDBP}} prompts
1899 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
1900 commands to begin your debugging session: @samp{target hms} to specify
1901 cross-debugging to the Hitachi board, and the @code{load} command to
1902 download your program to the board. @code{load} displays the names of
1903 the program's sections, and a @samp{*} for each 2K of data downloaded.
1904 (If you want to refresh @value{GDBN} data on symbols or on the
1905 executable file without downloading, use the @value{GDBN} commands
1906 @code{file} or @code{symbol-file}. These commands, and @code{load}
1907 itself, are described in @ref{Files,,Commands to specify files}.)
1910 (eg-C:\H8300\TEST) @value{GDBP} t.x
1911 GDB is free software and you are welcome to distribute copies
1912 of it under certain conditions; type "show copying" to see
1914 There is absolutely no warranty for GDB; type "show warranty"
1916 GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
1918 Connected to remote H8/300 HMS system.
1920 .text : 0x8000 .. 0xabde ***********
1921 .data : 0xabde .. 0xad30 *
1922 .stack : 0xf000 .. 0xf014 *
1925 At this point, you're ready to run or debug your program. From here on,
1926 you can use all the usual @value{GDBN} commands. The @code{break} command
1927 sets breakpoints; the @code{run} command starts your program;
1928 @code{print} or @code{x} display data; the @code{continue} command
1929 resumes execution after stopping at a breakpoint. You can use the
1930 @code{help} command at any time to find out more about @value{GDBN} commands.
1932 Remember, however, that @emph{operating system} facilities aren't
1933 available on your development board; for example, if your program hangs,
1934 you can't send an interrupt---but you can press the @sc{reset} switch!
1936 Use the @sc{reset} button on the development board
1939 to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
1940 no way to pass an interrupt signal to the development board); and
1943 to return to the @value{GDBN} command prompt after your program finishes
1944 normally. The communications protocol provides no other way for @value{GDBN}
1945 to detect program completion.
1948 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
1949 development board as a ``normal exit'' of your program.
1952 @subsubsection Using the E7000 in-circuit emulator
1954 @kindex target e7000
1955 You can use the E7000 in-circuit emulator to develop code for either the
1956 Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
1957 e7000} command to connect @value{GDBN} to your E7000:
1960 @item target e7000 @var{port} @var{speed}
1961 Use this form if your E7000 is connected to a serial port. The
1962 @var{port} argument identifies what serial port to use (for example,
1963 @samp{com2}). The third argument is the line speed in bits per second
1964 (for example, @samp{9600}).
1966 @item target e7000 @var{hostname}
1967 If your E7000 is installed as a host on a TCP/IP network, you can just
1968 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
1971 @node Hitachi Special
1972 @subsubsection Special @value{GDBN} commands for Hitachi micros
1974 Some @value{GDBN} commands are available only on the H8/300 or the
1975 H8/500 configurations:
1979 @kindex show machine
1980 @item set machine h8300
1981 @itemx set machine h8300h
1982 Condition @value{GDBN} for one of the two variants of the H8/300
1983 architecture with @samp{set machine}. You can use @samp{show machine}
1984 to check which variant is currently in effect.
1986 @kindex set memory @var{mod}
1987 @cindex memory models, H8/500
1988 @item set memory @var{mod}
1990 Specify which H8/500 memory model (@var{mod}) you are using with
1991 @samp{set memory}; check which memory model is in effect with @samp{show
1992 memory}. The accepted values for @var{mod} are @code{small},
1993 @code{big}, @code{medium}, and @code{compact}.
1997 @subsection @value{GDBN} and remote MIPS boards
2000 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
2001 MIPS board attached to a serial line. This is available when
2002 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
2005 Use these @value{GDBN} commands to specify the connection to your target board:
2008 @item target mips @var{port}
2009 @kindex target mips @var{port}
2010 To run a program on the board, start up @code{@value{GDBP}} with the
2011 name of your program as the argument. To connect to the board, use the
2012 command @samp{target mips @var{port}}, where @var{port} is the name of
2013 the serial port connected to the board. If the program has not already
2014 been downloaded to the board, you may use the @code{load} command to
2015 download it. You can then use all the usual @value{GDBN} commands.
2017 For example, this sequence connects to the target board through a serial
2018 port, and loads and runs a program called @var{prog} through the
2022 host$ @value{GDBP} @var{prog}
2023 GDB is free software and @dots{}
2024 (gdb) target mips /dev/ttyb
2025 (gdb) load @var{prog}
2029 @item target mips @var{hostname}:@var{portnumber}
2030 On some @value{GDBN} host configurations, you can specify a TCP
2031 connection (for instance, to a serial line managed by a terminal
2032 concentrator) instead of a serial port, using the syntax
2033 @samp{@var{hostname}:@var{portnumber}}.
2035 @item target pmon @var{port}
2036 @kindex target pmon @var{port}
2038 @item target ddb @var{port}
2039 @kindex target ddb @var{port}
2041 @item target lsi @var{port}
2042 @kindex target lsi @var{port}
2048 @value{GDBN} also supports these special commands for MIPS targets:
2051 @item set processor @var{args}
2052 @itemx show processor
2053 @kindex set processor @var{args}
2054 @kindex show processor
2055 Use the @code{set processor} command to set the type of MIPS
2056 processor when you want to access processor-type-specific registers.
2057 For example, @code{set processor @var{r3041}} tells @value{GDBN}
2058 to use the CPO registers appropriate for the 3041 chip.
2059 Use the @code{show processor} command to see what MIPS processor @value{GDBN}
2060 is using. Use the @code{info reg} command to see what registers
2061 @value{GDBN} is using.
2063 @item set mipsfpu double
2064 @itemx set mipsfpu single
2065 @itemx set mipsfpu none
2068 @kindex show mipsfpu
2069 @cindex MIPS remote floating point
2070 @cindex floating point, MIPS remote
2071 If your target board does not support the MIPS floating point
2072 coprocessor, you should use the command @samp{set mipsfpu none} (if you
2073 need this, you may wish to put the command in your @value{GDBINIT}
2074 file). This tells @value{GDBN} how to find the return value of
2075 functions which return floating point values. It also allows
2076 @value{GDBN} to avoid saving the floating point registers when calling
2077 functions on the board. If you are using a floating point coprocessor
2078 with only single precision floating point support, as on the @sc{r4650}
2079 processor, use the command @samp{set mipsfpu single}. The default
2080 double precision floating point coprocessor may be selected using
2081 @samp{set mipsfpu double}.
2083 In previous versions the only choices were double precision or no
2084 floating point, so @samp{set mipsfpu on} will select double precision
2085 and @samp{set mipsfpu off} will select no floating point.
2087 As usual, you can inquire about the @code{mipsfpu} variable with
2088 @samp{show mipsfpu}.
2090 @item set remotedebug @var{n}
2091 @itemx show remotedebug
2092 @kindex set remotedebug
2093 @kindex show remotedebug
2094 @cindex @code{remotedebug}, MIPS protocol
2095 @cindex MIPS @code{remotedebug} protocol
2096 @c FIXME! For this to be useful, you must know something about the MIPS
2097 @c FIXME...protocol. Where is it described?
2098 You can see some debugging information about communications with the board
2099 by setting the @code{remotedebug} variable. If you set it to @code{1} using
2100 @samp{set remotedebug 1}, every packet is displayed. If you set it
2101 to @code{2}, every character is displayed. You can check the current value
2102 at any time with the command @samp{show remotedebug}.
2104 @item set timeout @var{seconds}
2105 @itemx set retransmit-timeout @var{seconds}
2107 @itemx show retransmit-timeout
2108 @cindex @code{timeout}, MIPS protocol
2109 @cindex @code{retransmit-timeout}, MIPS protocol
2111 @kindex show timeout
2112 @kindex set retransmit-timeout
2113 @kindex show retransmit-timeout
2114 You can control the timeout used while waiting for a packet, in the MIPS
2115 remote protocol, with the @code{set timeout @var{seconds}} command. The
2116 default is 5 seconds. Similarly, you can control the timeout used while
2117 waiting for an acknowledgement of a packet with the @code{set
2118 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
2119 You can inspect both values with @code{show timeout} and @code{show
2120 retransmit-timeout}. (These commands are @emph{only} available when
2121 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
2123 The timeout set by @code{set timeout} does not apply when @value{GDBN}
2124 is waiting for your program to stop. In that case, @value{GDBN} waits
2125 forever because it has no way of knowing how long the program is going
2126 to run before stopping.
2130 @subsection Simulated CPU target
2133 @cindex simulator, Z8000
2134 @cindex Z8000 simulator
2135 @cindex simulator, H8/300 or H8/500
2136 @cindex H8/300 or H8/500 simulator
2137 @cindex simulator, Hitachi SH
2138 @cindex Hitachi SH simulator
2139 @cindex CPU simulator
2140 For some configurations, @value{GDBN} includes a CPU simulator that you
2141 can use instead of a hardware CPU to debug your programs.
2142 Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300,
2143 H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
2146 @cindex simulator, Z8000
2147 @cindex Zilog Z8000 simulator
2148 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
2151 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
2152 unsegmented variant of the Z8000 architecture) or the Z8001 (the
2153 segmented variant). The simulator recognizes which architecture is
2154 appropriate by inspecting the object code.
2157 @item target sim @var{args}
2160 Debug programs on a simulated CPU. If the simulator supports setup
2161 options, specify them via @var{args}.
2165 After specifying this target, you can debug programs for the simulated
2166 CPU in the same style as programs for your host computer; use the
2167 @code{file} command to load a new program image, the @code{run} command
2168 to run your program, and so on.
2170 As well as making available all the usual machine registers (see
2171 @code{info reg}), the Z8000 simulator provides three additional items
2172 of information as specially named registers:
2176 Counts clock-ticks in the simulator.
2179 Counts instructions run in the simulator.
2182 Execution time in 60ths of a second.
2185 You can refer to these values in @value{GDBN} expressions with the usual
2186 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
2187 conditional breakpoint that suspends only after at least 5000
2188 simulated clock ticks.
2190 @c need to add much more detail about sims!