Commit | Line | Data |
---|---|---|
c906108c SS |
1 | @c -*- Texinfo -*- |
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. | |
c906108c | 4 | |
c906108c SS |
5 | @node Remote Serial |
6 | @subsection The @value{GDBN} remote serial protocol | |
7 | ||
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 | |
12 | program, you need: | |
13 | ||
14 | @enumerate | |
15 | @item | |
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. | |
19 | ||
20 | @item | |
21 | You probably need a C subroutine library to support your program's | |
22 | subroutine calls, notably managing input and output. | |
23 | ||
24 | @item | |
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 | |
28 | documentation. | |
29 | @end enumerate | |
30 | ||
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: | |
34 | ||
35 | @table @emph | |
36 | @item On the host, | |
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}). | |
40 | ||
41 | @item On the 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}. | |
45 | ||
c906108c SS |
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. | |
c906108c SS |
49 | @end table |
50 | ||
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 | |
53 | @sc{sparc} boards. | |
54 | ||
55 | @cindex remote serial stub list | |
56 | These working remote stubs are distributed with @value{GDBN}: | |
57 | ||
58 | @table @code | |
59 | ||
60 | @item i386-stub.c | |
61 | @kindex i386-stub.c | |
62 | @cindex Intel | |
63 | @cindex i386 | |
64 | For Intel 386 and compatible architectures. | |
65 | ||
66 | @item m68k-stub.c | |
67 | @kindex m68k-stub.c | |
68 | @cindex Motorola 680x0 | |
69 | @cindex m680x0 | |
70 | For Motorola 680x0 architectures. | |
71 | ||
72 | @item sh-stub.c | |
73 | @kindex sh-stub.c | |
74 | @cindex Hitachi | |
75 | @cindex SH | |
76 | For Hitachi SH architectures. | |
77 | ||
78 | @item sparc-stub.c | |
79 | @kindex sparc-stub.c | |
80 | @cindex Sparc | |
81 | For @sc{sparc} architectures. | |
82 | ||
83 | @item sparcl-stub.c | |
84 | @kindex sparcl-stub.c | |
85 | @cindex Fujitsu | |
86 | @cindex SparcLite | |
87 | For Fujitsu @sc{sparclite} architectures. | |
88 | ||
89 | @end table | |
90 | ||
91 | The @file{README} file in the @value{GDBN} distribution may list other | |
92 | recently added stubs. | |
93 | ||
94 | @menu | |
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 | |
085dd6e6 | 98 | * Protocol:: Definition of the communication protocol |
c906108c | 99 | * Server:: Using the `gdbserver' program |
c906108c | 100 | * NetWare:: Using the `gdbserve.nlm' program |
c906108c SS |
101 | @end menu |
102 | ||
103 | @node Stub Contents | |
104 | @subsubsection What the stub can do for you | |
105 | ||
106 | @cindex remote serial stub | |
107 | The debugging stub for your architecture supplies these three | |
108 | subroutines: | |
109 | ||
110 | @table @code | |
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. | |
117 | ||
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. | |
124 | ||
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 | |
134 | machine. | |
135 | ||
136 | @item breakpoint | |
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. | |
148 | ||
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. | |
152 | @end table | |
153 | ||
154 | @node Bootstrapping | |
155 | @subsubsection What you must do for the stub | |
156 | ||
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. | |
161 | ||
162 | First of all you need to tell the stub how to communicate with the | |
163 | serial port. | |
164 | ||
165 | @table @code | |
166 | @item int getDebugChar() | |
167 | @kindex 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. | |
171 | ||
172 | @item void putDebugChar(int) | |
173 | @kindex putDebugChar | |
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. | |
177 | @end table | |
178 | ||
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. | |
186 | ||
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}). | |
191 | ||
192 | Other routines you need to supply are: | |
193 | ||
194 | @table @code | |
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. | |
210 | ||
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 | |
7a292a7a | 214 | @sc{sparc} and 68k stubs are able to mask interrupts themselves without |
c906108c SS |
215 | help from @code{exceptionHandler}. |
216 | ||
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. | |
222 | ||
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. | |
225 | @end table | |
226 | ||
227 | @noindent | |
228 | You must also make sure this library routine is available: | |
229 | ||
230 | @table @code | |
231 | @item void *memset(void *, int, int) | |
232 | @kindex memset | |
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. | |
237 | @end table | |
238 | ||
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. | |
243 | ||
244 | ||
245 | @node Debug Session | |
246 | @subsubsection Putting it all together | |
247 | ||
248 | @cindex remote serial debugging summary | |
249 | In summary, when your program is ready to debug, you must follow these | |
250 | steps. | |
251 | ||
252 | @enumerate | |
253 | @item | |
254 | Make sure you have the supporting low-level routines | |
255 | (@pxref{Bootstrapping,,What you must do for the stub}): | |
256 | @display | |
257 | @code{getDebugChar}, @code{putDebugChar}, | |
258 | @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. | |
259 | @end display | |
260 | ||
261 | @item | |
262 | Insert these lines near the top of your program: | |
263 | ||
264 | @example | |
265 | set_debug_traps(); | |
266 | breakpoint(); | |
267 | @end example | |
268 | ||
269 | @item | |
270 | For the 680x0 stub only, you need to provide a variable called | |
271 | @code{exceptionHook}. Normally you just use: | |
272 | ||
273 | @example | |
274 | void (*exceptionHook)() = 0; | |
275 | @end example | |
276 | ||
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. | |
282 | ||
283 | @item | |
284 | Compile and link together: your program, the @value{GDBN} debugging stub for | |
285 | your target architecture, and the supporting subroutines. | |
286 | ||
287 | @item | |
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. | |
290 | ||
291 | @item | |
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. | |
296 | ||
297 | @item | |
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 | |
301 | of its pure text. | |
302 | ||
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}: | |
310 | ||
311 | @example | |
312 | target remote /dev/ttyb | |
313 | @end example | |
314 | ||
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}: | |
319 | ||
320 | @example | |
321 | target remote manyfarms:2828 | |
322 | @end example | |
323 | @end enumerate | |
324 | ||
325 | Now you can use all the usual commands to examine and change data and to | |
326 | step and continue the remote program. | |
327 | ||
328 | To resume the remote program and stop debugging it, use the @code{detach} | |
329 | command. | |
330 | ||
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: | |
338 | ||
339 | @example | |
340 | Interrupted while waiting for the program. | |
341 | Give up (and stop debugging it)? (y or n) | |
342 | @end example | |
343 | ||
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. | |
348 | ||
349 | @node Protocol | |
350 | @subsubsection Communication protocol | |
351 | ||
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.) | |
362 | ||
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}. | |
367 | ||
085dd6e6 JM |
368 | In the examples below, @samp{<-} and @samp{->} are used to indicate |
369 | transmitted and received data respectfully. | |
370 | ||
c906108c SS |
371 | @cindex protocol, @value{GDBN} remote serial |
372 | @cindex serial protocol, @value{GDBN} remote | |
373 | @cindex remote serial protocol | |
085dd6e6 JM |
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}: | |
c906108c SS |
380 | |
381 | @example | |
085dd6e6 JM |
382 | @code{$}@var{packet-data}@code{#}@var{checksum} |
383 | @end example | |
384 | @noindent | |
385 | or, with the optional @var{sequence-id}: | |
386 | @example | |
387 | @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} | |
c906108c SS |
388 | @end example |
389 | ||
390 | @cindex checksum, for @value{GDBN} remote | |
391 | @noindent | |
085dd6e6 JM |
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 | |
395 | @var{packet-data}). | |
396 | ||
397 | @cindex sequence-id, for @value{GDBN} remote | |
398 | @noindent | |
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. | |
c906108c SS |
402 | |
403 | When either the host or the target machine receives a packet, the first | |
085dd6e6 JM |
404 | response expected is an acknowledgment: either @samp{+} (to indicate |
405 | the package was received correctly) or @samp{-} (to request | |
406 | retransmission): | |
c906108c | 407 | |
085dd6e6 JM |
408 | @example |
409 | <- @code{$}@var{packet-data}@code{#}@var{checksum} | |
410 | -> @code{+} | |
411 | @end example | |
412 | @noindent | |
413 | If the received packet included a @var{sequence-id} than that is | |
414 | appended to a positive acknowledgment: | |
c906108c | 415 | |
085dd6e6 JM |
416 | @example |
417 | <- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} | |
418 | -> @code{+}@var{sequence-id} | |
419 | @end example | |
c906108c | 420 | |
085dd6e6 JM |
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). | |
425 | ||
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 | |
432 | suppressed. | |
433 | ||
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 | |
439 | @code{n > 126}. | |
440 | ||
441 | So: | |
442 | @example | |
443 | "@code{0* }" | |
444 | @end example | |
445 | @noindent | |
446 | means the same as "0000". | |
c906108c | 447 | |
085dd6e6 JM |
448 | The error response, returned for some packets includes a two character |
449 | error number. That number is not well defined. | |
c906108c | 450 | |
085dd6e6 JM |
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 | |
454 | on the response. | |
c906108c | 455 | |
085dd6e6 JM |
456 | Below is a complete list of all currently defined @var{command}s and |
457 | their corresponding response @var{data}: | |
c906108c | 458 | |
085dd6e6 JM |
459 | @multitable @columnfractions .30 .30 .40 |
460 | @item Packet | |
461 | @tab Request | |
462 | @tab Description | |
c906108c | 463 | |
085dd6e6 JM |
464 | @item extended ops @emph{(optional)} |
465 | @tab @code{!} | |
466 | @tab | |
467 | Use the extended remote protocol. Sticky -- only needs to be set once. | |
468 | The extended remote protocol support the @samp{R} packet. | |
469 | @item | |
470 | @tab reply @samp{} | |
471 | @tab | |
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. | |
475 | ||
476 | @item last signal | |
477 | @tab @code{?} | |
478 | @tab | |
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 | |
481 | signal number. | |
482 | ||
483 | @item reserved | |
484 | @tab @code{a} | |
485 | @tab Reserved for future use | |
486 | ||
487 | @item set program arguments @strong{(reserved)} @emph{(optional)} | |
488 | @tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...} | |
489 | @tab | |
490 | Initialized @samp{argv[]} array passed into program. @var{arglen} | |
491 | specifies the number of bytes in the hex encoded byte stream @var{arg}. | |
492 | @item | |
493 | @tab reply @code{OK} | |
494 | @item | |
495 | @tab reply @code{E}@var{NN} | |
496 | ||
497 | @item set baud @strong{(deprecated)} | |
498 | @tab @code{b}@var{baud} | |
499 | @tab | |
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 | |
508 | happened.} | |
509 | ||
510 | @item set breakpoint @strong{(deprecated)} | |
511 | @tab @code{B}@var{addr},@var{mode} | |
512 | @tab | |
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 | |
515 | @samp{z} packets.} | |
516 | ||
517 | @item continue | |
518 | @tab @code{c}@var{addr} | |
519 | @tab | |
520 | @var{addr} is address to resume. If @var{addr} is omitted, resume at | |
521 | current address. | |
522 | @item | |
523 | @tab reply | |
524 | @tab see below | |
525 | ||
526 | @item continue with signal @emph{(optional)} | |
527 | @tab @code{C}@var{sig}@code{;}@var{addr} | |
528 | @tab | |
529 | Continue with signal @var{sig} (hex signal number). If | |
530 | @code{;}@var{addr} is omitted, resume at same address. | |
531 | @item | |
532 | @tab reply | |
533 | @tab see below | |
c906108c | 534 | |
085dd6e6 JM |
535 | @item toggle debug @emph{(optional)} |
536 | @tab @code{d} | |
537 | @tab | |
538 | toggle debug flag (see 386 & 68k stubs) | |
c906108c | 539 | |
085dd6e6 JM |
540 | @item detach @emph{(optional)} |
541 | @tab @code{D} | |
542 | @tab Reply OK. | |
c906108c | 543 | |
085dd6e6 JM |
544 | @item reserved |
545 | @tab @code{e} | |
546 | @tab Reserved for future use | |
c906108c | 547 | |
085dd6e6 JM |
548 | @item reserved |
549 | @tab @code{E} | |
550 | @tab Reserved for future use | |
c906108c | 551 | |
085dd6e6 JM |
552 | @item reserved |
553 | @tab @code{f} | |
554 | @tab Reserved for future use | |
555 | ||
556 | @item reserved | |
557 | @tab @code{F} | |
558 | @tab Reserved for future use | |
559 | ||
560 | @item read registers | |
561 | @tab @code{g} | |
562 | @tab Read general registers. | |
563 | @item | |
564 | @tab reply @var{XX...} | |
565 | @tab | |
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} | |
570 | macros. | |
571 | @item | |
572 | @tab @code{E}@var{NN} | |
573 | @tab for an error. | |
574 | ||
575 | @item write regs | |
576 | @tab @code{G}@var{XX...} | |
577 | @tab | |
578 | See @samp{g} for a description of the @var{XX...} data. | |
579 | @item | |
580 | @tab reply @code{OK} | |
581 | @tab for success | |
582 | @item | |
583 | @tab reply @code{E}@var{NN} | |
584 | @tab for an error | |
585 | ||
586 | @item reserved | |
587 | @tab @code{h} | |
588 | @tab Reserved for future use | |
589 | ||
590 | @item set thread @emph{(optional)} | |
591 | @tab @code{H}@var{c}@var{t...} | |
592 | @tab | |
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 | |
596 | thread, any thread. | |
597 | @item | |
598 | @tab reply @code{OK} | |
599 | @tab for success | |
600 | @item | |
601 | @tab reply @code{E}@var{NN} | |
602 | @tab for an error | |
603 | ||
604 | @item cycle step @strong{(draft)} @emph{(optional)} | |
605 | @tab @code{i}@var{addr}@code{,}@var{nnn} | |
606 | @tab | |
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. | |
610 | ||
611 | @item signal then cycle step @strong{(reserved)} @emph{(optional)} | |
612 | @tab @code{I} | |
613 | @tab | |
614 | See @samp{i} and @samp{S} for likely syntax and semantics. | |
615 | ||
616 | @item reserved | |
617 | @tab @code{j} | |
618 | @tab Reserved for future use | |
619 | ||
620 | @item reserved | |
621 | @tab @code{J} | |
622 | @tab Reserved for future use | |
623 | ||
624 | @item kill request @emph{(optional)} | |
625 | @tab @code{k} | |
626 | @tab | |
627 | ||
628 | @item reserved | |
629 | @tab @code{l} | |
630 | @tab Reserved for future use | |
631 | ||
632 | @item reserved | |
633 | @tab @code{L} | |
634 | @tab Reserved for future use | |
635 | ||
636 | @item read memory | |
637 | @tab @code{m}@var{addr}@code{,}@var{length} | |
638 | @tab | |
639 | Read @var{length} bytes of memory starting at address @var{addr}. | |
640 | @item | |
641 | @tab reply @var{XX...} | |
642 | @tab | |
643 | @var{XX...} is mem contents. Can be fewer bytes than requested if able to | |
644 | read only part of the data. | |
645 | @item | |
646 | @tab reply @code{E}@var{NN} | |
647 | @tab @var{NN} is errno | |
648 | ||
649 | @item write mem | |
650 | @tab @code{M}@var{addr},@var{length}@code{:}@var{XX...} | |
651 | @tab | |
652 | Write @var{length} bytes of memory starting at address @var{addr}. | |
653 | @var{XX...} is the data. | |
654 | @item | |
655 | @tab reply @code{OK} | |
656 | @tab for success | |
657 | @item | |
658 | @tab reply @code{E}@var{NN} | |
659 | @tab | |
660 | for an error (this includes the case where only part of the data was | |
661 | written). | |
662 | ||
663 | @item reserved | |
664 | @tab @code{n} | |
665 | @tab Reserved for future use | |
666 | ||
667 | @item reserved | |
668 | @tab @code{N} | |
669 | @tab Reserved for future use | |
670 | ||
671 | @item reserved | |
672 | @tab @code{o} | |
673 | @tab Reserved for future use | |
674 | ||
675 | @item reserved | |
676 | @tab @code{O} | |
677 | @tab Reserved for future use | |
678 | ||
679 | @item read reg @strong{(reserved)} | |
680 | @tab @code{p}@var{n...} | |
681 | @tab | |
682 | See write register. | |
683 | @item | |
684 | @tab return @var{r....} | |
685 | @tab The hex encoded value of the register in target byte order. | |
686 | ||
687 | @item write reg @emph{(optional)} | |
688 | @tab @code{P}@var{n...}@code{=}@var{r...} | |
689 | @tab | |
690 | Write register @var{n...} with value @var{r...}, which contains two hex | |
691 | digits for each byte in the register (target byte order). | |
692 | @item | |
693 | @tab reply @code{OK} | |
694 | @tab for success | |
695 | @item | |
696 | @tab reply @code{E}@var{NN} | |
697 | @tab for an error | |
698 | ||
699 | @item general query @emph{(optional)} | |
700 | @tab @code{q}@var{query} | |
701 | @tab | |
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 | |
707 | @var{query} name. | |
708 | @item | |
709 | @tab reply @code{XX...} | |
710 | @tab Hex encoded data from query. The reply can not be empty. | |
711 | @item | |
712 | @tab reply @code{E}@var{NN} | |
713 | @tab error reply | |
714 | @item | |
715 | @tab reply @samp{} | |
716 | @tab Indicating an unrecognized @var{query}. | |
717 | ||
718 | @item current thread | |
719 | @tab @code{q}@code{C} | |
720 | @tab Return the current thread id. | |
721 | @item | |
722 | @tab reply @code{QC}@var{pid} | |
723 | @tab | |
724 | Where @var{pid} is a HEX encoded 16 bit process id. | |
725 | @item | |
726 | @tab reply * | |
727 | @tab Any other reply implies the old pid. | |
728 | ||
729 | @item compute CRC of memory block | |
730 | @tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length} | |
731 | @tab | |
732 | @item | |
733 | @tab reply @code{E}@var{NN} | |
734 | @tab An error (such as memory fault) | |
735 | @item | |
736 | @tab reply @code{C}@var{CRC32} | |
737 | @tab A 32 bit cyclic redundancy check of the specified memory region. | |
738 | ||
739 | @item query @var{LIST} or @var{threadLIST} | |
740 | @tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} | |
741 | @tab | |
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 | |
744 | digits. | |
745 | @item | |
746 | @tab reply * | |
747 | @tab | |
748 | See @code{remote.c:parse_threadlist_response()}. | |
749 | ||
750 | @item query sect offs | |
751 | @tab @code{q}@code{Offsets} | |
752 | @tab Get section offsets. | |
753 | @item | |
754 | @tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} | |
755 | ||
756 | @item thread info request | |
757 | @tab @code{q}@code{P}@var{mode}@var{threadid} | |
758 | @tab | |
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. | |
761 | @item | |
762 | @tab reply * | |
763 | @tab | |
764 | See @code{remote.c:remote_unpack_thread_info_response()}. | |
765 | ||
766 | @item remote command @strong{(reserved)} | |
767 | @tab @code{q}@code{Rcmd,}@var{COMMAND} | |
768 | @tab | |
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}. | |
772 | @item | |
773 | @tab reply @var{OUTPUT} | |
774 | @tab | |
775 | The @var{OUTPUT} (hex encoded). Must be non-empty. | |
776 | @item | |
777 | @tab reply @samp{} | |
778 | @tab | |
779 | When @samp{q}@samp{Rcmd} is not recognized. | |
780 | ||
781 | @item general set @emph{(optional)} | |
782 | @tab @code{Q}@var{var}@code{=}@var{val} | |
783 | @tab | |
784 | Set value of @var{var} to @var{val}. See @samp{q} for a discussing of | |
785 | naming conventions. | |
786 | ||
787 | @item reset @emph{(optional)} | |
788 | @tab r | |
789 | @tab reset -- see sparc stub. | |
790 | ||
791 | @item remote restart @emph{(optional)} | |
792 | @tab @code{R}@var{XX} | |
793 | @tab | |
794 | Restart the remote server. @var{XX} while needed has no clear | |
795 | definition. | |
796 | ||
797 | @item step @emph{(optional)} | |
798 | @tab @code{s}@var{addr} | |
799 | @tab | |
800 | @var{addr} is address to resume. If @var{addr} is omitted, resume at | |
801 | same address. | |
802 | @item | |
803 | @tab reply | |
804 | @tab see below | |
805 | ||
806 | @item step with signal @emph{(optional)} | |
807 | @tab @code{S}@var{sig}@code{;}@var{addr} | |
808 | @tab | |
809 | Like @samp{C} but step not continue. | |
810 | @item | |
811 | @tab reply | |
812 | @tab see below | |
813 | ||
814 | @item search @emph{(optional)} | |
815 | @tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} | |
816 | @tab | |
817 | Search backwards starting at address @var{addr} for a match with pattern | |
818 | @var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 | |
819 | bytes. @var{addr} must be at least 3 digits. | |
820 | ||
821 | @item thread alive @emph{(optional)} | |
822 | @tab @code{T}@var{XX} | |
823 | @tab Find out if the thread XX is alive. | |
824 | @item | |
825 | @tab reply @code{OK} | |
826 | @tab thread is still alive | |
827 | @item | |
828 | @tab reply @code{E}@var{NN} | |
829 | @tab thread is dead | |
830 | ||
831 | @item reserved | |
832 | @tab @code{u} | |
833 | @tab Reserved for future use | |
834 | ||
835 | @item reserved | |
836 | @tab @code{U} | |
837 | @tab Reserved for future use | |
838 | ||
839 | @item reserved | |
840 | @tab @code{v} | |
841 | @tab Reserved for future use | |
842 | ||
843 | @item reserved | |
844 | @tab @code{V} | |
845 | @tab Reserved for future use | |
846 | ||
847 | @item reserved | |
848 | @tab @code{w} | |
849 | @tab Reserved for future use | |
850 | ||
851 | @item reserved | |
852 | @tab @code{W} | |
853 | @tab Reserved for future use | |
854 | ||
855 | @item reserved | |
856 | @tab @code{x} | |
857 | @tab Reserved for future use | |
858 | ||
859 | @item write mem (binary) @emph{(optional)} | |
860 | @tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...} | |
861 | @tab | |
862 | @var{addr} is address, @var{length} is number of bytes, @var{XX...} is | |
863 | binary data. | |
864 | @item | |
865 | @tab reply @code{OK} | |
866 | @tab for success | |
867 | @item | |
868 | @tab reply @code{E}@var{NN} | |
869 | @tab for an error | |
870 | ||
871 | @item reserved | |
872 | @tab @code{y} | |
873 | @tab Reserved for future use | |
874 | ||
875 | @item reserved | |
876 | @tab @code{Y} | |
877 | @tab Reserved for future use | |
878 | ||
879 | @item remove break or watchpoint @strong{(draft)} @emph{(optional)} | |
880 | @tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} | |
881 | @tab | |
882 | See @samp{Z}. | |
883 | ||
884 | @item insert break or watchpoint @strong{(draft)} @emph{(optional)} | |
885 | @tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} | |
886 | @tab | |
887 | @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware | |
888 | breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, | |
889 | @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in | |
890 | bytes. For a software breakpoint, @var{length} specifies the size of | |
891 | the instruction to be patched. For hardware breakpoints and watchpoints | |
892 | @var{length} specifies the memory region to be monitored. | |
893 | @item | |
894 | @tab reply @code{E}@var{NN} | |
895 | @tab for an error | |
896 | @item | |
897 | @tab reply @code{OK} | |
898 | @tab for success | |
899 | @item | |
900 | @tab @samp{} | |
901 | @tab If not supported. | |
902 | ||
903 | @item reserved | |
904 | @tab <other> | |
905 | @tab Reserved for future use | |
906 | ||
907 | @end multitable | |
908 | ||
909 | In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets, | |
910 | there is no immediate response. The reply, described below, comes when | |
911 | the machine stops: | |
912 | ||
913 | @multitable @columnfractions .4 .6 | |
914 | ||
915 | @item @code{S}@var{AA} | |
916 | @tab @var{AA} is the signal number | |
917 | ||
918 | @item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} | |
919 | @tab | |
920 | @var{AA} = two hex digit signal number; @var{n...} = register number | |
921 | (hex), @var{r...} = target byte ordered register contents, size defined | |
922 | by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = | |
923 | thread process ID, this is a hex integer; @var{n...} = other string not | |
924 | starting with valid hex digit. @value{GDBN} should ignore this | |
925 | @var{n...}, @var{r...} pair and go on to the next. This way we can | |
926 | extend the protocol. | |
927 | ||
928 | @item @code{W}@var{AA} | |
929 | @tab | |
930 | The process exited, and @var{AA} is the exit status. This is only | |
931 | applicable for certains sorts of targets. | |
932 | ||
933 | @item @code{X}@var{AA} | |
934 | @tab | |
935 | The process terminated with signal @var{AA}. | |
936 | ||
937 | @item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)} | |
938 | @tab | |
939 | @var{AA} = signal number; @var{tttttttt} = address of symbol "_start"; | |
940 | @var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss | |
941 | section. @emph{Note: only used by Cisco Systems targets. The difference | |
942 | between this reply and the "qOffsets" query is that the 'N' packet may | |
943 | arrive spontaneously whereas the 'qOffsets' is a query initiated by the | |
944 | host debugger.} | |
945 | ||
946 | @item @code{O}@var{XX...} | |
947 | @tab | |
948 | @var{XX...} is hex encoding of ASCII data. This can happen at any time | |
949 | while the program is running and the debugger should continue to wait | |
950 | for 'W', 'T', etc. | |
951 | ||
952 | @end multitable | |
953 | ||
954 | Example sequence of a target being re-started. Notice how the restart | |
955 | does not get any direct output: | |
956 | ||
957 | @example | |
958 | <- @code{R00} | |
959 | -> @code{+} | |
960 | @emph{target restarts} | |
961 | <- @code{?} | |
962 | -> @code{+} | |
963 | -> @code{T001:1234123412341234} | |
964 | <- @code{+} | |
965 | @end example | |
966 | ||
967 | Example sequence of a target being stepped by a single instruction: | |
968 | ||
969 | @example | |
970 | <- @code{G1445...} | |
971 | -> @code{+} | |
972 | <- @code{s} | |
973 | -> @code{+} | |
974 | @emph{time passes} | |
975 | -> @code{T001:1234123412341234} | |
976 | <- @code{+} | |
977 | <- @code{g} | |
978 | -> @code{+} | |
979 | -> @code{1455...} | |
980 | <- @code{+} | |
981 | @end example | |
c906108c SS |
982 | |
983 | @kindex set remotedebug | |
984 | @kindex show remotedebug | |
985 | @cindex packets, reporting on stdout | |
986 | @cindex serial connections, debugging | |
987 | If you have trouble with the serial connection, you can use the command | |
988 | @code{set remotedebug}. This makes @value{GDBN} report on all packets sent | |
989 | back and forth across the serial line to the remote machine. The | |
990 | packet-debugging information is printed on the @value{GDBN} standard output | |
991 | stream. @code{set remotedebug off} turns it off, and @code{show | |
992 | remotedebug} shows you its current state. | |
993 | ||
c906108c SS |
994 | @node Server |
995 | @subsubsection Using the @code{gdbserver} program | |
996 | ||
997 | @kindex gdbserver | |
998 | @cindex remote connection without stubs | |
999 | @code{gdbserver} is a control program for Unix-like systems, which | |
1000 | allows you to connect your program with a remote @value{GDBN} via | |
1001 | @code{target remote}---but without linking in the usual debugging stub. | |
1002 | ||
1003 | @code{gdbserver} is not a complete replacement for the debugging stubs, | |
1004 | because it requires essentially the same operating-system facilities | |
1005 | that @value{GDBN} itself does. In fact, a system that can run | |
1006 | @code{gdbserver} to connect to a remote @value{GDBN} could also run | |
1007 | @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, | |
1008 | because it is a much smaller program than @value{GDBN} itself. It is | |
1009 | also easier to port than all of @value{GDBN}, so you may be able to get | |
1010 | started more quickly on a new system by using @code{gdbserver}. | |
1011 | Finally, if you develop code for real-time systems, you may find that | |
1012 | the tradeoffs involved in real-time operation make it more convenient to | |
1013 | do as much development work as possible on another system, for example | |
1014 | by cross-compiling. You can use @code{gdbserver} to make a similar | |
1015 | choice for debugging. | |
1016 | ||
1017 | @value{GDBN} and @code{gdbserver} communicate via either a serial line | |
1018 | or a TCP connection, using the standard @value{GDBN} remote serial | |
1019 | protocol. | |
1020 | ||
1021 | @table @emph | |
1022 | @item On the target machine, | |
1023 | you need to have a copy of the program you want to debug. | |
1024 | @code{gdbserver} does not need your program's symbol table, so you can | |
1025 | strip the program if necessary to save space. @value{GDBN} on the host | |
1026 | system does all the symbol handling. | |
1027 | ||
1028 | To use the server, you must tell it how to communicate with @value{GDBN}; | |
1029 | the name of your program; and the arguments for your program. The | |
1030 | syntax is: | |
1031 | ||
1032 | @smallexample | |
1033 | target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] | |
1034 | @end smallexample | |
1035 | ||
1036 | @var{comm} is either a device name (to use a serial line) or a TCP | |
1037 | hostname and portnumber. For example, to debug Emacs with the argument | |
1038 | @samp{foo.txt} and communicate with @value{GDBN} over the serial port | |
1039 | @file{/dev/com1}: | |
1040 | ||
1041 | @smallexample | |
1042 | target> gdbserver /dev/com1 emacs foo.txt | |
1043 | @end smallexample | |
1044 | ||
1045 | @code{gdbserver} waits passively for the host @value{GDBN} to communicate | |
1046 | with it. | |
1047 | ||
1048 | To use a TCP connection instead of a serial line: | |
1049 | ||
1050 | @smallexample | |
1051 | target> gdbserver host:2345 emacs foo.txt | |
1052 | @end smallexample | |
1053 | ||
1054 | The only difference from the previous example is the first argument, | |
1055 | specifying that you are communicating with the host @value{GDBN} via | |
1056 | TCP. The @samp{host:2345} argument means that @code{gdbserver} is to | |
1057 | expect a TCP connection from machine @samp{host} to local TCP port 2345. | |
1058 | (Currently, the @samp{host} part is ignored.) You can choose any number | |
1059 | you want for the port number as long as it does not conflict with any | |
1060 | TCP ports already in use on the target system (for example, @code{23} is | |
1061 | reserved for @code{telnet}).@footnote{If you choose a port number that | |
1062 | conflicts with another service, @code{gdbserver} prints an error message | |
1063 | and exits.} You must use the same port number with the host @value{GDBN} | |
1064 | @code{target remote} command. | |
1065 | ||
1066 | @item On the @value{GDBN} host machine, | |
1067 | you need an unstripped copy of your program, since @value{GDBN} needs | |
1068 | symbols and debugging information. Start up @value{GDBN} as usual, | |
1069 | using the name of the local copy of your program as the first argument. | |
1070 | (You may also need the @w{@samp{--baud}} option if the serial line is | |
1071 | running at anything other than 9600 bps.) After that, use @code{target | |
1072 | remote} to establish communications with @code{gdbserver}. Its argument | |
1073 | is either a device name (usually a serial device, like | |
1074 | @file{/dev/ttyb}), or a TCP port descriptor in the form | |
1075 | @code{@var{host}:@var{PORT}}. For example: | |
1076 | ||
1077 | @smallexample | |
1078 | (@value{GDBP}) target remote /dev/ttyb | |
1079 | @end smallexample | |
1080 | ||
1081 | @noindent | |
1082 | communicates with the server via serial line @file{/dev/ttyb}, and | |
1083 | ||
1084 | @smallexample | |
1085 | (@value{GDBP}) target remote the-target:2345 | |
1086 | @end smallexample | |
1087 | ||
1088 | @noindent | |
1089 | communicates via a TCP connection to port 2345 on host @w{@file{the-target}}. | |
1090 | For TCP connections, you must start up @code{gdbserver} prior to using | |
1091 | the @code{target remote} command. Otherwise you may get an error whose | |
1092 | text depends on the host system, but which usually looks something like | |
1093 | @samp{Connection refused}. | |
1094 | @end table | |
c906108c | 1095 | |
c906108c SS |
1096 | @node NetWare |
1097 | @subsubsection Using the @code{gdbserve.nlm} program | |
1098 | ||
1099 | @kindex gdbserve.nlm | |
1100 | @code{gdbserve.nlm} is a control program for NetWare systems, which | |
1101 | allows you to connect your program with a remote @value{GDBN} via | |
1102 | @code{target remote}. | |
1103 | ||
1104 | @value{GDBN} and @code{gdbserve.nlm} communicate via a serial line, | |
1105 | using the standard @value{GDBN} remote serial protocol. | |
1106 | ||
1107 | @table @emph | |
1108 | @item On the target machine, | |
1109 | you need to have a copy of the program you want to debug. | |
1110 | @code{gdbserve.nlm} does not need your program's symbol table, so you | |
1111 | can strip the program if necessary to save space. @value{GDBN} on the | |
1112 | host system does all the symbol handling. | |
1113 | ||
1114 | To use the server, you must tell it how to communicate with | |
1115 | @value{GDBN}; the name of your program; and the arguments for your | |
1116 | program. The syntax is: | |
1117 | ||
1118 | @smallexample | |
1119 | load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ] | |
1120 | [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ] | |
1121 | @end smallexample | |
1122 | ||
1123 | @var{board} and @var{port} specify the serial line; @var{baud} specifies | |
1124 | the baud rate used by the connection. @var{port} and @var{node} default | |
1125 | to 0, @var{baud} defaults to 9600 bps. | |
1126 | ||
1127 | For example, to debug Emacs with the argument @samp{foo.txt}and | |
1128 | communicate with @value{GDBN} over serial port number 2 or board 1 | |
1129 | using a 19200 bps connection: | |
1130 | ||
1131 | @smallexample | |
1132 | load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt | |
1133 | @end smallexample | |
1134 | ||
1135 | @item On the @value{GDBN} host machine, | |
1136 | you need an unstripped copy of your program, since @value{GDBN} needs | |
1137 | symbols and debugging information. Start up @value{GDBN} as usual, | |
1138 | using the name of the local copy of your program as the first argument. | |
1139 | (You may also need the @w{@samp{--baud}} option if the serial line is | |
1140 | running at anything other than 9600 bps. After that, use @code{target | |
1141 | remote} to establish communications with @code{gdbserve.nlm}. Its | |
1142 | argument is a device name (usually a serial device, like | |
1143 | @file{/dev/ttyb}). For example: | |
1144 | ||
1145 | @smallexample | |
1146 | (@value{GDBP}) target remote /dev/ttyb | |
1147 | @end smallexample | |
1148 | ||
1149 | @noindent | |
1150 | communications with the server via serial line @file{/dev/ttyb}. | |
1151 | @end table | |
c906108c | 1152 | |
c906108c SS |
1153 | @node i960-Nindy Remote |
1154 | @subsection @value{GDBN} with a remote i960 (Nindy) | |
1155 | ||
1156 | @cindex Nindy | |
1157 | @cindex i960 | |
1158 | @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When | |
1159 | @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can | |
1160 | tell @value{GDBN} how to connect to the 960 in several ways: | |
1161 | ||
1162 | @itemize @bullet | |
1163 | @item | |
1164 | Through command line options specifying serial port, version of the | |
1165 | Nindy protocol, and communications speed; | |
1166 | ||
1167 | @item | |
1168 | By responding to a prompt on startup; | |
1169 | ||
1170 | @item | |
1171 | By using the @code{target} command at any point during your @value{GDBN} | |
1172 | session. @xref{Target Commands, ,Commands for managing targets}. | |
1173 | ||
1174 | @end itemize | |
1175 | ||
1176 | @menu | |
1177 | * Nindy Startup:: Startup with Nindy | |
1178 | * Nindy Options:: Options for Nindy | |
1179 | * Nindy Reset:: Nindy reset command | |
1180 | @end menu | |
1181 | ||
1182 | @node Nindy Startup | |
1183 | @subsubsection Startup with Nindy | |
1184 | ||
1185 | If you simply start @code{@value{GDBP}} without using any command-line | |
1186 | options, you are prompted for what serial port to use, @emph{before} you | |
1187 | reach the ordinary @value{GDBN} prompt: | |
1188 | ||
1189 | @example | |
1190 | Attach /dev/ttyNN -- specify NN, or "quit" to quit: | |
1191 | @end example | |
1192 | ||
1193 | @noindent | |
1194 | Respond to the prompt with whatever suffix (after @samp{/dev/tty}) | |
1195 | identifies the serial port you want to use. You can, if you choose, | |
1196 | simply start up with no Nindy connection by responding to the prompt | |
1197 | with an empty line. If you do this and later wish to attach to Nindy, | |
1198 | use @code{target} (@pxref{Target Commands, ,Commands for managing targets}). | |
1199 | ||
1200 | @node Nindy Options | |
1201 | @subsubsection Options for Nindy | |
1202 | ||
1203 | These are the startup options for beginning your @value{GDBN} session with a | |
1204 | Nindy-960 board attached: | |
1205 | ||
1206 | @table @code | |
1207 | @item -r @var{port} | |
1208 | Specify the serial port name of a serial interface to be used to connect | |
1209 | to the target system. This option is only available when @value{GDBN} is | |
1210 | configured for the Intel 960 target architecture. You may specify | |
1211 | @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a | |
1212 | device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique | |
1213 | suffix for a specific @code{tty} (e.g. @samp{-r a}). | |
1214 | ||
1215 | @item -O | |
1216 | (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use | |
1217 | the ``old'' Nindy monitor protocol to connect to the target system. | |
1218 | This option is only available when @value{GDBN} is configured for the Intel 960 | |
1219 | target architecture. | |
1220 | ||
1221 | @quotation | |
1222 | @emph{Warning:} if you specify @samp{-O}, but are actually trying to | |
1223 | connect to a target system that expects the newer protocol, the connection | |
1224 | fails, appearing to be a speed mismatch. @value{GDBN} repeatedly | |
1225 | attempts to reconnect at several different line speeds. You can abort | |
1226 | this process with an interrupt. | |
1227 | @end quotation | |
1228 | ||
1229 | @item -brk | |
1230 | Specify that @value{GDBN} should first send a @code{BREAK} signal to the target | |
1231 | system, in an attempt to reset it, before connecting to a Nindy target. | |
1232 | ||
1233 | @quotation | |
1234 | @emph{Warning:} Many target systems do not have the hardware that this | |
1235 | requires; it only works with a few boards. | |
1236 | @end quotation | |
1237 | @end table | |
1238 | ||
1239 | The standard @samp{-b} option controls the line speed used on the serial | |
1240 | port. | |
1241 | ||
1242 | @c @group | |
1243 | @node Nindy Reset | |
1244 | @subsubsection Nindy reset command | |
1245 | ||
1246 | @table @code | |
1247 | @item reset | |
1248 | @kindex reset | |
1249 | For a Nindy target, this command sends a ``break'' to the remote target | |
1250 | system; this is only useful if the target has been equipped with a | |
1251 | circuit to perform a hard reset (or some other interesting action) when | |
1252 | a break is detected. | |
1253 | @end table | |
1254 | @c @end group | |
c906108c | 1255 | |
c906108c SS |
1256 | @node UDI29K Remote |
1257 | @subsection The UDI protocol for AMD29K | |
1258 | ||
1259 | @cindex UDI | |
1260 | @cindex AMD29K via UDI | |
1261 | @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'') | |
1262 | protocol for debugging the a29k processor family. To use this | |
1263 | configuration with AMD targets running the MiniMON monitor, you need the | |
1264 | program @code{MONTIP}, available from AMD at no charge. You can also | |
1265 | use @value{GDBN} with the UDI-conformant a29k simulator program | |
1266 | @code{ISSTIP}, also available from AMD. | |
1267 | ||
1268 | @table @code | |
1269 | @item target udi @var{keyword} | |
1270 | @kindex udi | |
1271 | Select the UDI interface to a remote a29k board or simulator, where | |
1272 | @var{keyword} is an entry in the AMD configuration file @file{udi_soc}. | |
1273 | This file contains keyword entries which specify parameters used to | |
1274 | connect to a29k targets. If the @file{udi_soc} file is not in your | |
1275 | working directory, you must set the environment variable @samp{UDICONF} | |
1276 | to its pathname. | |
1277 | @end table | |
1278 | ||
1279 | @node EB29K Remote | |
1280 | @subsection The EBMON protocol for AMD29K | |
1281 | ||
1282 | @cindex EB29K board | |
1283 | @cindex running 29K programs | |
1284 | ||
1285 | AMD distributes a 29K development board meant to fit in a PC, together | |
1286 | with a DOS-hosted monitor program called @code{EBMON}. As a shorthand | |
1287 | term, this development system is called the ``EB29K''. To use | |
1288 | @value{GDBN} from a Unix system to run programs on the EB29K board, you | |
1289 | must first connect a serial cable between the PC (which hosts the EB29K | |
1290 | board) and a serial port on the Unix system. In the following, we | |
1291 | assume you've hooked the cable between the PC's @file{COM1} port and | |
1292 | @file{/dev/ttya} on the Unix system. | |
1293 | ||
1294 | @menu | |
1295 | * Comms (EB29K):: Communications setup | |
1296 | * gdb-EB29K:: EB29K cross-debugging | |
1297 | * Remote Log:: Remote log | |
1298 | @end menu | |
1299 | ||
1300 | @node Comms (EB29K) | |
1301 | @subsubsection Communications setup | |
1302 | ||
1303 | The next step is to set up the PC's port, by doing something like this | |
1304 | in DOS on the PC: | |
1305 | ||
1306 | @example | |
1307 | C:\> MODE com1:9600,n,8,1,none | |
1308 | @end example | |
1309 | ||
1310 | @noindent | |
1311 | This example---run on an MS DOS 4.0 system---sets the PC port to 9600 | |
1312 | bps, no parity, eight data bits, one stop bit, and no ``retry'' action; | |
1313 | you must match the communications parameters when establishing the Unix | |
1314 | end of the connection as well. | |
1315 | @c FIXME: Who knows what this "no retry action" crud from the DOS manual may | |
1316 | @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91 | |
1317 | ||
1318 | To give control of the PC to the Unix side of the serial line, type | |
1319 | the following at the DOS console: | |
1320 | ||
1321 | @example | |
1322 | C:\> CTTY com1 | |
1323 | @end example | |
1324 | ||
1325 | @noindent | |
1326 | (Later, if you wish to return control to the DOS console, you can use | |
1327 | the command @code{CTTY con}---but you must send it over the device that | |
1328 | had control, in our example over the @file{COM1} serial line). | |
1329 | ||
1330 | From the Unix host, use a communications program such as @code{tip} or | |
1331 | @code{cu} to communicate with the PC; for example, | |
1332 | ||
1333 | @example | |
1334 | cu -s 9600 -l /dev/ttya | |
1335 | @end example | |
1336 | ||
1337 | @noindent | |
1338 | The @code{cu} options shown specify, respectively, the linespeed and the | |
1339 | serial port to use. If you use @code{tip} instead, your command line | |
1340 | may look something like the following: | |
1341 | ||
1342 | @example | |
1343 | tip -9600 /dev/ttya | |
1344 | @end example | |
1345 | ||
1346 | @noindent | |
1347 | Your system may require a different name where we show | |
1348 | @file{/dev/ttya} as the argument to @code{tip}. The communications | |
1349 | parameters, including which port to use, are associated with the | |
1350 | @code{tip} argument in the ``remote'' descriptions file---normally the | |
1351 | system table @file{/etc/remote}. | |
1352 | @c FIXME: What if anything needs doing to match the "n,8,1,none" part of | |
1353 | @c the DOS side's comms setup? cu can support -o (odd | |
1354 | @c parity), -e (even parity)---apparently no settings for no parity or | |
1355 | @c for character size. Taken from stty maybe...? John points out tip | |
1356 | @c can set these as internal variables, eg ~s parity=none; man stty | |
1357 | @c suggests that it *might* work to stty these options with stdin or | |
1358 | @c stdout redirected... ---doc@cygnus.com, 25feb91 | |
1359 | ||
1360 | @kindex EBMON | |
1361 | Using the @code{tip} or @code{cu} connection, change the DOS working | |
1362 | directory to the directory containing a copy of your 29K program, then | |
1363 | start the PC program @code{EBMON} (an EB29K control program supplied | |
1364 | with your board by AMD). You should see an initial display from | |
1365 | @code{EBMON} similar to the one that follows, ending with the | |
1366 | @code{EBMON} prompt @samp{#}--- | |
1367 | ||
1368 | @example | |
1369 | C:\> G: | |
1370 | ||
1371 | G:\> CD \usr\joe\work29k | |
1372 | ||
1373 | G:\USR\JOE\WORK29K> EBMON | |
1374 | Am29000 PC Coprocessor Board Monitor, version 3.0-18 | |
1375 | Copyright 1990 Advanced Micro Devices, Inc. | |
1376 | Written by Gibbons and Associates, Inc. | |
1377 | ||
1378 | Enter '?' or 'H' for help | |
1379 | ||
1380 | PC Coprocessor Type = EB29K | |
1381 | I/O Base = 0x208 | |
1382 | Memory Base = 0xd0000 | |
1383 | ||
1384 | Data Memory Size = 2048KB | |
1385 | Available I-RAM Range = 0x8000 to 0x1fffff | |
1386 | Available D-RAM Range = 0x80002000 to 0x801fffff | |
1387 | ||
1388 | PageSize = 0x400 | |
1389 | Register Stack Size = 0x800 | |
1390 | Memory Stack Size = 0x1800 | |
1391 | ||
1392 | CPU PRL = 0x3 | |
1393 | Am29027 Available = No | |
1394 | Byte Write Available = Yes | |
1395 | ||
1396 | # ~. | |
1397 | @end example | |
1398 | ||
1399 | Then exit the @code{cu} or @code{tip} program (done in the example by | |
1400 | typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps | |
1401 | running, ready for @value{GDBN} to take over. | |
1402 | ||
1403 | For this example, we've assumed what is probably the most convenient | |
1404 | way to make sure the same 29K program is on both the PC and the Unix | |
1405 | system: a PC/NFS connection that establishes ``drive @code{G:}'' on the | |
1406 | PC as a file system on the Unix host. If you do not have PC/NFS or | |
1407 | something similar connecting the two systems, you must arrange some | |
1408 | other way---perhaps floppy-disk transfer---of getting the 29K program | |
1409 | from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the | |
1410 | serial line. | |
1411 | ||
1412 | @node gdb-EB29K | |
1413 | @subsubsection EB29K cross-debugging | |
1414 | ||
1415 | Finally, @code{cd} to the directory containing an image of your 29K | |
1416 | program on the Unix system, and start @value{GDBN}---specifying as argument the | |
1417 | name of your 29K program: | |
1418 | ||
1419 | @example | |
1420 | cd /usr/joe/work29k | |
1421 | @value{GDBP} myfoo | |
1422 | @end example | |
1423 | ||
1424 | @need 500 | |
1425 | Now you can use the @code{target} command: | |
1426 | ||
1427 | @example | |
1428 | target amd-eb /dev/ttya 9600 MYFOO | |
1429 | @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to | |
1430 | @c emphasize that this is the name as seen by DOS (since I think DOS is | |
1431 | @c single-minded about case of letters). ---doc@cygnus.com, 25feb91 | |
1432 | @end example | |
1433 | ||
1434 | @noindent | |
1435 | In this example, we've assumed your program is in a file called | |
1436 | @file{myfoo}. Note that the filename given as the last argument to | |
1437 | @code{target amd-eb} should be the name of the program as it appears to DOS. | |
1438 | In our example this is simply @code{MYFOO}, but in general it can include | |
1439 | a DOS path, and depending on your transfer mechanism may not resemble | |
1440 | the name on the Unix side. | |
1441 | ||
1442 | At this point, you can set any breakpoints you wish; when you are ready | |
1443 | to see your program run on the 29K board, use the @value{GDBN} command | |
1444 | @code{run}. | |
1445 | ||
1446 | To stop debugging the remote program, use the @value{GDBN} @code{detach} | |
1447 | command. | |
1448 | ||
1449 | To return control of the PC to its console, use @code{tip} or @code{cu} | |
1450 | once again, after your @value{GDBN} session has concluded, to attach to | |
1451 | @code{EBMON}. You can then type the command @code{q} to shut down | |
1452 | @code{EBMON}, returning control to the DOS command-line interpreter. | |
1453 | Type @code{CTTY con} to return command input to the main DOS console, | |
1454 | and type @kbd{~.} to leave @code{tip} or @code{cu}. | |
1455 | ||
1456 | @node Remote Log | |
1457 | @subsubsection Remote log | |
1458 | @kindex eb.log | |
1459 | @cindex log file for EB29K | |
1460 | ||
1461 | The @code{target amd-eb} command creates a file @file{eb.log} in the | |
1462 | current working directory, to help debug problems with the connection. | |
1463 | @file{eb.log} records all the output from @code{EBMON}, including echoes | |
1464 | of the commands sent to it. Running @samp{tail -f} on this file in | |
1465 | another window often helps to understand trouble with @code{EBMON}, or | |
1466 | unexpected events on the PC side of the connection. | |
1467 | ||
c906108c SS |
1468 | @node ST2000 Remote |
1469 | @subsection @value{GDBN} with a Tandem ST2000 | |
1470 | ||
1471 | To connect your ST2000 to the host system, see the manufacturer's | |
1472 | manual. Once the ST2000 is physically attached, you can run: | |
1473 | ||
1474 | @example | |
1475 | target st2000 @var{dev} @var{speed} | |
1476 | @end example | |
1477 | ||
1478 | @noindent | |
1479 | to establish it as your debugging environment. @var{dev} is normally | |
1480 | the name of a serial device, such as @file{/dev/ttya}, connected to the | |
1481 | ST2000 via a serial line. You can instead specify @var{dev} as a TCP | |
1482 | connection (for example, to a serial line attached via a terminal | |
1483 | concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. | |
1484 | ||
1485 | The @code{load} and @code{attach} commands are @emph{not} defined for | |
1486 | this target; you must load your program into the ST2000 as you normally | |
1487 | would for standalone operation. @value{GDBN} reads debugging information | |
1488 | (such as symbols) from a separate, debugging version of the program | |
1489 | available on your host computer. | |
1490 | @c FIXME!! This is terribly vague; what little content is here is | |
1491 | @c basically hearsay. | |
1492 | ||
1493 | @cindex ST2000 auxiliary commands | |
1494 | These auxiliary @value{GDBN} commands are available to help you with the ST2000 | |
1495 | environment: | |
1496 | ||
1497 | @table @code | |
1498 | @item st2000 @var{command} | |
1499 | @kindex st2000 @var{cmd} | |
1500 | @cindex STDBUG commands (ST2000) | |
1501 | @cindex commands to STDBUG (ST2000) | |
1502 | Send a @var{command} to the STDBUG monitor. See the manufacturer's | |
1503 | manual for available commands. | |
1504 | ||
1505 | @item connect | |
1506 | @cindex connect (to STDBUG) | |
1507 | Connect the controlling terminal to the STDBUG command monitor. When | |
1508 | you are done interacting with STDBUG, typing either of two character | |
1509 | sequences gets you back to the @value{GDBN} command prompt: | |
1510 | @kbd{@key{RET}~.} (Return, followed by tilde and period) or | |
1511 | @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). | |
1512 | @end table | |
c906108c | 1513 | |
c906108c SS |
1514 | @node VxWorks Remote |
1515 | @subsection @value{GDBN} and VxWorks | |
7a292a7a | 1516 | |
c906108c SS |
1517 | @cindex VxWorks |
1518 | ||
1519 | @value{GDBN} enables developers to spawn and debug tasks running on networked | |
1520 | VxWorks targets from a Unix host. Already-running tasks spawned from | |
1521 | the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on | |
1522 | both the Unix host and on the VxWorks target. The program | |
1523 | @code{gdb} is installed and executed on the Unix host. (It may be | |
1524 | installed with the name @code{vxgdb}, to distinguish it from a | |
1525 | @value{GDBN} for debugging programs on the host itself.) | |
1526 | ||
1527 | @table @code | |
1528 | @item VxWorks-timeout @var{args} | |
1529 | @kindex vxworks-timeout | |
1530 | All VxWorks-based targets now support the option @code{vxworks-timeout}. | |
1531 | This option is set by the user, and @var{args} represents the number of | |
1532 | seconds @value{GDBN} waits for responses to rpc's. You might use this if | |
1533 | your VxWorks target is a slow software simulator or is on the far side | |
1534 | of a thin network line. | |
1535 | @end table | |
1536 | ||
1537 | The following information on connecting to VxWorks was current when | |
1538 | this manual was produced; newer releases of VxWorks may use revised | |
1539 | procedures. | |
1540 | ||
1541 | @kindex INCLUDE_RDB | |
1542 | To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel | |
1543 | to include the remote debugging interface routines in the VxWorks | |
1544 | library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the | |
1545 | VxWorks configuration file @file{configAll.h} and rebuild your VxWorks | |
1546 | kernel. The resulting kernel contains @file{rdb.a}, and spawns the | |
1547 | source debugging task @code{tRdbTask} when VxWorks is booted. For more | |
1548 | information on configuring and remaking VxWorks, see the manufacturer's | |
1549 | manual. | |
1550 | @c VxWorks, see the @cite{VxWorks Programmer's Guide}. | |
1551 | ||
1552 | Once you have included @file{rdb.a} in your VxWorks system image and set | |
1553 | your Unix execution search path to find @value{GDBN}, you are ready to | |
1554 | run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb}, | |
1555 | depending on your installation). | |
1556 | ||
1557 | @value{GDBN} comes up showing the prompt: | |
1558 | ||
1559 | @example | |
1560 | (vxgdb) | |
1561 | @end example | |
1562 | ||
1563 | @menu | |
1564 | * VxWorks Connection:: Connecting to VxWorks | |
1565 | * VxWorks Download:: VxWorks download | |
1566 | * VxWorks Attach:: Running tasks | |
1567 | @end menu | |
1568 | ||
1569 | @node VxWorks Connection | |
1570 | @subsubsection Connecting to VxWorks | |
1571 | ||
1572 | The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the | |
1573 | network. To connect to a target whose host name is ``@code{tt}'', type: | |
1574 | ||
1575 | @example | |
1576 | (vxgdb) target vxworks tt | |
1577 | @end example | |
1578 | ||
1579 | @need 750 | |
1580 | @value{GDBN} displays messages like these: | |
1581 | ||
1582 | @smallexample | |
1583 | Attaching remote machine across net... | |
1584 | Connected to tt. | |
1585 | @end smallexample | |
1586 | ||
1587 | @need 1000 | |
1588 | @value{GDBN} then attempts to read the symbol tables of any object modules | |
1589 | loaded into the VxWorks target since it was last booted. @value{GDBN} locates | |
1590 | these files by searching the directories listed in the command search | |
1591 | path (@pxref{Environment, ,Your program's environment}); if it fails | |
1592 | to find an object file, it displays a message such as: | |
1593 | ||
1594 | @example | |
1595 | prog.o: No such file or directory. | |
1596 | @end example | |
1597 | ||
1598 | When this happens, add the appropriate directory to the search path with | |
1599 | the @value{GDBN} command @code{path}, and execute the @code{target} | |
1600 | command again. | |
1601 | ||
1602 | @node VxWorks Download | |
1603 | @subsubsection VxWorks download | |
1604 | ||
1605 | @cindex download to VxWorks | |
1606 | If you have connected to the VxWorks target and you want to debug an | |
1607 | object that has not yet been loaded, you can use the @value{GDBN} | |
1608 | @code{load} command to download a file from Unix to VxWorks | |
1609 | incrementally. The object file given as an argument to the @code{load} | |
1610 | command is actually opened twice: first by the VxWorks target in order | |
1611 | to download the code, then by @value{GDBN} in order to read the symbol | |
1612 | table. This can lead to problems if the current working directories on | |
1613 | the two systems differ. If both systems have NFS mounted the same | |
1614 | filesystems, you can avoid these problems by using absolute paths. | |
1615 | Otherwise, it is simplest to set the working directory on both systems | |
1616 | to the directory in which the object file resides, and then to reference | |
1617 | the file by its name, without any path. For instance, a program | |
1618 | @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks | |
1619 | and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this | |
1620 | program, type this on VxWorks: | |
1621 | ||
1622 | @example | |
1623 | -> cd "@var{vxpath}/vw/demo/rdb" | |
1624 | @end example | |
1625 | v | |
1626 | Then, in @value{GDBN}, type: | |
1627 | ||
1628 | @example | |
1629 | (vxgdb) cd @var{hostpath}/vw/demo/rdb | |
1630 | (vxgdb) load prog.o | |
1631 | @end example | |
1632 | ||
1633 | @value{GDBN} displays a response similar to this: | |
1634 | ||
1635 | @smallexample | |
1636 | Reading symbol data from wherever/vw/demo/rdb/prog.o... done. | |
1637 | @end smallexample | |
1638 | ||
1639 | You can also use the @code{load} command to reload an object module | |
1640 | after editing and recompiling the corresponding source file. Note that | |
1641 | this makes @value{GDBN} delete all currently-defined breakpoints, | |
1642 | auto-displays, and convenience variables, and to clear the value | |
1643 | history. (This is necessary in order to preserve the integrity of | |
1644 | debugger data structures that reference the target system's symbol | |
1645 | table.) | |
1646 | ||
1647 | @node VxWorks Attach | |
1648 | @subsubsection Running tasks | |
1649 | ||
1650 | @cindex running VxWorks tasks | |
1651 | You can also attach to an existing task using the @code{attach} command as | |
1652 | follows: | |
1653 | ||
1654 | @example | |
1655 | (vxgdb) attach @var{task} | |
1656 | @end example | |
1657 | ||
1658 | @noindent | |
1659 | where @var{task} is the VxWorks hexadecimal task ID. The task can be running | |
1660 | or suspended when you attach to it. Running tasks are suspended at | |
1661 | the time of attachment. | |
c906108c | 1662 | |
c906108c SS |
1663 | @node Sparclet Remote |
1664 | @subsection @value{GDBN} and Sparclet | |
1665 | @cindex Sparclet | |
1666 | ||
1667 | @value{GDBN} enables developers to debug tasks running on | |
1668 | Sparclet targets from a Unix host. | |
1669 | @value{GDBN} uses code that runs on | |
1670 | both the Unix host and on the Sparclet target. The program | |
1671 | @code{gdb} is installed and executed on the Unix host. | |
1672 | ||
1673 | @table @code | |
1674 | @item timeout @var{args} | |
1675 | @kindex remotetimeout | |
1676 | @value{GDBN} now supports the option @code{remotetimeout}. | |
1677 | This option is set by the user, and @var{args} represents the number of | |
1678 | seconds @value{GDBN} waits for responses. | |
1679 | @end table | |
1680 | ||
1681 | @kindex Compiling | |
1682 | When compiling for debugging, include the options "-g" to get debug | |
1683 | information and "-Ttext" to relocate the program to where you wish to | |
1684 | load it on the target. You may also want to add the options "-n" or | |
1685 | "-N" in order to reduce the size of the sections. | |
1686 | ||
1687 | @example | |
1688 | sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N | |
1689 | @end example | |
1690 | ||
1691 | You can use objdump to verify that the addresses are what you intended. | |
1692 | ||
1693 | @example | |
1694 | sparclet-aout-objdump --headers --syms prog | |
1695 | @end example | |
1696 | ||
1697 | @kindex Running | |
1698 | Once you have set | |
1699 | your Unix execution search path to find @value{GDBN}, you are ready to | |
1700 | run @value{GDBN}. From your Unix host, run @code{gdb} | |
1701 | (or @code{sparclet-aout-gdb}, depending on your installation). | |
1702 | ||
1703 | @value{GDBN} comes up showing the prompt: | |
1704 | ||
1705 | @example | |
1706 | (gdbslet) | |
1707 | @end example | |
1708 | ||
1709 | @menu | |
1710 | * Sparclet File:: Setting the file to debug | |
1711 | * Sparclet Connection:: Connecting to Sparclet | |
1712 | * Sparclet Download:: Sparclet download | |
1713 | * Sparclet Execution:: Running and debugging | |
1714 | @end menu | |
1715 | ||
1716 | @node Sparclet File | |
1717 | @subsubsection Setting file to debug | |
1718 | ||
1719 | The @value{GDBN} command @code{file} lets you choose with program to debug. | |
1720 | ||
1721 | @example | |
1722 | (gdbslet) file prog | |
1723 | @end example | |
1724 | ||
1725 | @need 1000 | |
1726 | @value{GDBN} then attempts to read the symbol table of @file{prog}. | |
1727 | @value{GDBN} locates | |
1728 | the file by searching the directories listed in the command search | |
1729 | path. | |
1730 | If the file was compiled with debug information (option "-g"), source | |
1731 | files will be searched as well. | |
1732 | @value{GDBN} locates | |
1733 | the source files by searching the directories listed in the directory search | |
1734 | path (@pxref{Environment, ,Your program's environment}). | |
1735 | If it fails | |
1736 | to find a file, it displays a message such as: | |
1737 | ||
1738 | @example | |
1739 | prog: No such file or directory. | |
1740 | @end example | |
1741 | ||
1742 | When this happens, add the appropriate directories to the search paths with | |
1743 | the @value{GDBN} commands @code{path} and @code{dir}, and execute the | |
1744 | @code{target} command again. | |
1745 | ||
1746 | @node Sparclet Connection | |
1747 | @subsubsection Connecting to Sparclet | |
1748 | ||
1749 | The @value{GDBN} command @code{target} lets you connect to a Sparclet target. | |
1750 | To connect to a target on serial port ``@code{ttya}'', type: | |
1751 | ||
1752 | @example | |
1753 | (gdbslet) target sparclet /dev/ttya | |
1754 | Remote target sparclet connected to /dev/ttya | |
1755 | main () at ../prog.c:3 | |
1756 | @end example | |
1757 | ||
1758 | @need 750 | |
1759 | @value{GDBN} displays messages like these: | |
1760 | ||
1761 | @smallexample | |
1762 | Connected to ttya. | |
1763 | @end smallexample | |
1764 | ||
1765 | @node Sparclet Download | |
1766 | @subsubsection Sparclet download | |
1767 | ||
1768 | @cindex download to Sparclet | |
1769 | Once connected to the Sparclet target, | |
1770 | you can use the @value{GDBN} | |
1771 | @code{load} command to download the file from the host to the target. | |
1772 | The file name and load offset should be given as arguments to the @code{load} | |
1773 | command. | |
1774 | Since the file format is aout, the program must be loaded to the starting | |
1775 | address. You can use objdump to find out what this value is. The load | |
1776 | offset is an offset which is added to the VMA (virtual memory address) | |
1777 | of each of the file's sections. | |
1778 | For instance, if the program | |
1779 | @file{prog} was linked to text address 0x1201000, with data at 0x12010160 | |
1780 | and bss at 0x12010170, in @value{GDBN}, type: | |
1781 | ||
1782 | @example | |
1783 | (gdbslet) load prog 0x12010000 | |
1784 | Loading section .text, size 0xdb0 vma 0x12010000 | |
1785 | @end example | |
1786 | ||
1787 | If the code is loaded at a different address then what the program was linked | |
1788 | to, you may need to use the @code{section} and @code{add-symbol-file} commands | |
1789 | to tell @value{GDBN} where to map the symbol table. | |
1790 | ||
1791 | @node Sparclet Execution | |
1792 | @subsubsection Running and debugging | |
1793 | ||
1794 | @cindex running and debugging Sparclet programs | |
1795 | You can now begin debugging the task using @value{GDBN}'s execution control | |
1796 | commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} | |
1797 | manual for the list of commands. | |
1798 | ||
1799 | @example | |
1800 | (gdbslet) b main | |
1801 | Breakpoint 1 at 0x12010000: file prog.c, line 3. | |
1802 | (gdbslet) run | |
1803 | Starting program: prog | |
1804 | Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 | |
1805 | 3 char *symarg = 0; | |
1806 | (gdbslet) step | |
1807 | 4 char *execarg = "hello!"; | |
1808 | (gdbslet) | |
1809 | @end example | |
1810 | ||
c906108c SS |
1811 | @node Hitachi Remote |
1812 | @subsection @value{GDBN} and Hitachi microprocessors | |
1813 | @value{GDBN} needs to know these things to talk to your | |
1814 | Hitachi SH, H8/300, or H8/500: | |
1815 | ||
1816 | @enumerate | |
1817 | @item | |
1818 | that you want to use @samp{target hms}, the remote debugging interface | |
1819 | for Hitachi microprocessors, or @samp{target e7000}, the in-circuit | |
1820 | emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is | |
1821 | the default when GDB is configured specifically for the Hitachi SH, | |
1822 | H8/300, or H8/500.) | |
1823 | ||
1824 | @item | |
1825 | what serial device connects your host to your Hitachi board (the first | |
1826 | serial device available on your host is the default). | |
1827 | ||
c906108c SS |
1828 | @item |
1829 | what speed to use over the serial device. | |
c906108c SS |
1830 | @end enumerate |
1831 | ||
1832 | @menu | |
1833 | * Hitachi Boards:: Connecting to Hitachi boards. | |
1834 | * Hitachi ICE:: Using the E7000 In-Circuit Emulator. | |
1835 | * Hitachi Special:: Special @value{GDBN} commands for Hitachi micros. | |
1836 | @end menu | |
1837 | ||
1838 | @node Hitachi Boards | |
1839 | @subsubsection Connecting to Hitachi boards | |
1840 | ||
c906108c SS |
1841 | @c only for Unix hosts |
1842 | @kindex device | |
1843 | @cindex serial device, Hitachi micros | |
1844 | Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you | |
1845 | need to explicitly set the serial device. The default @var{port} is the | |
1846 | first available port on your host. This is only necessary on Unix | |
1847 | hosts, where it is typically something like @file{/dev/ttya}. | |
1848 | ||
1849 | @kindex speed | |
1850 | @cindex serial line speed, Hitachi micros | |
1851 | @code{@value{GDBP}} has another special command to set the communications | |
1852 | speed: @samp{speed @var{bps}}. This command also is only used from Unix | |
1853 | hosts; on DOS hosts, set the line speed as usual from outside GDB with | |
1854 | the DOS @kbd{mode} command (for instance, @w{@samp{mode | |
1855 | com2:9600,n,8,1,p}} for a 9600 bps connection). | |
1856 | ||
1857 | The @samp{device} and @samp{speed} commands are available only when you | |
1858 | use a Unix host to debug your Hitachi microprocessor programs. If you | |
1859 | use a DOS host, | |
c906108c SS |
1860 | @value{GDBN} depends on an auxiliary terminate-and-stay-resident program |
1861 | called @code{asynctsr} to communicate with the development board | |
1862 | through a PC serial port. You must also use the DOS @code{mode} command | |
1863 | to set up the serial port on the DOS side. | |
1864 | ||
c906108c SS |
1865 | The following sample session illustrates the steps needed to start a |
1866 | program under @value{GDBN} control on an H8/300. The example uses a | |
1867 | sample H8/300 program called @file{t.x}. The procedure is the same for | |
1868 | the Hitachi SH and the H8/500. | |
1869 | ||
1870 | First hook up your development board. In this example, we use a | |
1871 | board attached to serial port @code{COM2}; if you use a different serial | |
1872 | port, substitute its name in the argument of the @code{mode} command. | |
1873 | When you call @code{asynctsr}, the auxiliary comms program used by the | |
1874 | degugger, you give it just the numeric part of the serial port's name; | |
1875 | for example, @samp{asyncstr 2} below runs @code{asyncstr} on | |
1876 | @code{COM2}. | |
1877 | ||
1878 | @example | |
1879 | C:\H8300\TEST> asynctsr 2 | |
1880 | C:\H8300\TEST> mode com2:9600,n,8,1,p | |
1881 | ||
1882 | Resident portion of MODE loaded | |
1883 | ||
1884 | COM2: 9600, n, 8, 1, p | |
1885 | ||
1886 | @end example | |
1887 | ||
1888 | @quotation | |
1889 | @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with | |
1890 | @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to | |
1891 | disable it, or even boot without it, to use @code{asynctsr} to control | |
1892 | your development board. | |
1893 | @end quotation | |
1894 | ||
1895 | @kindex target hms | |
1896 | Now that serial communications are set up, and the development board is | |
1897 | connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with | |
1898 | the name of your program as the argument. @code{@value{GDBP}} prompts | |
1899 | you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special | |
1900 | commands to begin your debugging session: @samp{target hms} to specify | |
1901 | cross-debugging to the Hitachi board, and the @code{load} command to | |
1902 | download your program to the board. @code{load} displays the names of | |
1903 | the program's sections, and a @samp{*} for each 2K of data downloaded. | |
1904 | (If you want to refresh @value{GDBN} data on symbols or on the | |
1905 | executable file without downloading, use the @value{GDBN} commands | |
1906 | @code{file} or @code{symbol-file}. These commands, and @code{load} | |
1907 | itself, are described in @ref{Files,,Commands to specify files}.) | |
1908 | ||
1909 | @smallexample | |
1910 | (eg-C:\H8300\TEST) @value{GDBP} t.x | |
1911 | GDB is free software and you are welcome to distribute copies | |
1912 | of it under certain conditions; type "show copying" to see | |
1913 | the conditions. | |
1914 | There is absolutely no warranty for GDB; type "show warranty" | |
1915 | for details. | |
1916 | GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... | |
1917 | (gdb) target hms | |
1918 | Connected to remote H8/300 HMS system. | |
1919 | (gdb) load t.x | |
1920 | .text : 0x8000 .. 0xabde *********** | |
1921 | .data : 0xabde .. 0xad30 * | |
1922 | .stack : 0xf000 .. 0xf014 * | |
1923 | @end smallexample | |
1924 | ||
1925 | At this point, you're ready to run or debug your program. From here on, | |
1926 | you can use all the usual @value{GDBN} commands. The @code{break} command | |
1927 | sets breakpoints; the @code{run} command starts your program; | |
1928 | @code{print} or @code{x} display data; the @code{continue} command | |
1929 | resumes execution after stopping at a breakpoint. You can use the | |
1930 | @code{help} command at any time to find out more about @value{GDBN} commands. | |
1931 | ||
1932 | Remember, however, that @emph{operating system} facilities aren't | |
1933 | available on your development board; for example, if your program hangs, | |
1934 | you can't send an interrupt---but you can press the @sc{reset} switch! | |
1935 | ||
1936 | Use the @sc{reset} button on the development board | |
1937 | @itemize @bullet | |
1938 | @item | |
1939 | to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has | |
1940 | no way to pass an interrupt signal to the development board); and | |
1941 | ||
1942 | @item | |
1943 | to return to the @value{GDBN} command prompt after your program finishes | |
1944 | normally. The communications protocol provides no other way for @value{GDBN} | |
1945 | to detect program completion. | |
1946 | @end itemize | |
1947 | ||
1948 | In either case, @value{GDBN} sees the effect of a @sc{reset} on the | |
1949 | development board as a ``normal exit'' of your program. | |
c906108c SS |
1950 | |
1951 | @node Hitachi ICE | |
1952 | @subsubsection Using the E7000 in-circuit emulator | |
1953 | ||
1954 | @kindex target e7000 | |
1955 | You can use the E7000 in-circuit emulator to develop code for either the | |
1956 | Hitachi SH or the H8/300H. Use one of these forms of the @samp{target | |
1957 | e7000} command to connect @value{GDBN} to your E7000: | |
1958 | ||
1959 | @table @code | |
1960 | @item target e7000 @var{port} @var{speed} | |
1961 | Use this form if your E7000 is connected to a serial port. The | |
1962 | @var{port} argument identifies what serial port to use (for example, | |
1963 | @samp{com2}). The third argument is the line speed in bits per second | |
1964 | (for example, @samp{9600}). | |
1965 | ||
1966 | @item target e7000 @var{hostname} | |
1967 | If your E7000 is installed as a host on a TCP/IP network, you can just | |
1968 | specify its hostname; @value{GDBN} uses @code{telnet} to connect. | |
1969 | @end table | |
1970 | ||
1971 | @node Hitachi Special | |
1972 | @subsubsection Special @value{GDBN} commands for Hitachi micros | |
1973 | ||
1974 | Some @value{GDBN} commands are available only on the H8/300 or the | |
1975 | H8/500 configurations: | |
1976 | ||
1977 | @table @code | |
1978 | @kindex set machine | |
1979 | @kindex show machine | |
1980 | @item set machine h8300 | |
1981 | @itemx set machine h8300h | |
1982 | Condition @value{GDBN} for one of the two variants of the H8/300 | |
1983 | architecture with @samp{set machine}. You can use @samp{show machine} | |
1984 | to check which variant is currently in effect. | |
1985 | ||
1986 | @kindex set memory @var{mod} | |
1987 | @cindex memory models, H8/500 | |
1988 | @item set memory @var{mod} | |
1989 | @itemx show memory | |
1990 | Specify which H8/500 memory model (@var{mod}) you are using with | |
1991 | @samp{set memory}; check which memory model is in effect with @samp{show | |
1992 | memory}. The accepted values for @var{mod} are @code{small}, | |
1993 | @code{big}, @code{medium}, and @code{compact}. | |
1994 | @end table | |
1995 | ||
c906108c SS |
1996 | @node MIPS Remote |
1997 | @subsection @value{GDBN} and remote MIPS boards | |
1998 | ||
1999 | @cindex MIPS boards | |
2000 | @value{GDBN} can use the MIPS remote debugging protocol to talk to a | |
2001 | MIPS board attached to a serial line. This is available when | |
2002 | you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. | |
2003 | ||
2004 | @need 1000 | |
2005 | Use these @value{GDBN} commands to specify the connection to your target board: | |
2006 | ||
2007 | @table @code | |
2008 | @item target mips @var{port} | |
2009 | @kindex target mips @var{port} | |
2010 | To run a program on the board, start up @code{@value{GDBP}} with the | |
2011 | name of your program as the argument. To connect to the board, use the | |
2012 | command @samp{target mips @var{port}}, where @var{port} is the name of | |
2013 | the serial port connected to the board. If the program has not already | |
2014 | been downloaded to the board, you may use the @code{load} command to | |
2015 | download it. You can then use all the usual @value{GDBN} commands. | |
2016 | ||
2017 | For example, this sequence connects to the target board through a serial | |
2018 | port, and loads and runs a program called @var{prog} through the | |
2019 | debugger: | |
2020 | ||
2021 | @example | |
2022 | host$ @value{GDBP} @var{prog} | |
2023 | GDB is free software and @dots{} | |
2024 | (gdb) target mips /dev/ttyb | |
2025 | (gdb) load @var{prog} | |
2026 | (gdb) run | |
2027 | @end example | |
2028 | ||
2029 | @item target mips @var{hostname}:@var{portnumber} | |
2030 | On some @value{GDBN} host configurations, you can specify a TCP | |
2031 | connection (for instance, to a serial line managed by a terminal | |
2032 | concentrator) instead of a serial port, using the syntax | |
2033 | @samp{@var{hostname}:@var{portnumber}}. | |
2034 | ||
2035 | @item target pmon @var{port} | |
2036 | @kindex target pmon @var{port} | |
2037 | ||
2038 | @item target ddb @var{port} | |
2039 | @kindex target ddb @var{port} | |
2040 | ||
2041 | @item target lsi @var{port} | |
2042 | @kindex target lsi @var{port} | |
2043 | ||
2044 | @end table | |
2045 | ||
2046 | ||
2047 | @noindent | |
2048 | @value{GDBN} also supports these special commands for MIPS targets: | |
2049 | ||
2050 | @table @code | |
2051 | @item set processor @var{args} | |
2052 | @itemx show processor | |
2053 | @kindex set processor @var{args} | |
2054 | @kindex show processor | |
2055 | Use the @code{set processor} command to set the type of MIPS | |
2056 | processor when you want to access processor-type-specific registers. | |
2057 | For example, @code{set processor @var{r3041}} tells @value{GDBN} | |
2058 | to use the CPO registers appropriate for the 3041 chip. | |
2059 | Use the @code{show processor} command to see what MIPS processor @value{GDBN} | |
2060 | is using. Use the @code{info reg} command to see what registers | |
2061 | @value{GDBN} is using. | |
2062 | ||
2063 | @item set mipsfpu double | |
2064 | @itemx set mipsfpu single | |
2065 | @itemx set mipsfpu none | |
2066 | @itemx show mipsfpu | |
2067 | @kindex set mipsfpu | |
2068 | @kindex show mipsfpu | |
2069 | @cindex MIPS remote floating point | |
2070 | @cindex floating point, MIPS remote | |
2071 | If your target board does not support the MIPS floating point | |
2072 | coprocessor, you should use the command @samp{set mipsfpu none} (if you | |
2073 | need this, you may wish to put the command in your @value{GDBINIT} | |
2074 | file). This tells @value{GDBN} how to find the return value of | |
2075 | functions which return floating point values. It also allows | |
2076 | @value{GDBN} to avoid saving the floating point registers when calling | |
2077 | functions on the board. If you are using a floating point coprocessor | |
2078 | with only single precision floating point support, as on the @sc{r4650} | |
2079 | processor, use the command @samp{set mipsfpu single}. The default | |
2080 | double precision floating point coprocessor may be selected using | |
2081 | @samp{set mipsfpu double}. | |
2082 | ||
2083 | In previous versions the only choices were double precision or no | |
2084 | floating point, so @samp{set mipsfpu on} will select double precision | |
2085 | and @samp{set mipsfpu off} will select no floating point. | |
2086 | ||
2087 | As usual, you can inquire about the @code{mipsfpu} variable with | |
2088 | @samp{show mipsfpu}. | |
2089 | ||
2090 | @item set remotedebug @var{n} | |
2091 | @itemx show remotedebug | |
2092 | @kindex set remotedebug | |
2093 | @kindex show remotedebug | |
2094 | @cindex @code{remotedebug}, MIPS protocol | |
2095 | @cindex MIPS @code{remotedebug} protocol | |
2096 | @c FIXME! For this to be useful, you must know something about the MIPS | |
2097 | @c FIXME...protocol. Where is it described? | |
2098 | You can see some debugging information about communications with the board | |
2099 | by setting the @code{remotedebug} variable. If you set it to @code{1} using | |
2100 | @samp{set remotedebug 1}, every packet is displayed. If you set it | |
2101 | to @code{2}, every character is displayed. You can check the current value | |
2102 | at any time with the command @samp{show remotedebug}. | |
2103 | ||
2104 | @item set timeout @var{seconds} | |
2105 | @itemx set retransmit-timeout @var{seconds} | |
2106 | @itemx show timeout | |
2107 | @itemx show retransmit-timeout | |
2108 | @cindex @code{timeout}, MIPS protocol | |
2109 | @cindex @code{retransmit-timeout}, MIPS protocol | |
2110 | @kindex set timeout | |
2111 | @kindex show timeout | |
2112 | @kindex set retransmit-timeout | |
2113 | @kindex show retransmit-timeout | |
2114 | You can control the timeout used while waiting for a packet, in the MIPS | |
2115 | remote protocol, with the @code{set timeout @var{seconds}} command. The | |
2116 | default is 5 seconds. Similarly, you can control the timeout used while | |
2117 | waiting for an acknowledgement of a packet with the @code{set | |
2118 | retransmit-timeout @var{seconds}} command. The default is 3 seconds. | |
2119 | You can inspect both values with @code{show timeout} and @code{show | |
2120 | retransmit-timeout}. (These commands are @emph{only} available when | |
2121 | @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) | |
2122 | ||
2123 | The timeout set by @code{set timeout} does not apply when @value{GDBN} | |
2124 | is waiting for your program to stop. In that case, @value{GDBN} waits | |
2125 | forever because it has no way of knowing how long the program is going | |
2126 | to run before stopping. | |
2127 | @end table | |
c906108c | 2128 | |
c906108c SS |
2129 | @node Simulator |
2130 | @subsection Simulated CPU target | |
2131 | ||
c906108c SS |
2132 | @cindex simulator |
2133 | @cindex simulator, Z8000 | |
2134 | @cindex Z8000 simulator | |
2135 | @cindex simulator, H8/300 or H8/500 | |
2136 | @cindex H8/300 or H8/500 simulator | |
2137 | @cindex simulator, Hitachi SH | |
2138 | @cindex Hitachi SH simulator | |
2139 | @cindex CPU simulator | |
2140 | For some configurations, @value{GDBN} includes a CPU simulator that you | |
2141 | can use instead of a hardware CPU to debug your programs. | |
2142 | Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300, | |
2143 | H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850, | |
2144 | W65, and Z8000. | |
c906108c | 2145 | |
c906108c SS |
2146 | @cindex simulator, Z8000 |
2147 | @cindex Zilog Z8000 simulator | |
2148 | When configured for debugging Zilog Z8000 targets, @value{GDBN} includes | |
2149 | a Z8000 simulator. | |
c906108c | 2150 | |
c906108c SS |
2151 | For the Z8000 family, @samp{target sim} simulates either the Z8002 (the |
2152 | unsegmented variant of the Z8000 architecture) or the Z8001 (the | |
2153 | segmented variant). The simulator recognizes which architecture is | |
2154 | appropriate by inspecting the object code. | |
c906108c SS |
2155 | |
2156 | @table @code | |
2157 | @item target sim @var{args} | |
2158 | @kindex sim | |
2159 | @kindex target sim | |
2160 | Debug programs on a simulated CPU. If the simulator supports setup | |
2161 | options, specify them via @var{args}. | |
2162 | @end table | |
2163 | ||
2164 | @noindent | |
2165 | After specifying this target, you can debug programs for the simulated | |
2166 | CPU in the same style as programs for your host computer; use the | |
2167 | @code{file} command to load a new program image, the @code{run} command | |
2168 | to run your program, and so on. | |
2169 | ||
2170 | As well as making available all the usual machine registers (see | |
2171 | @code{info reg}), the Z8000 simulator provides three additional items | |
2172 | of information as specially named registers: | |
2173 | ||
2174 | @table @code | |
2175 | @item cycles | |
2176 | Counts clock-ticks in the simulator. | |
2177 | ||
2178 | @item insts | |
2179 | Counts instructions run in the simulator. | |
2180 | ||
2181 | @item time | |
2182 | Execution time in 60ths of a second. | |
2183 | @end table | |
2184 | ||
2185 | You can refer to these values in @value{GDBN} expressions with the usual | |
2186 | conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a | |
2187 | conditional breakpoint that suspends only after at least 5000 | |
2188 | simulated clock ticks. | |
c906108c SS |
2189 | |
2190 | @c need to add much more detail about sims! |