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()}.
767 @tab @code{q}@code{Rcmd,}@var{COMMAND}
769 @var{COMMAND} (hex encoded) is passed to the local interpreter for
770 execution. Invalid commands should be reported using the output string.
771 Before the final result packet, the target may also respond with a
772 number of intermediate @code{O}@var{OUTPUT} console output
773 packets. @emph{Implementors should note that providing access to a
774 stubs's interpreter may have security implications}.
778 A command response with no output.
780 @tab reply @var{OUTPUT}
782 A command response with the hex encoded output string @var{OUTPUT}.
784 @tab reply @code{E}@var{NN}
786 Indicate a badly formed request.
791 When @samp{q}@samp{Rcmd} is not recognized.
793 @item general set @emph{(optional)}
794 @tab @code{Q}@var{var}@code{=}@var{val}
796 Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
799 @item reset @emph{(optional)}
801 @tab reset -- see sparc stub.
803 @item remote restart @emph{(optional)}
804 @tab @code{R}@var{XX}
806 Restart the remote server. @var{XX} while needed has no clear
809 @item step @emph{(optional)}
810 @tab @code{s}@var{addr}
812 @var{addr} is address to resume. If @var{addr} is omitted, resume at
818 @item step with signal @emph{(optional)}
819 @tab @code{S}@var{sig}@code{;}@var{addr}
821 Like @samp{C} but step not continue.
826 @item search @emph{(optional)}
827 @tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
829 Search backwards starting at address @var{addr} for a match with pattern
830 @var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
831 bytes. @var{addr} must be at least 3 digits.
833 @item thread alive @emph{(optional)}
834 @tab @code{T}@var{XX}
835 @tab Find out if the thread XX is alive.
838 @tab thread is still alive
840 @tab reply @code{E}@var{NN}
845 @tab Reserved for future use
849 @tab Reserved for future use
853 @tab Reserved for future use
857 @tab Reserved for future use
861 @tab Reserved for future use
865 @tab Reserved for future use
869 @tab Reserved for future use
871 @item write mem (binary) @emph{(optional)}
872 @tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
874 @var{addr} is address, @var{length} is number of bytes, @var{XX...} is
880 @tab reply @code{E}@var{NN}
885 @tab Reserved for future use
889 @tab Reserved for future use
891 @item remove break or watchpoint @strong{(draft)} @emph{(optional)}
892 @tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
896 @item insert break or watchpoint @strong{(draft)} @emph{(optional)}
897 @tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
899 @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
900 breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
901 @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
902 bytes. For a software breakpoint, @var{length} specifies the size of
903 the instruction to be patched. For hardware breakpoints and watchpoints
904 @var{length} specifies the memory region to be monitored.
906 @tab reply @code{E}@var{NN}
913 @tab If not supported.
917 @tab Reserved for future use
921 In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets,
922 there is no immediate response. The reply, described below, comes when
925 @multitable @columnfractions .4 .6
927 @item @code{S}@var{AA}
928 @tab @var{AA} is the signal number
930 @item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
932 @var{AA} = two hex digit signal number; @var{n...} = register number
933 (hex), @var{r...} = target byte ordered register contents, size defined
934 by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
935 thread process ID, this is a hex integer; @var{n...} = other string not
936 starting with valid hex digit. @value{GDBN} should ignore this
937 @var{n...}, @var{r...} pair and go on to the next. This way we can
940 @item @code{W}@var{AA}
942 The process exited, and @var{AA} is the exit status. This is only
943 applicable for certains sorts of targets.
945 @item @code{X}@var{AA}
947 The process terminated with signal @var{AA}.
949 @item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)}
951 @var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
952 @var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss
953 section. @emph{Note: only used by Cisco Systems targets. The difference
954 between this reply and the "qOffsets" query is that the 'N' packet may
955 arrive spontaneously whereas the 'qOffsets' is a query initiated by the
958 @item @code{O}@var{XX...}
960 @var{XX...} is hex encoding of ASCII data. This can happen at any time
961 while the program is running and the debugger should continue to wait
966 Example sequence of a target being re-started. Notice how the restart
967 does not get any direct output:
972 @emph{target restarts}
975 -> @code{T001:1234123412341234}
979 Example sequence of a target being stepped by a single instruction:
987 -> @code{T001:1234123412341234}
995 @kindex set remotedebug
996 @kindex show remotedebug
997 @cindex packets, reporting on stdout
998 @cindex serial connections, debugging
999 If you have trouble with the serial connection, you can use the command
1000 @code{set remotedebug}. This makes @value{GDBN} report on all packets sent
1001 back and forth across the serial line to the remote machine. The
1002 packet-debugging information is printed on the @value{GDBN} standard output
1003 stream. @code{set remotedebug off} turns it off, and @code{show
1004 remotedebug} shows you its current state.
1007 @subsubsection Using the @code{gdbserver} program
1010 @cindex remote connection without stubs
1011 @code{gdbserver} is a control program for Unix-like systems, which
1012 allows you to connect your program with a remote @value{GDBN} via
1013 @code{target remote}---but without linking in the usual debugging stub.
1015 @code{gdbserver} is not a complete replacement for the debugging stubs,
1016 because it requires essentially the same operating-system facilities
1017 that @value{GDBN} itself does. In fact, a system that can run
1018 @code{gdbserver} to connect to a remote @value{GDBN} could also run
1019 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
1020 because it is a much smaller program than @value{GDBN} itself. It is
1021 also easier to port than all of @value{GDBN}, so you may be able to get
1022 started more quickly on a new system by using @code{gdbserver}.
1023 Finally, if you develop code for real-time systems, you may find that
1024 the tradeoffs involved in real-time operation make it more convenient to
1025 do as much development work as possible on another system, for example
1026 by cross-compiling. You can use @code{gdbserver} to make a similar
1027 choice for debugging.
1029 @value{GDBN} and @code{gdbserver} communicate via either a serial line
1030 or a TCP connection, using the standard @value{GDBN} remote serial
1034 @item On the target machine,
1035 you need to have a copy of the program you want to debug.
1036 @code{gdbserver} does not need your program's symbol table, so you can
1037 strip the program if necessary to save space. @value{GDBN} on the host
1038 system does all the symbol handling.
1040 To use the server, you must tell it how to communicate with @value{GDBN};
1041 the name of your program; and the arguments for your program. The
1045 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
1048 @var{comm} is either a device name (to use a serial line) or a TCP
1049 hostname and portnumber. For example, to debug Emacs with the argument
1050 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
1054 target> gdbserver /dev/com1 emacs foo.txt
1057 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
1060 To use a TCP connection instead of a serial line:
1063 target> gdbserver host:2345 emacs foo.txt
1066 The only difference from the previous example is the first argument,
1067 specifying that you are communicating with the host @value{GDBN} via
1068 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
1069 expect a TCP connection from machine @samp{host} to local TCP port 2345.
1070 (Currently, the @samp{host} part is ignored.) You can choose any number
1071 you want for the port number as long as it does not conflict with any
1072 TCP ports already in use on the target system (for example, @code{23} is
1073 reserved for @code{telnet}).@footnote{If you choose a port number that
1074 conflicts with another service, @code{gdbserver} prints an error message
1075 and exits.} You must use the same port number with the host @value{GDBN}
1076 @code{target remote} command.
1078 @item On the @value{GDBN} host machine,
1079 you need an unstripped copy of your program, since @value{GDBN} needs
1080 symbols and debugging information. Start up @value{GDBN} as usual,
1081 using the name of the local copy of your program as the first argument.
1082 (You may also need the @w{@samp{--baud}} option if the serial line is
1083 running at anything other than 9600 bps.) After that, use @code{target
1084 remote} to establish communications with @code{gdbserver}. Its argument
1085 is either a device name (usually a serial device, like
1086 @file{/dev/ttyb}), or a TCP port descriptor in the form
1087 @code{@var{host}:@var{PORT}}. For example:
1090 (@value{GDBP}) target remote /dev/ttyb
1094 communicates with the server via serial line @file{/dev/ttyb}, and
1097 (@value{GDBP}) target remote the-target:2345
1101 communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
1102 For TCP connections, you must start up @code{gdbserver} prior to using
1103 the @code{target remote} command. Otherwise you may get an error whose
1104 text depends on the host system, but which usually looks something like
1105 @samp{Connection refused}.
1109 @subsubsection Using the @code{gdbserve.nlm} program
1111 @kindex gdbserve.nlm
1112 @code{gdbserve.nlm} is a control program for NetWare systems, which
1113 allows you to connect your program with a remote @value{GDBN} via
1114 @code{target remote}.
1116 @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
1117 using the standard @value{GDBN} remote serial protocol.
1120 @item On the target machine,
1121 you need to have a copy of the program you want to debug.
1122 @code{gdbserve.nlm} does not need your program's symbol table, so you
1123 can strip the program if necessary to save space. @value{GDBN} on the
1124 host system does all the symbol handling.
1126 To use the server, you must tell it how to communicate with
1127 @value{GDBN}; the name of your program; and the arguments for your
1128 program. The syntax is:
1131 load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
1132 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
1135 @var{board} and @var{port} specify the serial line; @var{baud} specifies
1136 the baud rate used by the connection. @var{port} and @var{node} default
1137 to 0, @var{baud} defaults to 9600 bps.
1139 For example, to debug Emacs with the argument @samp{foo.txt}and
1140 communicate with @value{GDBN} over serial port number 2 or board 1
1141 using a 19200 bps connection:
1144 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
1147 @item On the @value{GDBN} host machine,
1148 you need an unstripped copy of your program, since @value{GDBN} needs
1149 symbols and debugging information. Start up @value{GDBN} as usual,
1150 using the name of the local copy of your program as the first argument.
1151 (You may also need the @w{@samp{--baud}} option if the serial line is
1152 running at anything other than 9600 bps. After that, use @code{target
1153 remote} to establish communications with @code{gdbserve.nlm}. Its
1154 argument is a device name (usually a serial device, like
1155 @file{/dev/ttyb}). For example:
1158 (@value{GDBP}) target remote /dev/ttyb
1162 communications with the server via serial line @file{/dev/ttyb}.
1165 @node i960-Nindy Remote
1166 @subsection @value{GDBN} with a remote i960 (Nindy)
1170 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
1171 @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
1172 tell @value{GDBN} how to connect to the 960 in several ways:
1176 Through command line options specifying serial port, version of the
1177 Nindy protocol, and communications speed;
1180 By responding to a prompt on startup;
1183 By using the @code{target} command at any point during your @value{GDBN}
1184 session. @xref{Target Commands, ,Commands for managing targets}.
1189 * Nindy Startup:: Startup with Nindy
1190 * Nindy Options:: Options for Nindy
1191 * Nindy Reset:: Nindy reset command
1195 @subsubsection Startup with Nindy
1197 If you simply start @code{@value{GDBP}} without using any command-line
1198 options, you are prompted for what serial port to use, @emph{before} you
1199 reach the ordinary @value{GDBN} prompt:
1202 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
1206 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
1207 identifies the serial port you want to use. You can, if you choose,
1208 simply start up with no Nindy connection by responding to the prompt
1209 with an empty line. If you do this and later wish to attach to Nindy,
1210 use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
1213 @subsubsection Options for Nindy
1215 These are the startup options for beginning your @value{GDBN} session with a
1216 Nindy-960 board attached:
1220 Specify the serial port name of a serial interface to be used to connect
1221 to the target system. This option is only available when @value{GDBN} is
1222 configured for the Intel 960 target architecture. You may specify
1223 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
1224 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
1225 suffix for a specific @code{tty} (e.g. @samp{-r a}).
1228 (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
1229 the ``old'' Nindy monitor protocol to connect to the target system.
1230 This option is only available when @value{GDBN} is configured for the Intel 960
1231 target architecture.
1234 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
1235 connect to a target system that expects the newer protocol, the connection
1236 fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
1237 attempts to reconnect at several different line speeds. You can abort
1238 this process with an interrupt.
1242 Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
1243 system, in an attempt to reset it, before connecting to a Nindy target.
1246 @emph{Warning:} Many target systems do not have the hardware that this
1247 requires; it only works with a few boards.
1251 The standard @samp{-b} option controls the line speed used on the serial
1256 @subsubsection Nindy reset command
1261 For a Nindy target, this command sends a ``break'' to the remote target
1262 system; this is only useful if the target has been equipped with a
1263 circuit to perform a hard reset (or some other interesting action) when
1264 a break is detected.
1269 @subsection The UDI protocol for AMD29K
1272 @cindex AMD29K via UDI
1273 @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
1274 protocol for debugging the a29k processor family. To use this
1275 configuration with AMD targets running the MiniMON monitor, you need the
1276 program @code{MONTIP}, available from AMD at no charge. You can also
1277 use @value{GDBN} with the UDI-conformant a29k simulator program
1278 @code{ISSTIP}, also available from AMD.
1281 @item target udi @var{keyword}
1283 Select the UDI interface to a remote a29k board or simulator, where
1284 @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
1285 This file contains keyword entries which specify parameters used to
1286 connect to a29k targets. If the @file{udi_soc} file is not in your
1287 working directory, you must set the environment variable @samp{UDICONF}
1292 @subsection The EBMON protocol for AMD29K
1295 @cindex running 29K programs
1297 AMD distributes a 29K development board meant to fit in a PC, together
1298 with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
1299 term, this development system is called the ``EB29K''. To use
1300 @value{GDBN} from a Unix system to run programs on the EB29K board, you
1301 must first connect a serial cable between the PC (which hosts the EB29K
1302 board) and a serial port on the Unix system. In the following, we
1303 assume you've hooked the cable between the PC's @file{COM1} port and
1304 @file{/dev/ttya} on the Unix system.
1307 * Comms (EB29K):: Communications setup
1308 * gdb-EB29K:: EB29K cross-debugging
1309 * Remote Log:: Remote log
1313 @subsubsection Communications setup
1315 The next step is to set up the PC's port, by doing something like this
1319 C:\> MODE com1:9600,n,8,1,none
1323 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
1324 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
1325 you must match the communications parameters when establishing the Unix
1326 end of the connection as well.
1327 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
1328 @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
1330 To give control of the PC to the Unix side of the serial line, type
1331 the following at the DOS console:
1338 (Later, if you wish to return control to the DOS console, you can use
1339 the command @code{CTTY con}---but you must send it over the device that
1340 had control, in our example over the @file{COM1} serial line).
1342 From the Unix host, use a communications program such as @code{tip} or
1343 @code{cu} to communicate with the PC; for example,
1346 cu -s 9600 -l /dev/ttya
1350 The @code{cu} options shown specify, respectively, the linespeed and the
1351 serial port to use. If you use @code{tip} instead, your command line
1352 may look something like the following:
1359 Your system may require a different name where we show
1360 @file{/dev/ttya} as the argument to @code{tip}. The communications
1361 parameters, including which port to use, are associated with the
1362 @code{tip} argument in the ``remote'' descriptions file---normally the
1363 system table @file{/etc/remote}.
1364 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
1365 @c the DOS side's comms setup? cu can support -o (odd
1366 @c parity), -e (even parity)---apparently no settings for no parity or
1367 @c for character size. Taken from stty maybe...? John points out tip
1368 @c can set these as internal variables, eg ~s parity=none; man stty
1369 @c suggests that it *might* work to stty these options with stdin or
1370 @c stdout redirected... ---doc@cygnus.com, 25feb91
1373 Using the @code{tip} or @code{cu} connection, change the DOS working
1374 directory to the directory containing a copy of your 29K program, then
1375 start the PC program @code{EBMON} (an EB29K control program supplied
1376 with your board by AMD). You should see an initial display from
1377 @code{EBMON} similar to the one that follows, ending with the
1378 @code{EBMON} prompt @samp{#}---
1383 G:\> CD \usr\joe\work29k
1385 G:\USR\JOE\WORK29K> EBMON
1386 Am29000 PC Coprocessor Board Monitor, version 3.0-18
1387 Copyright 1990 Advanced Micro Devices, Inc.
1388 Written by Gibbons and Associates, Inc.
1390 Enter '?' or 'H' for help
1392 PC Coprocessor Type = EB29K
1394 Memory Base = 0xd0000
1396 Data Memory Size = 2048KB
1397 Available I-RAM Range = 0x8000 to 0x1fffff
1398 Available D-RAM Range = 0x80002000 to 0x801fffff
1401 Register Stack Size = 0x800
1402 Memory Stack Size = 0x1800
1405 Am29027 Available = No
1406 Byte Write Available = Yes
1411 Then exit the @code{cu} or @code{tip} program (done in the example by
1412 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
1413 running, ready for @value{GDBN} to take over.
1415 For this example, we've assumed what is probably the most convenient
1416 way to make sure the same 29K program is on both the PC and the Unix
1417 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
1418 PC as a file system on the Unix host. If you do not have PC/NFS or
1419 something similar connecting the two systems, you must arrange some
1420 other way---perhaps floppy-disk transfer---of getting the 29K program
1421 from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
1425 @subsubsection EB29K cross-debugging
1427 Finally, @code{cd} to the directory containing an image of your 29K
1428 program on the Unix system, and start @value{GDBN}---specifying as argument the
1429 name of your 29K program:
1437 Now you can use the @code{target} command:
1440 target amd-eb /dev/ttya 9600 MYFOO
1441 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
1442 @c emphasize that this is the name as seen by DOS (since I think DOS is
1443 @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
1447 In this example, we've assumed your program is in a file called
1448 @file{myfoo}. Note that the filename given as the last argument to
1449 @code{target amd-eb} should be the name of the program as it appears to DOS.
1450 In our example this is simply @code{MYFOO}, but in general it can include
1451 a DOS path, and depending on your transfer mechanism may not resemble
1452 the name on the Unix side.
1454 At this point, you can set any breakpoints you wish; when you are ready
1455 to see your program run on the 29K board, use the @value{GDBN} command
1458 To stop debugging the remote program, use the @value{GDBN} @code{detach}
1461 To return control of the PC to its console, use @code{tip} or @code{cu}
1462 once again, after your @value{GDBN} session has concluded, to attach to
1463 @code{EBMON}. You can then type the command @code{q} to shut down
1464 @code{EBMON}, returning control to the DOS command-line interpreter.
1465 Type @code{CTTY con} to return command input to the main DOS console,
1466 and type @kbd{~.} to leave @code{tip} or @code{cu}.
1469 @subsubsection Remote log
1471 @cindex log file for EB29K
1473 The @code{target amd-eb} command creates a file @file{eb.log} in the
1474 current working directory, to help debug problems with the connection.
1475 @file{eb.log} records all the output from @code{EBMON}, including echoes
1476 of the commands sent to it. Running @samp{tail -f} on this file in
1477 another window often helps to understand trouble with @code{EBMON}, or
1478 unexpected events on the PC side of the connection.
1481 @subsection @value{GDBN} with a Tandem ST2000
1483 To connect your ST2000 to the host system, see the manufacturer's
1484 manual. Once the ST2000 is physically attached, you can run:
1487 target st2000 @var{dev} @var{speed}
1491 to establish it as your debugging environment. @var{dev} is normally
1492 the name of a serial device, such as @file{/dev/ttya}, connected to the
1493 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
1494 connection (for example, to a serial line attached via a terminal
1495 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
1497 The @code{load} and @code{attach} commands are @emph{not} defined for
1498 this target; you must load your program into the ST2000 as you normally
1499 would for standalone operation. @value{GDBN} reads debugging information
1500 (such as symbols) from a separate, debugging version of the program
1501 available on your host computer.
1502 @c FIXME!! This is terribly vague; what little content is here is
1503 @c basically hearsay.
1505 @cindex ST2000 auxiliary commands
1506 These auxiliary @value{GDBN} commands are available to help you with the ST2000
1510 @item st2000 @var{command}
1511 @kindex st2000 @var{cmd}
1512 @cindex STDBUG commands (ST2000)
1513 @cindex commands to STDBUG (ST2000)
1514 Send a @var{command} to the STDBUG monitor. See the manufacturer's
1515 manual for available commands.
1518 @cindex connect (to STDBUG)
1519 Connect the controlling terminal to the STDBUG command monitor. When
1520 you are done interacting with STDBUG, typing either of two character
1521 sequences gets you back to the @value{GDBN} command prompt:
1522 @kbd{@key{RET}~.} (Return, followed by tilde and period) or
1523 @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
1526 @node VxWorks Remote
1527 @subsection @value{GDBN} and VxWorks
1531 @value{GDBN} enables developers to spawn and debug tasks running on networked
1532 VxWorks targets from a Unix host. Already-running tasks spawned from
1533 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
1534 both the Unix host and on the VxWorks target. The program
1535 @code{gdb} is installed and executed on the Unix host. (It may be
1536 installed with the name @code{vxgdb}, to distinguish it from a
1537 @value{GDBN} for debugging programs on the host itself.)
1540 @item VxWorks-timeout @var{args}
1541 @kindex vxworks-timeout
1542 All VxWorks-based targets now support the option @code{vxworks-timeout}.
1543 This option is set by the user, and @var{args} represents the number of
1544 seconds @value{GDBN} waits for responses to rpc's. You might use this if
1545 your VxWorks target is a slow software simulator or is on the far side
1546 of a thin network line.
1549 The following information on connecting to VxWorks was current when
1550 this manual was produced; newer releases of VxWorks may use revised
1554 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
1555 to include the remote debugging interface routines in the VxWorks
1556 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
1557 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
1558 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
1559 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1560 information on configuring and remaking VxWorks, see the manufacturer's
1562 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
1564 Once you have included @file{rdb.a} in your VxWorks system image and set
1565 your Unix execution search path to find @value{GDBN}, you are ready to
1566 run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb},
1567 depending on your installation).
1569 @value{GDBN} comes up showing the prompt:
1576 * VxWorks Connection:: Connecting to VxWorks
1577 * VxWorks Download:: VxWorks download
1578 * VxWorks Attach:: Running tasks
1581 @node VxWorks Connection
1582 @subsubsection Connecting to VxWorks
1584 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
1585 network. To connect to a target whose host name is ``@code{tt}'', type:
1588 (vxgdb) target vxworks tt
1592 @value{GDBN} displays messages like these:
1595 Attaching remote machine across net...
1600 @value{GDBN} then attempts to read the symbol tables of any object modules
1601 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
1602 these files by searching the directories listed in the command search
1603 path (@pxref{Environment, ,Your program's environment}); if it fails
1604 to find an object file, it displays a message such as:
1607 prog.o: No such file or directory.
1610 When this happens, add the appropriate directory to the search path with
1611 the @value{GDBN} command @code{path}, and execute the @code{target}
1614 @node VxWorks Download
1615 @subsubsection VxWorks download
1617 @cindex download to VxWorks
1618 If you have connected to the VxWorks target and you want to debug an
1619 object that has not yet been loaded, you can use the @value{GDBN}
1620 @code{load} command to download a file from Unix to VxWorks
1621 incrementally. The object file given as an argument to the @code{load}
1622 command is actually opened twice: first by the VxWorks target in order
1623 to download the code, then by @value{GDBN} in order to read the symbol
1624 table. This can lead to problems if the current working directories on
1625 the two systems differ. If both systems have NFS mounted the same
1626 filesystems, you can avoid these problems by using absolute paths.
1627 Otherwise, it is simplest to set the working directory on both systems
1628 to the directory in which the object file resides, and then to reference
1629 the file by its name, without any path. For instance, a program
1630 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
1631 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
1632 program, type this on VxWorks:
1635 -> cd "@var{vxpath}/vw/demo/rdb"
1638 Then, in @value{GDBN}, type:
1641 (vxgdb) cd @var{hostpath}/vw/demo/rdb
1645 @value{GDBN} displays a response similar to this:
1648 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1651 You can also use the @code{load} command to reload an object module
1652 after editing and recompiling the corresponding source file. Note that
1653 this makes @value{GDBN} delete all currently-defined breakpoints,
1654 auto-displays, and convenience variables, and to clear the value
1655 history. (This is necessary in order to preserve the integrity of
1656 debugger data structures that reference the target system's symbol
1659 @node VxWorks Attach
1660 @subsubsection Running tasks
1662 @cindex running VxWorks tasks
1663 You can also attach to an existing task using the @code{attach} command as
1667 (vxgdb) attach @var{task}
1671 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1672 or suspended when you attach to it. Running tasks are suspended at
1673 the time of attachment.
1675 @node Sparclet Remote
1676 @subsection @value{GDBN} and Sparclet
1679 @value{GDBN} enables developers to debug tasks running on
1680 Sparclet targets from a Unix host.
1681 @value{GDBN} uses code that runs on
1682 both the Unix host and on the Sparclet target. The program
1683 @code{gdb} is installed and executed on the Unix host.
1686 @item timeout @var{args}
1687 @kindex remotetimeout
1688 @value{GDBN} now supports the option @code{remotetimeout}.
1689 This option is set by the user, and @var{args} represents the number of
1690 seconds @value{GDBN} waits for responses.
1694 When compiling for debugging, include the options "-g" to get debug
1695 information and "-Ttext" to relocate the program to where you wish to
1696 load it on the target. You may also want to add the options "-n" or
1697 "-N" in order to reduce the size of the sections.
1700 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
1703 You can use objdump to verify that the addresses are what you intended.
1706 sparclet-aout-objdump --headers --syms prog
1711 your Unix execution search path to find @value{GDBN}, you are ready to
1712 run @value{GDBN}. From your Unix host, run @code{gdb}
1713 (or @code{sparclet-aout-gdb}, depending on your installation).
1715 @value{GDBN} comes up showing the prompt:
1722 * Sparclet File:: Setting the file to debug
1723 * Sparclet Connection:: Connecting to Sparclet
1724 * Sparclet Download:: Sparclet download
1725 * Sparclet Execution:: Running and debugging
1729 @subsubsection Setting file to debug
1731 The @value{GDBN} command @code{file} lets you choose with program to debug.
1738 @value{GDBN} then attempts to read the symbol table of @file{prog}.
1739 @value{GDBN} locates
1740 the file by searching the directories listed in the command search
1742 If the file was compiled with debug information (option "-g"), source
1743 files will be searched as well.
1744 @value{GDBN} locates
1745 the source files by searching the directories listed in the directory search
1746 path (@pxref{Environment, ,Your program's environment}).
1748 to find a file, it displays a message such as:
1751 prog: No such file or directory.
1754 When this happens, add the appropriate directories to the search paths with
1755 the @value{GDBN} commands @code{path} and @code{dir}, and execute the
1756 @code{target} command again.
1758 @node Sparclet Connection
1759 @subsubsection Connecting to Sparclet
1761 The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
1762 To connect to a target on serial port ``@code{ttya}'', type:
1765 (gdbslet) target sparclet /dev/ttya
1766 Remote target sparclet connected to /dev/ttya
1767 main () at ../prog.c:3
1771 @value{GDBN} displays messages like these:
1777 @node Sparclet Download
1778 @subsubsection Sparclet download
1780 @cindex download to Sparclet
1781 Once connected to the Sparclet target,
1782 you can use the @value{GDBN}
1783 @code{load} command to download the file from the host to the target.
1784 The file name and load offset should be given as arguments to the @code{load}
1786 Since the file format is aout, the program must be loaded to the starting
1787 address. You can use objdump to find out what this value is. The load
1788 offset is an offset which is added to the VMA (virtual memory address)
1789 of each of the file's sections.
1790 For instance, if the program
1791 @file{prog} was linked to text address 0x1201000, with data at 0x12010160
1792 and bss at 0x12010170, in @value{GDBN}, type:
1795 (gdbslet) load prog 0x12010000
1796 Loading section .text, size 0xdb0 vma 0x12010000
1799 If the code is loaded at a different address then what the program was linked
1800 to, you may need to use the @code{section} and @code{add-symbol-file} commands
1801 to tell @value{GDBN} where to map the symbol table.
1803 @node Sparclet Execution
1804 @subsubsection Running and debugging
1806 @cindex running and debugging Sparclet programs
1807 You can now begin debugging the task using @value{GDBN}'s execution control
1808 commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
1809 manual for the list of commands.
1813 Breakpoint 1 at 0x12010000: file prog.c, line 3.
1815 Starting program: prog
1816 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
1819 4 char *execarg = "hello!";
1823 @node Hitachi Remote
1824 @subsection @value{GDBN} and Hitachi microprocessors
1825 @value{GDBN} needs to know these things to talk to your
1826 Hitachi SH, H8/300, or H8/500:
1830 that you want to use @samp{target hms}, the remote debugging interface
1831 for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
1832 emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
1833 the default when GDB is configured specifically for the Hitachi SH,
1837 what serial device connects your host to your Hitachi board (the first
1838 serial device available on your host is the default).
1841 what speed to use over the serial device.
1845 * Hitachi Boards:: Connecting to Hitachi boards.
1846 * Hitachi ICE:: Using the E7000 In-Circuit Emulator.
1847 * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
1850 @node Hitachi Boards
1851 @subsubsection Connecting to Hitachi boards
1853 @c only for Unix hosts
1855 @cindex serial device, Hitachi micros
1856 Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
1857 need to explicitly set the serial device. The default @var{port} is the
1858 first available port on your host. This is only necessary on Unix
1859 hosts, where it is typically something like @file{/dev/ttya}.
1862 @cindex serial line speed, Hitachi micros
1863 @code{@value{GDBP}} has another special command to set the communications
1864 speed: @samp{speed @var{bps}}. This command also is only used from Unix
1865 hosts; on DOS hosts, set the line speed as usual from outside GDB with
1866 the DOS @kbd{mode} command (for instance, @w{@samp{mode
1867 com2:9600,n,8,1,p}} for a 9600 bps connection).
1869 The @samp{device} and @samp{speed} commands are available only when you
1870 use a Unix host to debug your Hitachi microprocessor programs. If you
1872 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
1873 called @code{asynctsr} to communicate with the development board
1874 through a PC serial port. You must also use the DOS @code{mode} command
1875 to set up the serial port on the DOS side.
1877 The following sample session illustrates the steps needed to start a
1878 program under @value{GDBN} control on an H8/300. The example uses a
1879 sample H8/300 program called @file{t.x}. The procedure is the same for
1880 the Hitachi SH and the H8/500.
1882 First hook up your development board. In this example, we use a
1883 board attached to serial port @code{COM2}; if you use a different serial
1884 port, substitute its name in the argument of the @code{mode} command.
1885 When you call @code{asynctsr}, the auxiliary comms program used by the
1886 degugger, you give it just the numeric part of the serial port's name;
1887 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
1891 C:\H8300\TEST> asynctsr 2
1892 C:\H8300\TEST> mode com2:9600,n,8,1,p
1894 Resident portion of MODE loaded
1896 COM2: 9600, n, 8, 1, p
1901 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
1902 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
1903 disable it, or even boot without it, to use @code{asynctsr} to control
1904 your development board.
1908 Now that serial communications are set up, and the development board is
1909 connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
1910 the name of your program as the argument. @code{@value{GDBP}} prompts
1911 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
1912 commands to begin your debugging session: @samp{target hms} to specify
1913 cross-debugging to the Hitachi board, and the @code{load} command to
1914 download your program to the board. @code{load} displays the names of
1915 the program's sections, and a @samp{*} for each 2K of data downloaded.
1916 (If you want to refresh @value{GDBN} data on symbols or on the
1917 executable file without downloading, use the @value{GDBN} commands
1918 @code{file} or @code{symbol-file}. These commands, and @code{load}
1919 itself, are described in @ref{Files,,Commands to specify files}.)
1922 (eg-C:\H8300\TEST) @value{GDBP} t.x
1923 GDB is free software and you are welcome to distribute copies
1924 of it under certain conditions; type "show copying" to see
1926 There is absolutely no warranty for GDB; type "show warranty"
1928 GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
1930 Connected to remote H8/300 HMS system.
1932 .text : 0x8000 .. 0xabde ***********
1933 .data : 0xabde .. 0xad30 *
1934 .stack : 0xf000 .. 0xf014 *
1937 At this point, you're ready to run or debug your program. From here on,
1938 you can use all the usual @value{GDBN} commands. The @code{break} command
1939 sets breakpoints; the @code{run} command starts your program;
1940 @code{print} or @code{x} display data; the @code{continue} command
1941 resumes execution after stopping at a breakpoint. You can use the
1942 @code{help} command at any time to find out more about @value{GDBN} commands.
1944 Remember, however, that @emph{operating system} facilities aren't
1945 available on your development board; for example, if your program hangs,
1946 you can't send an interrupt---but you can press the @sc{reset} switch!
1948 Use the @sc{reset} button on the development board
1951 to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
1952 no way to pass an interrupt signal to the development board); and
1955 to return to the @value{GDBN} command prompt after your program finishes
1956 normally. The communications protocol provides no other way for @value{GDBN}
1957 to detect program completion.
1960 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
1961 development board as a ``normal exit'' of your program.
1964 @subsubsection Using the E7000 in-circuit emulator
1966 @kindex target e7000
1967 You can use the E7000 in-circuit emulator to develop code for either the
1968 Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
1969 e7000} command to connect @value{GDBN} to your E7000:
1972 @item target e7000 @var{port} @var{speed}
1973 Use this form if your E7000 is connected to a serial port. The
1974 @var{port} argument identifies what serial port to use (for example,
1975 @samp{com2}). The third argument is the line speed in bits per second
1976 (for example, @samp{9600}).
1978 @item target e7000 @var{hostname}
1979 If your E7000 is installed as a host on a TCP/IP network, you can just
1980 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
1983 @node Hitachi Special
1984 @subsubsection Special @value{GDBN} commands for Hitachi micros
1986 Some @value{GDBN} commands are available only on the H8/300 or the
1987 H8/500 configurations:
1991 @kindex show machine
1992 @item set machine h8300
1993 @itemx set machine h8300h
1994 Condition @value{GDBN} for one of the two variants of the H8/300
1995 architecture with @samp{set machine}. You can use @samp{show machine}
1996 to check which variant is currently in effect.
1998 @kindex set memory @var{mod}
1999 @cindex memory models, H8/500
2000 @item set memory @var{mod}
2002 Specify which H8/500 memory model (@var{mod}) you are using with
2003 @samp{set memory}; check which memory model is in effect with @samp{show
2004 memory}. The accepted values for @var{mod} are @code{small},
2005 @code{big}, @code{medium}, and @code{compact}.
2009 @subsection @value{GDBN} and remote MIPS boards
2012 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
2013 MIPS board attached to a serial line. This is available when
2014 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
2017 Use these @value{GDBN} commands to specify the connection to your target board:
2020 @item target mips @var{port}
2021 @kindex target mips @var{port}
2022 To run a program on the board, start up @code{@value{GDBP}} with the
2023 name of your program as the argument. To connect to the board, use the
2024 command @samp{target mips @var{port}}, where @var{port} is the name of
2025 the serial port connected to the board. If the program has not already
2026 been downloaded to the board, you may use the @code{load} command to
2027 download it. You can then use all the usual @value{GDBN} commands.
2029 For example, this sequence connects to the target board through a serial
2030 port, and loads and runs a program called @var{prog} through the
2034 host$ @value{GDBP} @var{prog}
2035 GDB is free software and @dots{}
2036 (gdb) target mips /dev/ttyb
2037 (gdb) load @var{prog}
2041 @item target mips @var{hostname}:@var{portnumber}
2042 On some @value{GDBN} host configurations, you can specify a TCP
2043 connection (for instance, to a serial line managed by a terminal
2044 concentrator) instead of a serial port, using the syntax
2045 @samp{@var{hostname}:@var{portnumber}}.
2047 @item target pmon @var{port}
2048 @kindex target pmon @var{port}
2050 @item target ddb @var{port}
2051 @kindex target ddb @var{port}
2053 @item target lsi @var{port}
2054 @kindex target lsi @var{port}
2060 @value{GDBN} also supports these special commands for MIPS targets:
2063 @item set processor @var{args}
2064 @itemx show processor
2065 @kindex set processor @var{args}
2066 @kindex show processor
2067 Use the @code{set processor} command to set the type of MIPS
2068 processor when you want to access processor-type-specific registers.
2069 For example, @code{set processor @var{r3041}} tells @value{GDBN}
2070 to use the CPO registers appropriate for the 3041 chip.
2071 Use the @code{show processor} command to see what MIPS processor @value{GDBN}
2072 is using. Use the @code{info reg} command to see what registers
2073 @value{GDBN} is using.
2075 @item set mipsfpu double
2076 @itemx set mipsfpu single
2077 @itemx set mipsfpu none
2080 @kindex show mipsfpu
2081 @cindex MIPS remote floating point
2082 @cindex floating point, MIPS remote
2083 If your target board does not support the MIPS floating point
2084 coprocessor, you should use the command @samp{set mipsfpu none} (if you
2085 need this, you may wish to put the command in your @value{GDBINIT}
2086 file). This tells @value{GDBN} how to find the return value of
2087 functions which return floating point values. It also allows
2088 @value{GDBN} to avoid saving the floating point registers when calling
2089 functions on the board. If you are using a floating point coprocessor
2090 with only single precision floating point support, as on the @sc{r4650}
2091 processor, use the command @samp{set mipsfpu single}. The default
2092 double precision floating point coprocessor may be selected using
2093 @samp{set mipsfpu double}.
2095 In previous versions the only choices were double precision or no
2096 floating point, so @samp{set mipsfpu on} will select double precision
2097 and @samp{set mipsfpu off} will select no floating point.
2099 As usual, you can inquire about the @code{mipsfpu} variable with
2100 @samp{show mipsfpu}.
2102 @item set remotedebug @var{n}
2103 @itemx show remotedebug
2104 @kindex set remotedebug
2105 @kindex show remotedebug
2106 @cindex @code{remotedebug}, MIPS protocol
2107 @cindex MIPS @code{remotedebug} protocol
2108 @c FIXME! For this to be useful, you must know something about the MIPS
2109 @c FIXME...protocol. Where is it described?
2110 You can see some debugging information about communications with the board
2111 by setting the @code{remotedebug} variable. If you set it to @code{1} using
2112 @samp{set remotedebug 1}, every packet is displayed. If you set it
2113 to @code{2}, every character is displayed. You can check the current value
2114 at any time with the command @samp{show remotedebug}.
2116 @item set timeout @var{seconds}
2117 @itemx set retransmit-timeout @var{seconds}
2119 @itemx show retransmit-timeout
2120 @cindex @code{timeout}, MIPS protocol
2121 @cindex @code{retransmit-timeout}, MIPS protocol
2123 @kindex show timeout
2124 @kindex set retransmit-timeout
2125 @kindex show retransmit-timeout
2126 You can control the timeout used while waiting for a packet, in the MIPS
2127 remote protocol, with the @code{set timeout @var{seconds}} command. The
2128 default is 5 seconds. Similarly, you can control the timeout used while
2129 waiting for an acknowledgement of a packet with the @code{set
2130 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
2131 You can inspect both values with @code{show timeout} and @code{show
2132 retransmit-timeout}. (These commands are @emph{only} available when
2133 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
2135 The timeout set by @code{set timeout} does not apply when @value{GDBN}
2136 is waiting for your program to stop. In that case, @value{GDBN} waits
2137 forever because it has no way of knowing how long the program is going
2138 to run before stopping.
2142 @subsection Simulated CPU target
2145 @cindex simulator, Z8000
2146 @cindex Z8000 simulator
2147 @cindex simulator, H8/300 or H8/500
2148 @cindex H8/300 or H8/500 simulator
2149 @cindex simulator, Hitachi SH
2150 @cindex Hitachi SH simulator
2151 @cindex CPU simulator
2152 For some configurations, @value{GDBN} includes a CPU simulator that you
2153 can use instead of a hardware CPU to debug your programs.
2154 Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300,
2155 H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
2158 @cindex simulator, Z8000
2159 @cindex Zilog Z8000 simulator
2160 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
2163 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
2164 unsegmented variant of the Z8000 architecture) or the Z8001 (the
2165 segmented variant). The simulator recognizes which architecture is
2166 appropriate by inspecting the object code.
2169 @item target sim @var{args}
2172 Debug programs on a simulated CPU. If the simulator supports setup
2173 options, specify them via @var{args}.
2177 After specifying this target, you can debug programs for the simulated
2178 CPU in the same style as programs for your host computer; use the
2179 @code{file} command to load a new program image, the @code{run} command
2180 to run your program, and so on.
2182 As well as making available all the usual machine registers (see
2183 @code{info reg}), the Z8000 simulator provides three additional items
2184 of information as specially named registers:
2188 Counts clock-ticks in the simulator.
2191 Counts instructions run in the simulator.
2194 Execution time in 60ths of a second.
2197 You can refer to these values in @value{GDBN} expressions with the usual
2198 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
2199 conditional breakpoint that suspends only after at least 5000
2200 simulated clock ticks.
2202 @c need to add much more detail about sims!