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} or @code{OK}
775 The @var{OUTPUT} is the hex encoded output from the command. @code{OK}
776 is returned when the @var{OUTPUT} would have been empty. The target may
777 also respond with a number of intermediate @code{O}@var{OUTPUT} console
783 When @samp{q}@samp{Rcmd} is not recognized.
785 @item general set @emph{(optional)}
786 @tab @code{Q}@var{var}@code{=}@var{val}
788 Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
791 @item reset @emph{(optional)}
793 @tab reset -- see sparc stub.
795 @item remote restart @emph{(optional)}
796 @tab @code{R}@var{XX}
798 Restart the remote server. @var{XX} while needed has no clear
801 @item step @emph{(optional)}
802 @tab @code{s}@var{addr}
804 @var{addr} is address to resume. If @var{addr} is omitted, resume at
810 @item step with signal @emph{(optional)}
811 @tab @code{S}@var{sig}@code{;}@var{addr}
813 Like @samp{C} but step not continue.
818 @item search @emph{(optional)}
819 @tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
821 Search backwards starting at address @var{addr} for a match with pattern
822 @var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
823 bytes. @var{addr} must be at least 3 digits.
825 @item thread alive @emph{(optional)}
826 @tab @code{T}@var{XX}
827 @tab Find out if the thread XX is alive.
830 @tab thread is still alive
832 @tab reply @code{E}@var{NN}
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
861 @tab Reserved for future use
863 @item write mem (binary) @emph{(optional)}
864 @tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
866 @var{addr} is address, @var{length} is number of bytes, @var{XX...} is
872 @tab reply @code{E}@var{NN}
877 @tab Reserved for future use
881 @tab Reserved for future use
883 @item remove break or watchpoint @strong{(draft)} @emph{(optional)}
884 @tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
888 @item insert break or watchpoint @strong{(draft)} @emph{(optional)}
889 @tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
891 @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
892 breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
893 @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
894 bytes. For a software breakpoint, @var{length} specifies the size of
895 the instruction to be patched. For hardware breakpoints and watchpoints
896 @var{length} specifies the memory region to be monitored.
898 @tab reply @code{E}@var{NN}
905 @tab If not supported.
909 @tab Reserved for future use
913 In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets,
914 there is no immediate response. The reply, described below, comes when
917 @multitable @columnfractions .4 .6
919 @item @code{S}@var{AA}
920 @tab @var{AA} is the signal number
922 @item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
924 @var{AA} = two hex digit signal number; @var{n...} = register number
925 (hex), @var{r...} = target byte ordered register contents, size defined
926 by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
927 thread process ID, this is a hex integer; @var{n...} = other string not
928 starting with valid hex digit. @value{GDBN} should ignore this
929 @var{n...}, @var{r...} pair and go on to the next. This way we can
932 @item @code{W}@var{AA}
934 The process exited, and @var{AA} is the exit status. This is only
935 applicable for certains sorts of targets.
937 @item @code{X}@var{AA}
939 The process terminated with signal @var{AA}.
941 @item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)}
943 @var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
944 @var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss
945 section. @emph{Note: only used by Cisco Systems targets. The difference
946 between this reply and the "qOffsets" query is that the 'N' packet may
947 arrive spontaneously whereas the 'qOffsets' is a query initiated by the
950 @item @code{O}@var{XX...}
952 @var{XX...} is hex encoding of ASCII data. This can happen at any time
953 while the program is running and the debugger should continue to wait
958 Example sequence of a target being re-started. Notice how the restart
959 does not get any direct output:
964 @emph{target restarts}
967 -> @code{T001:1234123412341234}
971 Example sequence of a target being stepped by a single instruction:
979 -> @code{T001:1234123412341234}
987 @kindex set remotedebug
988 @kindex show remotedebug
989 @cindex packets, reporting on stdout
990 @cindex serial connections, debugging
991 If you have trouble with the serial connection, you can use the command
992 @code{set remotedebug}. This makes @value{GDBN} report on all packets sent
993 back and forth across the serial line to the remote machine. The
994 packet-debugging information is printed on the @value{GDBN} standard output
995 stream. @code{set remotedebug off} turns it off, and @code{show
996 remotedebug} shows you its current state.
999 @subsubsection Using the @code{gdbserver} program
1002 @cindex remote connection without stubs
1003 @code{gdbserver} is a control program for Unix-like systems, which
1004 allows you to connect your program with a remote @value{GDBN} via
1005 @code{target remote}---but without linking in the usual debugging stub.
1007 @code{gdbserver} is not a complete replacement for the debugging stubs,
1008 because it requires essentially the same operating-system facilities
1009 that @value{GDBN} itself does. In fact, a system that can run
1010 @code{gdbserver} to connect to a remote @value{GDBN} could also run
1011 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
1012 because it is a much smaller program than @value{GDBN} itself. It is
1013 also easier to port than all of @value{GDBN}, so you may be able to get
1014 started more quickly on a new system by using @code{gdbserver}.
1015 Finally, if you develop code for real-time systems, you may find that
1016 the tradeoffs involved in real-time operation make it more convenient to
1017 do as much development work as possible on another system, for example
1018 by cross-compiling. You can use @code{gdbserver} to make a similar
1019 choice for debugging.
1021 @value{GDBN} and @code{gdbserver} communicate via either a serial line
1022 or a TCP connection, using the standard @value{GDBN} remote serial
1026 @item On the target machine,
1027 you need to have a copy of the program you want to debug.
1028 @code{gdbserver} does not need your program's symbol table, so you can
1029 strip the program if necessary to save space. @value{GDBN} on the host
1030 system does all the symbol handling.
1032 To use the server, you must tell it how to communicate with @value{GDBN};
1033 the name of your program; and the arguments for your program. The
1037 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
1040 @var{comm} is either a device name (to use a serial line) or a TCP
1041 hostname and portnumber. For example, to debug Emacs with the argument
1042 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
1046 target> gdbserver /dev/com1 emacs foo.txt
1049 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
1052 To use a TCP connection instead of a serial line:
1055 target> gdbserver host:2345 emacs foo.txt
1058 The only difference from the previous example is the first argument,
1059 specifying that you are communicating with the host @value{GDBN} via
1060 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
1061 expect a TCP connection from machine @samp{host} to local TCP port 2345.
1062 (Currently, the @samp{host} part is ignored.) You can choose any number
1063 you want for the port number as long as it does not conflict with any
1064 TCP ports already in use on the target system (for example, @code{23} is
1065 reserved for @code{telnet}).@footnote{If you choose a port number that
1066 conflicts with another service, @code{gdbserver} prints an error message
1067 and exits.} You must use the same port number with the host @value{GDBN}
1068 @code{target remote} command.
1070 @item On the @value{GDBN} host machine,
1071 you need an unstripped copy of your program, since @value{GDBN} needs
1072 symbols and debugging information. Start up @value{GDBN} as usual,
1073 using the name of the local copy of your program as the first argument.
1074 (You may also need the @w{@samp{--baud}} option if the serial line is
1075 running at anything other than 9600 bps.) After that, use @code{target
1076 remote} to establish communications with @code{gdbserver}. Its argument
1077 is either a device name (usually a serial device, like
1078 @file{/dev/ttyb}), or a TCP port descriptor in the form
1079 @code{@var{host}:@var{PORT}}. For example:
1082 (@value{GDBP}) target remote /dev/ttyb
1086 communicates with the server via serial line @file{/dev/ttyb}, and
1089 (@value{GDBP}) target remote the-target:2345
1093 communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
1094 For TCP connections, you must start up @code{gdbserver} prior to using
1095 the @code{target remote} command. Otherwise you may get an error whose
1096 text depends on the host system, but which usually looks something like
1097 @samp{Connection refused}.
1101 @subsubsection Using the @code{gdbserve.nlm} program
1103 @kindex gdbserve.nlm
1104 @code{gdbserve.nlm} is a control program for NetWare systems, which
1105 allows you to connect your program with a remote @value{GDBN} via
1106 @code{target remote}.
1108 @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
1109 using the standard @value{GDBN} remote serial protocol.
1112 @item On the target machine,
1113 you need to have a copy of the program you want to debug.
1114 @code{gdbserve.nlm} does not need your program's symbol table, so you
1115 can strip the program if necessary to save space. @value{GDBN} on the
1116 host system does all the symbol handling.
1118 To use the server, you must tell it how to communicate with
1119 @value{GDBN}; the name of your program; and the arguments for your
1120 program. The syntax is:
1123 load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
1124 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
1127 @var{board} and @var{port} specify the serial line; @var{baud} specifies
1128 the baud rate used by the connection. @var{port} and @var{node} default
1129 to 0, @var{baud} defaults to 9600 bps.
1131 For example, to debug Emacs with the argument @samp{foo.txt}and
1132 communicate with @value{GDBN} over serial port number 2 or board 1
1133 using a 19200 bps connection:
1136 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
1139 @item On the @value{GDBN} host machine,
1140 you need an unstripped copy of your program, since @value{GDBN} needs
1141 symbols and debugging information. Start up @value{GDBN} as usual,
1142 using the name of the local copy of your program as the first argument.
1143 (You may also need the @w{@samp{--baud}} option if the serial line is
1144 running at anything other than 9600 bps. After that, use @code{target
1145 remote} to establish communications with @code{gdbserve.nlm}. Its
1146 argument is a device name (usually a serial device, like
1147 @file{/dev/ttyb}). For example:
1150 (@value{GDBP}) target remote /dev/ttyb
1154 communications with the server via serial line @file{/dev/ttyb}.
1157 @node i960-Nindy Remote
1158 @subsection @value{GDBN} with a remote i960 (Nindy)
1162 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
1163 @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
1164 tell @value{GDBN} how to connect to the 960 in several ways:
1168 Through command line options specifying serial port, version of the
1169 Nindy protocol, and communications speed;
1172 By responding to a prompt on startup;
1175 By using the @code{target} command at any point during your @value{GDBN}
1176 session. @xref{Target Commands, ,Commands for managing targets}.
1181 * Nindy Startup:: Startup with Nindy
1182 * Nindy Options:: Options for Nindy
1183 * Nindy Reset:: Nindy reset command
1187 @subsubsection Startup with Nindy
1189 If you simply start @code{@value{GDBP}} without using any command-line
1190 options, you are prompted for what serial port to use, @emph{before} you
1191 reach the ordinary @value{GDBN} prompt:
1194 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
1198 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
1199 identifies the serial port you want to use. You can, if you choose,
1200 simply start up with no Nindy connection by responding to the prompt
1201 with an empty line. If you do this and later wish to attach to Nindy,
1202 use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
1205 @subsubsection Options for Nindy
1207 These are the startup options for beginning your @value{GDBN} session with a
1208 Nindy-960 board attached:
1212 Specify the serial port name of a serial interface to be used to connect
1213 to the target system. This option is only available when @value{GDBN} is
1214 configured for the Intel 960 target architecture. You may specify
1215 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
1216 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
1217 suffix for a specific @code{tty} (e.g. @samp{-r a}).
1220 (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
1221 the ``old'' Nindy monitor protocol to connect to the target system.
1222 This option is only available when @value{GDBN} is configured for the Intel 960
1223 target architecture.
1226 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
1227 connect to a target system that expects the newer protocol, the connection
1228 fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
1229 attempts to reconnect at several different line speeds. You can abort
1230 this process with an interrupt.
1234 Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
1235 system, in an attempt to reset it, before connecting to a Nindy target.
1238 @emph{Warning:} Many target systems do not have the hardware that this
1239 requires; it only works with a few boards.
1243 The standard @samp{-b} option controls the line speed used on the serial
1248 @subsubsection Nindy reset command
1253 For a Nindy target, this command sends a ``break'' to the remote target
1254 system; this is only useful if the target has been equipped with a
1255 circuit to perform a hard reset (or some other interesting action) when
1256 a break is detected.
1261 @subsection The UDI protocol for AMD29K
1264 @cindex AMD29K via UDI
1265 @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
1266 protocol for debugging the a29k processor family. To use this
1267 configuration with AMD targets running the MiniMON monitor, you need the
1268 program @code{MONTIP}, available from AMD at no charge. You can also
1269 use @value{GDBN} with the UDI-conformant a29k simulator program
1270 @code{ISSTIP}, also available from AMD.
1273 @item target udi @var{keyword}
1275 Select the UDI interface to a remote a29k board or simulator, where
1276 @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
1277 This file contains keyword entries which specify parameters used to
1278 connect to a29k targets. If the @file{udi_soc} file is not in your
1279 working directory, you must set the environment variable @samp{UDICONF}
1284 @subsection The EBMON protocol for AMD29K
1287 @cindex running 29K programs
1289 AMD distributes a 29K development board meant to fit in a PC, together
1290 with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
1291 term, this development system is called the ``EB29K''. To use
1292 @value{GDBN} from a Unix system to run programs on the EB29K board, you
1293 must first connect a serial cable between the PC (which hosts the EB29K
1294 board) and a serial port on the Unix system. In the following, we
1295 assume you've hooked the cable between the PC's @file{COM1} port and
1296 @file{/dev/ttya} on the Unix system.
1299 * Comms (EB29K):: Communications setup
1300 * gdb-EB29K:: EB29K cross-debugging
1301 * Remote Log:: Remote log
1305 @subsubsection Communications setup
1307 The next step is to set up the PC's port, by doing something like this
1311 C:\> MODE com1:9600,n,8,1,none
1315 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
1316 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
1317 you must match the communications parameters when establishing the Unix
1318 end of the connection as well.
1319 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
1320 @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
1322 To give control of the PC to the Unix side of the serial line, type
1323 the following at the DOS console:
1330 (Later, if you wish to return control to the DOS console, you can use
1331 the command @code{CTTY con}---but you must send it over the device that
1332 had control, in our example over the @file{COM1} serial line).
1334 From the Unix host, use a communications program such as @code{tip} or
1335 @code{cu} to communicate with the PC; for example,
1338 cu -s 9600 -l /dev/ttya
1342 The @code{cu} options shown specify, respectively, the linespeed and the
1343 serial port to use. If you use @code{tip} instead, your command line
1344 may look something like the following:
1351 Your system may require a different name where we show
1352 @file{/dev/ttya} as the argument to @code{tip}. The communications
1353 parameters, including which port to use, are associated with the
1354 @code{tip} argument in the ``remote'' descriptions file---normally the
1355 system table @file{/etc/remote}.
1356 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
1357 @c the DOS side's comms setup? cu can support -o (odd
1358 @c parity), -e (even parity)---apparently no settings for no parity or
1359 @c for character size. Taken from stty maybe...? John points out tip
1360 @c can set these as internal variables, eg ~s parity=none; man stty
1361 @c suggests that it *might* work to stty these options with stdin or
1362 @c stdout redirected... ---doc@cygnus.com, 25feb91
1365 Using the @code{tip} or @code{cu} connection, change the DOS working
1366 directory to the directory containing a copy of your 29K program, then
1367 start the PC program @code{EBMON} (an EB29K control program supplied
1368 with your board by AMD). You should see an initial display from
1369 @code{EBMON} similar to the one that follows, ending with the
1370 @code{EBMON} prompt @samp{#}---
1375 G:\> CD \usr\joe\work29k
1377 G:\USR\JOE\WORK29K> EBMON
1378 Am29000 PC Coprocessor Board Monitor, version 3.0-18
1379 Copyright 1990 Advanced Micro Devices, Inc.
1380 Written by Gibbons and Associates, Inc.
1382 Enter '?' or 'H' for help
1384 PC Coprocessor Type = EB29K
1386 Memory Base = 0xd0000
1388 Data Memory Size = 2048KB
1389 Available I-RAM Range = 0x8000 to 0x1fffff
1390 Available D-RAM Range = 0x80002000 to 0x801fffff
1393 Register Stack Size = 0x800
1394 Memory Stack Size = 0x1800
1397 Am29027 Available = No
1398 Byte Write Available = Yes
1403 Then exit the @code{cu} or @code{tip} program (done in the example by
1404 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
1405 running, ready for @value{GDBN} to take over.
1407 For this example, we've assumed what is probably the most convenient
1408 way to make sure the same 29K program is on both the PC and the Unix
1409 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
1410 PC as a file system on the Unix host. If you do not have PC/NFS or
1411 something similar connecting the two systems, you must arrange some
1412 other way---perhaps floppy-disk transfer---of getting the 29K program
1413 from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
1417 @subsubsection EB29K cross-debugging
1419 Finally, @code{cd} to the directory containing an image of your 29K
1420 program on the Unix system, and start @value{GDBN}---specifying as argument the
1421 name of your 29K program:
1429 Now you can use the @code{target} command:
1432 target amd-eb /dev/ttya 9600 MYFOO
1433 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
1434 @c emphasize that this is the name as seen by DOS (since I think DOS is
1435 @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
1439 In this example, we've assumed your program is in a file called
1440 @file{myfoo}. Note that the filename given as the last argument to
1441 @code{target amd-eb} should be the name of the program as it appears to DOS.
1442 In our example this is simply @code{MYFOO}, but in general it can include
1443 a DOS path, and depending on your transfer mechanism may not resemble
1444 the name on the Unix side.
1446 At this point, you can set any breakpoints you wish; when you are ready
1447 to see your program run on the 29K board, use the @value{GDBN} command
1450 To stop debugging the remote program, use the @value{GDBN} @code{detach}
1453 To return control of the PC to its console, use @code{tip} or @code{cu}
1454 once again, after your @value{GDBN} session has concluded, to attach to
1455 @code{EBMON}. You can then type the command @code{q} to shut down
1456 @code{EBMON}, returning control to the DOS command-line interpreter.
1457 Type @code{CTTY con} to return command input to the main DOS console,
1458 and type @kbd{~.} to leave @code{tip} or @code{cu}.
1461 @subsubsection Remote log
1463 @cindex log file for EB29K
1465 The @code{target amd-eb} command creates a file @file{eb.log} in the
1466 current working directory, to help debug problems with the connection.
1467 @file{eb.log} records all the output from @code{EBMON}, including echoes
1468 of the commands sent to it. Running @samp{tail -f} on this file in
1469 another window often helps to understand trouble with @code{EBMON}, or
1470 unexpected events on the PC side of the connection.
1473 @subsection @value{GDBN} with a Tandem ST2000
1475 To connect your ST2000 to the host system, see the manufacturer's
1476 manual. Once the ST2000 is physically attached, you can run:
1479 target st2000 @var{dev} @var{speed}
1483 to establish it as your debugging environment. @var{dev} is normally
1484 the name of a serial device, such as @file{/dev/ttya}, connected to the
1485 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
1486 connection (for example, to a serial line attached via a terminal
1487 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
1489 The @code{load} and @code{attach} commands are @emph{not} defined for
1490 this target; you must load your program into the ST2000 as you normally
1491 would for standalone operation. @value{GDBN} reads debugging information
1492 (such as symbols) from a separate, debugging version of the program
1493 available on your host computer.
1494 @c FIXME!! This is terribly vague; what little content is here is
1495 @c basically hearsay.
1497 @cindex ST2000 auxiliary commands
1498 These auxiliary @value{GDBN} commands are available to help you with the ST2000
1502 @item st2000 @var{command}
1503 @kindex st2000 @var{cmd}
1504 @cindex STDBUG commands (ST2000)
1505 @cindex commands to STDBUG (ST2000)
1506 Send a @var{command} to the STDBUG monitor. See the manufacturer's
1507 manual for available commands.
1510 @cindex connect (to STDBUG)
1511 Connect the controlling terminal to the STDBUG command monitor. When
1512 you are done interacting with STDBUG, typing either of two character
1513 sequences gets you back to the @value{GDBN} command prompt:
1514 @kbd{@key{RET}~.} (Return, followed by tilde and period) or
1515 @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
1518 @node VxWorks Remote
1519 @subsection @value{GDBN} and VxWorks
1523 @value{GDBN} enables developers to spawn and debug tasks running on networked
1524 VxWorks targets from a Unix host. Already-running tasks spawned from
1525 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
1526 both the Unix host and on the VxWorks target. The program
1527 @code{gdb} is installed and executed on the Unix host. (It may be
1528 installed with the name @code{vxgdb}, to distinguish it from a
1529 @value{GDBN} for debugging programs on the host itself.)
1532 @item VxWorks-timeout @var{args}
1533 @kindex vxworks-timeout
1534 All VxWorks-based targets now support the option @code{vxworks-timeout}.
1535 This option is set by the user, and @var{args} represents the number of
1536 seconds @value{GDBN} waits for responses to rpc's. You might use this if
1537 your VxWorks target is a slow software simulator or is on the far side
1538 of a thin network line.
1541 The following information on connecting to VxWorks was current when
1542 this manual was produced; newer releases of VxWorks may use revised
1546 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
1547 to include the remote debugging interface routines in the VxWorks
1548 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
1549 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
1550 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
1551 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1552 information on configuring and remaking VxWorks, see the manufacturer's
1554 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
1556 Once you have included @file{rdb.a} in your VxWorks system image and set
1557 your Unix execution search path to find @value{GDBN}, you are ready to
1558 run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb},
1559 depending on your installation).
1561 @value{GDBN} comes up showing the prompt:
1568 * VxWorks Connection:: Connecting to VxWorks
1569 * VxWorks Download:: VxWorks download
1570 * VxWorks Attach:: Running tasks
1573 @node VxWorks Connection
1574 @subsubsection Connecting to VxWorks
1576 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
1577 network. To connect to a target whose host name is ``@code{tt}'', type:
1580 (vxgdb) target vxworks tt
1584 @value{GDBN} displays messages like these:
1587 Attaching remote machine across net...
1592 @value{GDBN} then attempts to read the symbol tables of any object modules
1593 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
1594 these files by searching the directories listed in the command search
1595 path (@pxref{Environment, ,Your program's environment}); if it fails
1596 to find an object file, it displays a message such as:
1599 prog.o: No such file or directory.
1602 When this happens, add the appropriate directory to the search path with
1603 the @value{GDBN} command @code{path}, and execute the @code{target}
1606 @node VxWorks Download
1607 @subsubsection VxWorks download
1609 @cindex download to VxWorks
1610 If you have connected to the VxWorks target and you want to debug an
1611 object that has not yet been loaded, you can use the @value{GDBN}
1612 @code{load} command to download a file from Unix to VxWorks
1613 incrementally. The object file given as an argument to the @code{load}
1614 command is actually opened twice: first by the VxWorks target in order
1615 to download the code, then by @value{GDBN} in order to read the symbol
1616 table. This can lead to problems if the current working directories on
1617 the two systems differ. If both systems have NFS mounted the same
1618 filesystems, you can avoid these problems by using absolute paths.
1619 Otherwise, it is simplest to set the working directory on both systems
1620 to the directory in which the object file resides, and then to reference
1621 the file by its name, without any path. For instance, a program
1622 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
1623 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
1624 program, type this on VxWorks:
1627 -> cd "@var{vxpath}/vw/demo/rdb"
1630 Then, in @value{GDBN}, type:
1633 (vxgdb) cd @var{hostpath}/vw/demo/rdb
1637 @value{GDBN} displays a response similar to this:
1640 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1643 You can also use the @code{load} command to reload an object module
1644 after editing and recompiling the corresponding source file. Note that
1645 this makes @value{GDBN} delete all currently-defined breakpoints,
1646 auto-displays, and convenience variables, and to clear the value
1647 history. (This is necessary in order to preserve the integrity of
1648 debugger data structures that reference the target system's symbol
1651 @node VxWorks Attach
1652 @subsubsection Running tasks
1654 @cindex running VxWorks tasks
1655 You can also attach to an existing task using the @code{attach} command as
1659 (vxgdb) attach @var{task}
1663 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1664 or suspended when you attach to it. Running tasks are suspended at
1665 the time of attachment.
1667 @node Sparclet Remote
1668 @subsection @value{GDBN} and Sparclet
1671 @value{GDBN} enables developers to debug tasks running on
1672 Sparclet targets from a Unix host.
1673 @value{GDBN} uses code that runs on
1674 both the Unix host and on the Sparclet target. The program
1675 @code{gdb} is installed and executed on the Unix host.
1678 @item timeout @var{args}
1679 @kindex remotetimeout
1680 @value{GDBN} now supports the option @code{remotetimeout}.
1681 This option is set by the user, and @var{args} represents the number of
1682 seconds @value{GDBN} waits for responses.
1686 When compiling for debugging, include the options "-g" to get debug
1687 information and "-Ttext" to relocate the program to where you wish to
1688 load it on the target. You may also want to add the options "-n" or
1689 "-N" in order to reduce the size of the sections.
1692 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
1695 You can use objdump to verify that the addresses are what you intended.
1698 sparclet-aout-objdump --headers --syms prog
1703 your Unix execution search path to find @value{GDBN}, you are ready to
1704 run @value{GDBN}. From your Unix host, run @code{gdb}
1705 (or @code{sparclet-aout-gdb}, depending on your installation).
1707 @value{GDBN} comes up showing the prompt:
1714 * Sparclet File:: Setting the file to debug
1715 * Sparclet Connection:: Connecting to Sparclet
1716 * Sparclet Download:: Sparclet download
1717 * Sparclet Execution:: Running and debugging
1721 @subsubsection Setting file to debug
1723 The @value{GDBN} command @code{file} lets you choose with program to debug.
1730 @value{GDBN} then attempts to read the symbol table of @file{prog}.
1731 @value{GDBN} locates
1732 the file by searching the directories listed in the command search
1734 If the file was compiled with debug information (option "-g"), source
1735 files will be searched as well.
1736 @value{GDBN} locates
1737 the source files by searching the directories listed in the directory search
1738 path (@pxref{Environment, ,Your program's environment}).
1740 to find a file, it displays a message such as:
1743 prog: No such file or directory.
1746 When this happens, add the appropriate directories to the search paths with
1747 the @value{GDBN} commands @code{path} and @code{dir}, and execute the
1748 @code{target} command again.
1750 @node Sparclet Connection
1751 @subsubsection Connecting to Sparclet
1753 The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
1754 To connect to a target on serial port ``@code{ttya}'', type:
1757 (gdbslet) target sparclet /dev/ttya
1758 Remote target sparclet connected to /dev/ttya
1759 main () at ../prog.c:3
1763 @value{GDBN} displays messages like these:
1769 @node Sparclet Download
1770 @subsubsection Sparclet download
1772 @cindex download to Sparclet
1773 Once connected to the Sparclet target,
1774 you can use the @value{GDBN}
1775 @code{load} command to download the file from the host to the target.
1776 The file name and load offset should be given as arguments to the @code{load}
1778 Since the file format is aout, the program must be loaded to the starting
1779 address. You can use objdump to find out what this value is. The load
1780 offset is an offset which is added to the VMA (virtual memory address)
1781 of each of the file's sections.
1782 For instance, if the program
1783 @file{prog} was linked to text address 0x1201000, with data at 0x12010160
1784 and bss at 0x12010170, in @value{GDBN}, type:
1787 (gdbslet) load prog 0x12010000
1788 Loading section .text, size 0xdb0 vma 0x12010000
1791 If the code is loaded at a different address then what the program was linked
1792 to, you may need to use the @code{section} and @code{add-symbol-file} commands
1793 to tell @value{GDBN} where to map the symbol table.
1795 @node Sparclet Execution
1796 @subsubsection Running and debugging
1798 @cindex running and debugging Sparclet programs
1799 You can now begin debugging the task using @value{GDBN}'s execution control
1800 commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
1801 manual for the list of commands.
1805 Breakpoint 1 at 0x12010000: file prog.c, line 3.
1807 Starting program: prog
1808 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
1811 4 char *execarg = "hello!";
1815 @node Hitachi Remote
1816 @subsection @value{GDBN} and Hitachi microprocessors
1817 @value{GDBN} needs to know these things to talk to your
1818 Hitachi SH, H8/300, or H8/500:
1822 that you want to use @samp{target hms}, the remote debugging interface
1823 for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
1824 emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
1825 the default when GDB is configured specifically for the Hitachi SH,
1829 what serial device connects your host to your Hitachi board (the first
1830 serial device available on your host is the default).
1833 what speed to use over the serial device.
1837 * Hitachi Boards:: Connecting to Hitachi boards.
1838 * Hitachi ICE:: Using the E7000 In-Circuit Emulator.
1839 * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
1842 @node Hitachi Boards
1843 @subsubsection Connecting to Hitachi boards
1845 @c only for Unix hosts
1847 @cindex serial device, Hitachi micros
1848 Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
1849 need to explicitly set the serial device. The default @var{port} is the
1850 first available port on your host. This is only necessary on Unix
1851 hosts, where it is typically something like @file{/dev/ttya}.
1854 @cindex serial line speed, Hitachi micros
1855 @code{@value{GDBP}} has another special command to set the communications
1856 speed: @samp{speed @var{bps}}. This command also is only used from Unix
1857 hosts; on DOS hosts, set the line speed as usual from outside GDB with
1858 the DOS @kbd{mode} command (for instance, @w{@samp{mode
1859 com2:9600,n,8,1,p}} for a 9600 bps connection).
1861 The @samp{device} and @samp{speed} commands are available only when you
1862 use a Unix host to debug your Hitachi microprocessor programs. If you
1864 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
1865 called @code{asynctsr} to communicate with the development board
1866 through a PC serial port. You must also use the DOS @code{mode} command
1867 to set up the serial port on the DOS side.
1869 The following sample session illustrates the steps needed to start a
1870 program under @value{GDBN} control on an H8/300. The example uses a
1871 sample H8/300 program called @file{t.x}. The procedure is the same for
1872 the Hitachi SH and the H8/500.
1874 First hook up your development board. In this example, we use a
1875 board attached to serial port @code{COM2}; if you use a different serial
1876 port, substitute its name in the argument of the @code{mode} command.
1877 When you call @code{asynctsr}, the auxiliary comms program used by the
1878 degugger, you give it just the numeric part of the serial port's name;
1879 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
1883 C:\H8300\TEST> asynctsr 2
1884 C:\H8300\TEST> mode com2:9600,n,8,1,p
1886 Resident portion of MODE loaded
1888 COM2: 9600, n, 8, 1, p
1893 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
1894 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
1895 disable it, or even boot without it, to use @code{asynctsr} to control
1896 your development board.
1900 Now that serial communications are set up, and the development board is
1901 connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
1902 the name of your program as the argument. @code{@value{GDBP}} prompts
1903 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
1904 commands to begin your debugging session: @samp{target hms} to specify
1905 cross-debugging to the Hitachi board, and the @code{load} command to
1906 download your program to the board. @code{load} displays the names of
1907 the program's sections, and a @samp{*} for each 2K of data downloaded.
1908 (If you want to refresh @value{GDBN} data on symbols or on the
1909 executable file without downloading, use the @value{GDBN} commands
1910 @code{file} or @code{symbol-file}. These commands, and @code{load}
1911 itself, are described in @ref{Files,,Commands to specify files}.)
1914 (eg-C:\H8300\TEST) @value{GDBP} t.x
1915 GDB is free software and you are welcome to distribute copies
1916 of it under certain conditions; type "show copying" to see
1918 There is absolutely no warranty for GDB; type "show warranty"
1920 GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
1922 Connected to remote H8/300 HMS system.
1924 .text : 0x8000 .. 0xabde ***********
1925 .data : 0xabde .. 0xad30 *
1926 .stack : 0xf000 .. 0xf014 *
1929 At this point, you're ready to run or debug your program. From here on,
1930 you can use all the usual @value{GDBN} commands. The @code{break} command
1931 sets breakpoints; the @code{run} command starts your program;
1932 @code{print} or @code{x} display data; the @code{continue} command
1933 resumes execution after stopping at a breakpoint. You can use the
1934 @code{help} command at any time to find out more about @value{GDBN} commands.
1936 Remember, however, that @emph{operating system} facilities aren't
1937 available on your development board; for example, if your program hangs,
1938 you can't send an interrupt---but you can press the @sc{reset} switch!
1940 Use the @sc{reset} button on the development board
1943 to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
1944 no way to pass an interrupt signal to the development board); and
1947 to return to the @value{GDBN} command prompt after your program finishes
1948 normally. The communications protocol provides no other way for @value{GDBN}
1949 to detect program completion.
1952 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
1953 development board as a ``normal exit'' of your program.
1956 @subsubsection Using the E7000 in-circuit emulator
1958 @kindex target e7000
1959 You can use the E7000 in-circuit emulator to develop code for either the
1960 Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
1961 e7000} command to connect @value{GDBN} to your E7000:
1964 @item target e7000 @var{port} @var{speed}
1965 Use this form if your E7000 is connected to a serial port. The
1966 @var{port} argument identifies what serial port to use (for example,
1967 @samp{com2}). The third argument is the line speed in bits per second
1968 (for example, @samp{9600}).
1970 @item target e7000 @var{hostname}
1971 If your E7000 is installed as a host on a TCP/IP network, you can just
1972 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
1975 @node Hitachi Special
1976 @subsubsection Special @value{GDBN} commands for Hitachi micros
1978 Some @value{GDBN} commands are available only on the H8/300 or the
1979 H8/500 configurations:
1983 @kindex show machine
1984 @item set machine h8300
1985 @itemx set machine h8300h
1986 Condition @value{GDBN} for one of the two variants of the H8/300
1987 architecture with @samp{set machine}. You can use @samp{show machine}
1988 to check which variant is currently in effect.
1990 @kindex set memory @var{mod}
1991 @cindex memory models, H8/500
1992 @item set memory @var{mod}
1994 Specify which H8/500 memory model (@var{mod}) you are using with
1995 @samp{set memory}; check which memory model is in effect with @samp{show
1996 memory}. The accepted values for @var{mod} are @code{small},
1997 @code{big}, @code{medium}, and @code{compact}.
2001 @subsection @value{GDBN} and remote MIPS boards
2004 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
2005 MIPS board attached to a serial line. This is available when
2006 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
2009 Use these @value{GDBN} commands to specify the connection to your target board:
2012 @item target mips @var{port}
2013 @kindex target mips @var{port}
2014 To run a program on the board, start up @code{@value{GDBP}} with the
2015 name of your program as the argument. To connect to the board, use the
2016 command @samp{target mips @var{port}}, where @var{port} is the name of
2017 the serial port connected to the board. If the program has not already
2018 been downloaded to the board, you may use the @code{load} command to
2019 download it. You can then use all the usual @value{GDBN} commands.
2021 For example, this sequence connects to the target board through a serial
2022 port, and loads and runs a program called @var{prog} through the
2026 host$ @value{GDBP} @var{prog}
2027 GDB is free software and @dots{}
2028 (gdb) target mips /dev/ttyb
2029 (gdb) load @var{prog}
2033 @item target mips @var{hostname}:@var{portnumber}
2034 On some @value{GDBN} host configurations, you can specify a TCP
2035 connection (for instance, to a serial line managed by a terminal
2036 concentrator) instead of a serial port, using the syntax
2037 @samp{@var{hostname}:@var{portnumber}}.
2039 @item target pmon @var{port}
2040 @kindex target pmon @var{port}
2042 @item target ddb @var{port}
2043 @kindex target ddb @var{port}
2045 @item target lsi @var{port}
2046 @kindex target lsi @var{port}
2052 @value{GDBN} also supports these special commands for MIPS targets:
2055 @item set processor @var{args}
2056 @itemx show processor
2057 @kindex set processor @var{args}
2058 @kindex show processor
2059 Use the @code{set processor} command to set the type of MIPS
2060 processor when you want to access processor-type-specific registers.
2061 For example, @code{set processor @var{r3041}} tells @value{GDBN}
2062 to use the CPO registers appropriate for the 3041 chip.
2063 Use the @code{show processor} command to see what MIPS processor @value{GDBN}
2064 is using. Use the @code{info reg} command to see what registers
2065 @value{GDBN} is using.
2067 @item set mipsfpu double
2068 @itemx set mipsfpu single
2069 @itemx set mipsfpu none
2072 @kindex show mipsfpu
2073 @cindex MIPS remote floating point
2074 @cindex floating point, MIPS remote
2075 If your target board does not support the MIPS floating point
2076 coprocessor, you should use the command @samp{set mipsfpu none} (if you
2077 need this, you may wish to put the command in your @value{GDBINIT}
2078 file). This tells @value{GDBN} how to find the return value of
2079 functions which return floating point values. It also allows
2080 @value{GDBN} to avoid saving the floating point registers when calling
2081 functions on the board. If you are using a floating point coprocessor
2082 with only single precision floating point support, as on the @sc{r4650}
2083 processor, use the command @samp{set mipsfpu single}. The default
2084 double precision floating point coprocessor may be selected using
2085 @samp{set mipsfpu double}.
2087 In previous versions the only choices were double precision or no
2088 floating point, so @samp{set mipsfpu on} will select double precision
2089 and @samp{set mipsfpu off} will select no floating point.
2091 As usual, you can inquire about the @code{mipsfpu} variable with
2092 @samp{show mipsfpu}.
2094 @item set remotedebug @var{n}
2095 @itemx show remotedebug
2096 @kindex set remotedebug
2097 @kindex show remotedebug
2098 @cindex @code{remotedebug}, MIPS protocol
2099 @cindex MIPS @code{remotedebug} protocol
2100 @c FIXME! For this to be useful, you must know something about the MIPS
2101 @c FIXME...protocol. Where is it described?
2102 You can see some debugging information about communications with the board
2103 by setting the @code{remotedebug} variable. If you set it to @code{1} using
2104 @samp{set remotedebug 1}, every packet is displayed. If you set it
2105 to @code{2}, every character is displayed. You can check the current value
2106 at any time with the command @samp{show remotedebug}.
2108 @item set timeout @var{seconds}
2109 @itemx set retransmit-timeout @var{seconds}
2111 @itemx show retransmit-timeout
2112 @cindex @code{timeout}, MIPS protocol
2113 @cindex @code{retransmit-timeout}, MIPS protocol
2115 @kindex show timeout
2116 @kindex set retransmit-timeout
2117 @kindex show retransmit-timeout
2118 You can control the timeout used while waiting for a packet, in the MIPS
2119 remote protocol, with the @code{set timeout @var{seconds}} command. The
2120 default is 5 seconds. Similarly, you can control the timeout used while
2121 waiting for an acknowledgement of a packet with the @code{set
2122 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
2123 You can inspect both values with @code{show timeout} and @code{show
2124 retransmit-timeout}. (These commands are @emph{only} available when
2125 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
2127 The timeout set by @code{set timeout} does not apply when @value{GDBN}
2128 is waiting for your program to stop. In that case, @value{GDBN} waits
2129 forever because it has no way of knowing how long the program is going
2130 to run before stopping.
2134 @subsection Simulated CPU target
2137 @cindex simulator, Z8000
2138 @cindex Z8000 simulator
2139 @cindex simulator, H8/300 or H8/500
2140 @cindex H8/300 or H8/500 simulator
2141 @cindex simulator, Hitachi SH
2142 @cindex Hitachi SH simulator
2143 @cindex CPU simulator
2144 For some configurations, @value{GDBN} includes a CPU simulator that you
2145 can use instead of a hardware CPU to debug your programs.
2146 Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300,
2147 H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
2150 @cindex simulator, Z8000
2151 @cindex Zilog Z8000 simulator
2152 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
2155 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
2156 unsegmented variant of the Z8000 architecture) or the Z8001 (the
2157 segmented variant). The simulator recognizes which architecture is
2158 appropriate by inspecting the object code.
2161 @item target sim @var{args}
2164 Debug programs on a simulated CPU. If the simulator supports setup
2165 options, specify them via @var{args}.
2169 After specifying this target, you can debug programs for the simulated
2170 CPU in the same style as programs for your host computer; use the
2171 @code{file} command to load a new program image, the @code{run} command
2172 to run your program, and so on.
2174 As well as making available all the usual machine registers (see
2175 @code{info reg}), the Z8000 simulator provides three additional items
2176 of information as specially named registers:
2180 Counts clock-ticks in the simulator.
2183 Counts instructions run in the simulator.
2186 Execution time in 60ths of a second.
2189 You can refer to these values in @value{GDBN} expressions with the usual
2190 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
2191 conditional breakpoint that suspends only after at least 5000
2192 simulated clock ticks.
2194 @c need to add much more detail about sims!