Commit | Line | Data |
---|---|---|
919de9a1 | 1 | _dnl__ -*- Texinfo -*- |
1041a570 | 2 | _dnl__ Copyright (c) 1990 1991 1992 Free Software Foundation, Inc. |
919de9a1 | 3 | _dnl__ This file is part of the source for the GDB manual. |
1041a570 RP |
4 | _dnl__ M4 FRAGMENT $Id$ |
5 | _dnl__ This text diverted to "Remote Debugging" section in general case; | |
6 | _dnl__ however, if we're doing a manual specifically for one of these, it | |
7 | _dnl__ belongs up front (in "Getting In and Out" chapter). | |
b21b18e1 RP |
8 | @node Remote Serial |
9 | @subsection The _GDBN__ remote serial protocol | |
10 | ||
11 | @cindex remote serial debugging, overview | |
12 | To debug a program running on another machine (the debugging | |
13 | @dfn{target} machine), you must first arrange for all the usual | |
14 | prerequisites for the program to run by itself. For example, for a C | |
15 | program, you need | |
16 | ||
17 | @enumerate | |
18 | @item | |
19 | A startup routine to set up the C runtime environment; these usually | |
20 | have a name like @file{crt0}. The startup routine may be supplied by | |
21 | your hardware supplier, or you may have to write your own. | |
22 | ||
23 | @item | |
24 | You probably need a C subroutine library to support your program's | |
25 | subroutine calls, notably managing input and output. | |
26 | ||
27 | @item | |
28 | A way of getting your program to the other machine---for example, a | |
29 | download program. These are often supplied by the hardware | |
30 | manufacturer, but you may have to write your own from hardware | |
31 | documentation. | |
32 | @end enumerate | |
33 | ||
34 | The next step is to arrange for your program to use a serial port to | |
35 | communicate with the machine where _GDBN__ is running (the @dfn{host} | |
36 | machine). In general terms, the scheme looks like this: | |
37 | ||
38 | @table @emph | |
39 | @item On the host, | |
40 | _GDBN__ already understands how to use this protocol; when everything | |
41 | else is set up, you can simply use the @samp{target remote} command | |
42 | (@pxref{Targets,,Specifying a Debugging Target}). | |
43 | ||
44 | @item On the target, | |
45 | you must link with your program a few special-purpose subroutines that | |
46 | implement the _GDBN__ remote serial protocol. The file containing these | |
47 | subroutines is called a @dfn{debugging stub}. | |
48 | @end table | |
49 | ||
50 | The debugging stub is specific to the architecture of the remote | |
51 | machine; for example, use @file{sparc-stub.c} to debug programs on | |
52 | @sc{sparc} boards. | |
53 | ||
54 | @cindex remote serial stub list | |
55 | These working remote stubs are distributed with _GDBN__: | |
56 | ||
57 | @c FIXME! verify these... | |
58 | @table @code | |
59 | @item sparc-stub.c | |
60 | @kindex sparc-stub.c | |
61 | For @sc{sparc} architectures. | |
62 | ||
63 | @item m68-stub.c | |
64 | @kindex m68-stub.c | |
65 | For Motorola 680x0 architectures. | |
66 | ||
67 | @item i36-stub.c | |
68 | @kindex i36-stub.c | |
69 | For Intel 386 and compatible architectures. | |
70 | @end table | |
71 | ||
72 | The @file{README} file in the _GDBN__ distribution may list other | |
73 | recently added stubs. | |
74 | ||
75 | @menu | |
76 | * stub contents:: What the stub can do for you | |
77 | * bootstrapping:: What you must do for the stub | |
78 | * debug session:: Putting it all together | |
79 | * protocol:: Outline of the communication protocol | |
80 | @end menu | |
81 | ||
82 | @node stub contents | |
83 | @subsubsection What the stub can do for you | |
84 | ||
85 | @cindex remote serial stub | |
86 | The debugging stub for your architecture supplies these three | |
87 | subroutines: | |
88 | ||
89 | @table @code | |
90 | @item handle_exception | |
91 | @kindex handle_exception | |
92 | @cindex remote serial stub, main routine | |
93 | This is the central workhorse, but your program never calls it | |
94 | explicitly---the setup code arranges for @code{handle_exception} to | |
95 | run when a trap is triggered. | |
96 | ||
97 | @code{handle_exception} takes control when your program stops during | |
98 | execution (for example, on a breakpoint), and mediates communications | |
99 | with _GDBN__ on the host machine. This is where the communications | |
100 | protocol is implemented; @code{handle_exception} acts as the _GDBN__ | |
101 | representative on the target machine; it begins by sending summary | |
102 | information on the state of your program, then continues to execute, | |
103 | retrieving and transmitting any information _GDBN__ needs, until you | |
104 | execute a _GDBN__ command that makes your program resume; at that point, | |
105 | @code{handle_exception} returns control to your own code on the target | |
106 | machine. | |
107 | ||
108 | @item set_debug_traps | |
109 | @kindex set_debug_traps | |
110 | @cindex remote serial stub, initialization | |
111 | You must call this subroutine explicitly near the beginning of your | |
112 | program. This is the routine that arranges to transfer control to | |
113 | @code{handle_exception} when your program stops. | |
114 | ||
115 | @item breakpoint | |
116 | @cindex @code{breakpoint} subroutine, remote | |
117 | Use this auxiliary subroutine to make your program contain a | |
118 | breakpoint. Depending on the particular situation, this may be the only | |
119 | way for _GDBN__ to get control. For instance, if your target | |
120 | machine has some sort of interrupt button, you won't need to call this; | |
121 | pressing the interrupt button will transfer control to | |
122 | @code{handle_exception}---in efect, to _GDBN__. On some machines, | |
123 | simply receiving characters on the serial port may also trigger a trap; | |
124 | again, in that situation, you don't need to call @code{breakpoint} from | |
125 | your own program---simply running @samp{target remote} from the host | |
126 | _GDBN__ session will get control. | |
127 | ||
128 | Call @code{breakpoint} if none of these is true, or if you simply want | |
129 | to make certain your program stops at a predetermined point for the | |
130 | start of your debugging session. | |
131 | ||
132 | @quotation | |
133 | @emph{Warning:} when you set a breakpoint using this subroutine, it's a | |
134 | little harder than usual to restart your program afterwards---because if | |
135 | you simply @code{continue}, you will immediately run into the line of | |
136 | your program that sets the breakpoint! | |
137 | ||
138 | To get past this, adjust the program counter manually to get past the | |
139 | current instruction before issuing the @code{continue} command. For example, | |
140 | ||
141 | @example | |
142 | (_GDBP__) p $pc = 4+$pc | |
143 | ||
144 | FIXME!!! Stu, I suspect I don't have this quite right. | |
145 | Please supply the right incantation... presumably the | |
146 | constant depends on instruction width, BTW? | |
147 | Sample output would be nice too, so I don't have to make | |
148 | up a ridiculous number. | |
149 | ||
150 | Nothing simpler works, right? Frinstance, an ignore count on the | |
151 | continue would just keep stopping at the same place too? | |
152 | ||
153 | Whatta bout $pc++ ---does GDB know the instruction width as a "type" size? | |
154 | ||
155 | (_GDBP__) continue | |
156 | @end example | |
157 | @end quotation | |
158 | @end table | |
159 | ||
160 | @node bootstrapping | |
161 | @subsubsection What you must do for the stub | |
162 | ||
163 | @cindex remote stub, support routines | |
164 | The debugging stubs that come with _GDBN__ are set up for a particular | |
165 | chip architecture, but they have no information about the rest of your | |
166 | debugging target machine. To allow the stub to work, you must supply | |
167 | three special low-level subroutines, and make sure one library routine | |
168 | is available. | |
169 | ||
170 | @table @code | |
171 | @item int getDebugChar() | |
172 | @kindex getDebugChar | |
173 | Write this subroutine to read a single character from the serial port. | |
174 | It may be identical to @code{getchar} for your target system; a | |
175 | different name is used to allow you to distinguish the two if you wish. | |
176 | ||
177 | @item void putDebugChar(int) | |
178 | @kindex putDebugChar | |
179 | Write this subroutine to write a single character to the serial port. | |
180 | It may be identical to @code{putchar} for your target system; a | |
181 | different name is used to allow you to distinguish the two if you wish. | |
182 | ||
183 | @item void flush_i_cache() | |
184 | @kindex flush_i_cache | |
185 | Write this subroutine to flush the instruction cache, if any, on your | |
186 | target machine. If there is no instruction cache, this subroutine may | |
187 | be a no-op. | |
188 | ||
189 | On target machines that have instruction caches, _GDBN__ requires this | |
190 | function to make certain that the state of your program is stable. | |
191 | ||
192 | @item void *memset(void *, int, int) | |
193 | @kindex memset | |
194 | This is the standard library function @code{memset} that sets an area of | |
195 | memory to a known value. If you have one of the free versions of | |
196 | @code{libc.a}, @code{memset} can be found there; otherwise, you must | |
197 | either obtain it from your hardware manufacturer, or write your own. | |
198 | @end table | |
199 | ||
200 | If you do not use the GNU C compiler, you may also need other standard | |
201 | library subroutines; this will vary from one stub to another, but in | |
202 | general the stubs are likely to use any of the common library | |
203 | subroutines which @code{gcc} generates as inline code. | |
204 | ||
205 | ||
206 | @node debug session | |
207 | @subsubsection Putting it all together | |
208 | ||
209 | @cindex remote serial debugging summary | |
210 | In summary, when your program is ready to debug, you must follow these | |
211 | steps. | |
212 | ||
213 | @enumerate | |
214 | @item | |
215 | Make sure you have the supporting low-level routines: | |
216 | @code{getDebugChar}, @code{putDebugChar}, @code{flush_i_cache}, | |
217 | @code{memset}. | |
218 | ||
219 | @item | |
220 | Insert these lines near the top of your program: | |
221 | ||
222 | @example | |
223 | set_debug_traps(); | |
224 | breakpoint(); | |
225 | @end example | |
226 | ||
227 | @item | |
228 | Compile and link together: your program, the _GDBN__ debugging stub for | |
229 | your target architecture, and the supporting subroutines. | |
230 | ||
231 | @item | |
232 | Make sure you have a serial connection between your target machine and | |
233 | the _GDBN__ host, and identify the serial port used for this on the host. | |
234 | ||
235 | @item | |
236 | Download your program to your target machine (or get it there by | |
237 | whatever means the manufacturer provides), and start it. | |
238 | ||
239 | @item | |
240 | To start remote debugging, run _GDBN__ on the host machine, and specify | |
241 | as an executable file the program that is running in the remote machine. | |
242 | This tells _GDBN__ how to find your program's symbols and the contents | |
243 | of its pure text. | |
244 | ||
245 | Then establish communication using the @code{target remote} command. | |
246 | Its argument is the name of the device you're using to control the | |
247 | target machine. For example: | |
248 | ||
249 | @example | |
250 | target remote /dev/ttyb | |
251 | @end example | |
252 | ||
253 | @noindent | |
254 | if the serial line is connected to the device named @file{/dev/ttyb}. | |
255 | @ignore | |
256 | @c this is from the old text, but it doesn't seem to make sense now that I've | |
257 | @c seen an example... pesch 4sep1992 | |
258 | This will stop the remote machine if it is not already stopped. | |
259 | @end ignore | |
260 | ||
261 | @end enumerate | |
262 | ||
263 | Now you can use all the usual commands to examine and change data and to | |
264 | step and continue the remote program. | |
265 | ||
266 | To resume the remote program and stop debugging it, use the @code{detach} | |
267 | command. | |
268 | ||
269 | @node protocol | |
270 | @subsubsection Outline of the communication protocol | |
271 | ||
272 | @cindex debugging stub, example | |
273 | @cindex remote stub, example | |
274 | @cindex stub example, remote debugging | |
275 | The stub files provided with _GDBN__ implement the target side of the | |
276 | communication protocol, and the _GDBN__ side is implemented in the | |
277 | _GDBN__ source file @file{remote.c}. Normally, you can simply allow | |
278 | these subroutines to communicate, and ignore the details. (If you're | |
279 | implementing your own stub file, you can still ignore the details: start | |
280 | with one of the existing stub files. @file{sparc-stub.c} is the best | |
281 | organized, and therefore the easiest to read.) | |
282 | ||
283 | However, there may be occasions when you need to know something about | |
284 | the protocol---for example, if there is only one serial port to your | |
285 | target machine, you might want your program to do something special if | |
286 | it recognizes a packet meant for _GDBN__. | |
287 | ||
288 | @cindex protocol, _GDBN__ remote serial | |
289 | @cindex serial protocol, _GDBN__ remote | |
290 | @cindex remote serial protocol | |
291 | All _GDBN__ commands and responses (other than acknowledgements, which | |
292 | are single characters) are sent as a packet which includes a | |
293 | checksum. A packet is introduced with the character @samp{$}, and ends | |
294 | with the character @samp{#} followed by a two-digit checksum: | |
295 | ||
296 | @example | |
297 | $@var{packet info}#@var{checksum} | |
298 | @end example | |
299 | ||
300 | @cindex checksum, for _GDBN__ remote | |
301 | @noindent | |
302 | @var{checksum} is computed as the modulo 256 sum of the @var{packet | |
303 | info} characters. | |
304 | ||
305 | When either the host or the target machine receives a packet, the first | |
306 | response expected is an acknowledgement: a single character, either | |
307 | @samp{+} (to indicate the package was received correctly) or @samp{-} | |
308 | (to request retransmission). | |
309 | ||
310 | The host (_GDBN__) sends commands, and the target (the debugging stub | |
311 | incorporated in your program) sends data in response. The target also | |
312 | sends data when your program stops. | |
313 | ||
314 | Command packets are distinguished by their first character, which | |
315 | identifies the kind of command. | |
316 | ||
317 | These are the commands currently supported: | |
318 | ||
319 | @table @code | |
320 | @item g | |
321 | Requests the values of CPU registers. | |
322 | ||
323 | @item G | |
324 | Sets the values of CPU registers. | |
325 | ||
326 | @item m@var{addr},@var{count} | |
327 | Read @var{count} bytes at location @var{addr}. | |
328 | ||
329 | @item M@var{addr},@var{count}:@dots{} | |
330 | Write @var{count} bytes at location @var{addr}. | |
331 | ||
332 | @item c | |
333 | @itemx c@var{addr} | |
334 | Resume execution at the current address (or at @var{addr} if supplied). | |
335 | ||
336 | @item s | |
337 | @itemx s@var{addr} | |
338 | Step the target program for one instruction, from either the current | |
339 | program counter or from @var{addr} if supplied. | |
340 | ||
341 | @item k | |
342 | Kill the target program. | |
343 | ||
344 | @item ? | |
345 | Report the most recent signal. To allow you to take advantage of the | |
346 | _GDBN__ signal handling commands, one of the functions of the debugging | |
347 | stub is to report CPU traps as the corresponding POSIX signal values. | |
348 | @end table | |
349 | ||
350 | @kindex set remotedebug | |
351 | @kindex show remotedebug | |
352 | @cindex packets, reporting on stdout | |
353 | @cindex serial connections, debugging | |
354 | If you have trouble with the serial connection, you can use the command | |
355 | @code{set remotedebug}. This makes _GDBN__ report on all packets sent | |
356 | back and forth across the serial line to the remote machine. The | |
357 | packet-debugging information is printed on the _GDBN__ standard output | |
358 | stream. @code{set remotedebug off} turns it off, and @code{show | |
359 | remotedebug} will show you its current state. | |
360 | ||
361 | ||
919de9a1 | 362 | _if__(_I960__) |
4eb4cf57 | 363 | @node i960-Nindy Remote |
919de9a1 RP |
364 | @subsection _GDBN__ with a Remote i960 (Nindy) |
365 | ||
366 | @cindex Nindy | |
367 | @cindex i960 | |
368 | @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When | |
369 | _GDBN__ is configured to control a remote Intel 960 using Nindy, you can | |
370 | tell _GDBN__ how to connect to the 960 in several ways: | |
371 | ||
372 | @itemize @bullet | |
373 | @item | |
374 | Through command line options specifying serial port, version of the | |
375 | Nindy protocol, and communications speed; | |
376 | ||
377 | @item | |
378 | By responding to a prompt on startup; | |
379 | ||
380 | @item | |
381 | By using the @code{target} command at any point during your _GDBN__ | |
1041a570 | 382 | session. @xref{Target Commands, ,Commands for Managing Targets}. |
919de9a1 RP |
383 | |
384 | @end itemize | |
385 | ||
386 | @menu | |
387 | * Nindy Startup:: Startup with Nindy | |
388 | * Nindy Options:: Options for Nindy | |
389 | * Nindy reset:: Nindy Reset Command | |
390 | @end menu | |
391 | ||
4eb4cf57 | 392 | @node Nindy Startup |
919de9a1 RP |
393 | @subsubsection Startup with Nindy |
394 | ||
c7cb8acb | 395 | If you simply start @code{_GDBP__} without using any command-line |
919de9a1 RP |
396 | options, you are prompted for what serial port to use, @emph{before} you |
397 | reach the ordinary _GDBN__ prompt: | |
1041a570 | 398 | |
919de9a1 RP |
399 | @example |
400 | Attach /dev/ttyNN -- specify NN, or "quit" to quit: | |
401 | @end example | |
1041a570 | 402 | |
919de9a1 RP |
403 | @noindent |
404 | Respond to the prompt with whatever suffix (after @samp{/dev/tty}) | |
405 | identifies the serial port you want to use. You can, if you choose, | |
406 | simply start up with no Nindy connection by responding to the prompt | |
407 | with an empty line. If you do this, and later wish to attach to Nindy, | |
1041a570 | 408 | use @code{target} (@pxref{Target Commands, ,Commands for Managing Targets}). |
919de9a1 | 409 | |
4eb4cf57 | 410 | @node Nindy Options |
919de9a1 RP |
411 | @subsubsection Options for Nindy |
412 | ||
413 | These are the startup options for beginning your _GDBN__ session with a | |
414 | Nindy-960 board attached: | |
415 | ||
416 | @table @code | |
417 | @item -r @var{port} | |
418 | Specify the serial port name of a serial interface to be used to connect | |
419 | to the target system. This option is only available when _GDBN__ is | |
420 | configured for the Intel 960 target architecture. You may specify | |
421 | @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a | |
422 | device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique | |
423 | suffix for a specific @code{tty} (e.g. @samp{-r a}). | |
424 | ||
425 | @item -O | |
426 | (An uppercase letter ``O'', not a zero.) Specify that _GDBN__ should use | |
427 | the ``old'' Nindy monitor protocol to connect to the target system. | |
428 | This option is only available when _GDBN__ is configured for the Intel 960 | |
429 | target architecture. | |
430 | ||
431 | @quotation | |
432 | @emph{Warning:} if you specify @samp{-O}, but are actually trying to | |
433 | connect to a target system that expects the newer protocol, the connection | |
434 | will fail, appearing to be a speed mismatch. _GDBN__ will repeatedly | |
435 | attempt to reconnect at several different line speeds. You can abort | |
436 | this process with an interrupt. | |
437 | @end quotation | |
438 | ||
439 | @item -brk | |
440 | Specify that _GDBN__ should first send a @code{BREAK} signal to the target | |
441 | system, in an attempt to reset it, before connecting to a Nindy target. | |
442 | ||
443 | @quotation | |
444 | @emph{Warning:} Many target systems do not have the hardware that this | |
445 | requires; it only works with a few boards. | |
446 | @end quotation | |
919de9a1 RP |
447 | @end table |
448 | ||
449 | The standard @samp{-b} option controls the line speed used on the serial | |
1041a570 | 450 | port. |
919de9a1 | 451 | |
919de9a1 | 452 | @c @group |
4eb4cf57 | 453 | @node Nindy reset |
919de9a1 | 454 | @subsubsection Nindy Reset Command |
1041a570 | 455 | |
919de9a1 RP |
456 | @table @code |
457 | @item reset | |
458 | @kindex reset | |
459 | For a Nindy target, this command sends a ``break'' to the remote target | |
460 | system; this is only useful if the target has been equipped with a | |
461 | circuit to perform a hard reset (or some other interesting action) when | |
462 | a break is detected. | |
463 | @end table | |
464 | @c @end group | |
465 | _fi__(_I960__) | |
466 | ||
467 | _if__(_AMD29K__) | |
4eb4cf57 | 468 | @node EB29K Remote |
919de9a1 RP |
469 | @subsection _GDBN__ with a Remote EB29K |
470 | ||
471 | @cindex EB29K board | |
472 | @cindex running 29K programs | |
473 | ||
474 | To use _GDBN__ from a Unix system to run programs on AMD's EB29K | |
475 | board in a PC, you must first connect a serial cable between the PC | |
476 | and a serial port on the Unix system. In the following, we assume | |
477 | you've hooked the cable between the PC's @file{COM1} port and | |
478 | @file{/dev/ttya} on the Unix system. | |
479 | ||
480 | @menu | |
481 | * Comms (EB29K):: Communications Setup | |
482 | * _GDBP__-EB29K:: EB29K cross-debugging | |
483 | * Remote Log:: Remote Log | |
484 | @end menu | |
485 | ||
4eb4cf57 | 486 | @node Comms (EB29K) |
919de9a1 | 487 | @subsubsection Communications Setup |
1041a570 | 488 | |
919de9a1 RP |
489 | The next step is to set up the PC's port, by doing something like the |
490 | following in DOS on the PC: | |
1041a570 | 491 | |
919de9a1 RP |
492 | _0__@example |
493 | C:\> MODE com1:9600,n,8,1,none | |
494 | _1__@end example | |
1041a570 | 495 | |
919de9a1 RP |
496 | @noindent |
497 | This example---run on an MS DOS 4.0 system---sets the PC port to 9600 | |
498 | bps, no parity, eight data bits, one stop bit, and no ``retry'' action; | |
499 | you must match the communications parameters when establishing the Unix | |
500 | end of the connection as well. | |
501 | @c FIXME: Who knows what this "no retry action" crud from the DOS manual may | |
502 | @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91 | |
503 | ||
504 | To give control of the PC to the Unix side of the serial line, type | |
505 | the following at the DOS console: | |
1041a570 | 506 | |
919de9a1 RP |
507 | _0__@example |
508 | C:\> CTTY com1 | |
509 | _1__@end example | |
1041a570 | 510 | |
919de9a1 RP |
511 | @noindent |
512 | (Later, if you wish to return control to the DOS console, you can use | |
513 | the command @code{CTTY con}---but you must send it over the device that | |
514 | had control, in our example over the @file{COM1} serial line). | |
515 | ||
516 | From the Unix host, use a communications program such as @code{tip} or | |
517 | @code{cu} to communicate with the PC; for example, | |
1041a570 | 518 | |
919de9a1 RP |
519 | @example |
520 | cu -s 9600 -l /dev/ttya | |
521 | @end example | |
1041a570 | 522 | |
919de9a1 RP |
523 | @noindent |
524 | The @code{cu} options shown specify, respectively, the linespeed and the | |
525 | serial port to use. If you use @code{tip} instead, your command line | |
526 | may look something like the following: | |
1041a570 | 527 | |
919de9a1 RP |
528 | @example |
529 | tip -9600 /dev/ttya | |
530 | @end example | |
1041a570 | 531 | |
919de9a1 RP |
532 | @noindent |
533 | Your system may define a different name where our example uses | |
534 | @file{/dev/ttya} as the argument to @code{tip}. The communications | |
1041a570 | 535 | parameters, including which port to use, are associated with the |
919de9a1 RP |
536 | @code{tip} argument in the ``remote'' descriptions file---normally the |
537 | system table @file{/etc/remote}. | |
538 | @c FIXME: What if anything needs doing to match the "n,8,1,none" part of | |
539 | @c the DOS side's comms setup? cu can support -o (odd | |
540 | @c parity), -e (even parity)---apparently no settings for no parity or | |
541 | @c for character size. Taken from stty maybe...? John points out tip | |
542 | @c can set these as internal variables, eg ~s parity=none; man stty | |
543 | @c suggests that it *might* work to stty these options with stdin or | |
544 | @c stdout redirected... ---pesch@cygnus.com, 25feb91 | |
545 | ||
546 | @kindex EBMON | |
547 | Using the @code{tip} or @code{cu} connection, change the DOS working | |
548 | directory to the directory containing a copy of your 29K program, then | |
549 | start the PC program @code{EBMON} (an EB29K control program supplied | |
550 | with your board by AMD). You should see an initial display from | |
551 | @code{EBMON} similar to the one that follows, ending with the | |
552 | @code{EBMON} prompt @samp{#}--- | |
1041a570 | 553 | |
919de9a1 RP |
554 | _0__@example |
555 | C:\> G: | |
556 | ||
557 | G:\> CD \usr\joe\work29k | |
558 | ||
559 | G:\USR\JOE\WORK29K> EBMON | |
560 | Am29000 PC Coprocessor Board Monitor, version 3.0-18 | |
561 | Copyright 1990 Advanced Micro Devices, Inc. | |
562 | Written by Gibbons and Associates, Inc. | |
563 | ||
564 | Enter '?' or 'H' for help | |
565 | ||
566 | PC Coprocessor Type = EB29K | |
567 | I/O Base = 0x208 | |
568 | Memory Base = 0xd0000 | |
569 | ||
570 | Data Memory Size = 2048KB | |
571 | Available I-RAM Range = 0x8000 to 0x1fffff | |
572 | Available D-RAM Range = 0x80002000 to 0x801fffff | |
573 | ||
574 | PageSize = 0x400 | |
575 | Register Stack Size = 0x800 | |
576 | Memory Stack Size = 0x1800 | |
577 | ||
578 | CPU PRL = 0x3 | |
579 | Am29027 Available = No | |
580 | Byte Write Available = Yes | |
581 | ||
582 | # ~. | |
583 | _1__@end example | |
584 | ||
585 | Then exit the @code{cu} or @code{tip} program (done in the example by | |
586 | typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep | |
587 | running, ready for _GDBN__ to take over. | |
588 | ||
589 | For this example, we've assumed what is probably the most convenient | |
590 | way to make sure the same 29K program is on both the PC and the Unix | |
591 | system: a PC/NFS connection that establishes ``drive @code{G:}'' on the | |
1041a570 | 592 | PC as a file system on the Unix host. If you do not have PC/NFS or |
919de9a1 RP |
593 | something similar connecting the two systems, you must arrange some |
594 | other way---perhaps floppy-disk transfer---of getting the 29K program | |
595 | from the Unix system to the PC; _GDBN__ will @emph{not} download it over the | |
596 | serial line. | |
597 | ||
4eb4cf57 | 598 | @node _GDBP__-EB29K |
919de9a1 | 599 | @subsubsection EB29K cross-debugging |
1041a570 | 600 | |
919de9a1 RP |
601 | Finally, @code{cd} to the directory containing an image of your 29K |
602 | program on the Unix system, and start _GDBN__---specifying as argument the | |
603 | name of your 29K program: | |
1041a570 | 604 | |
919de9a1 RP |
605 | @example |
606 | cd /usr/joe/work29k | |
607 | _GDBP__ myfoo | |
608 | @end example | |
1041a570 | 609 | |
919de9a1 | 610 | Now you can use the @code{target} command: |
1041a570 | 611 | |
919de9a1 RP |
612 | @example |
613 | target amd-eb /dev/ttya 9600 MYFOO | |
919de9a1 RP |
614 | @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to |
615 | @c emphasize that this is the name as seen by DOS (since I think DOS is | |
616 | @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91 | |
1041a570 | 617 | @end example |
919de9a1 RP |
618 | |
619 | @noindent | |
620 | In this example, we've assumed your program is in a file called | |
621 | @file{myfoo}. Note that the filename given as the last argument to | |
622 | @code{target amd-eb} should be the name of the program as it appears to DOS. | |
623 | In our example this is simply @code{MYFOO}, but in general it can include | |
624 | a DOS path, and depending on your transfer mechanism may not resemble | |
625 | the name on the Unix side. | |
626 | ||
1041a570 | 627 | At this point, you can set any breakpoints you wish; when you are ready |
919de9a1 RP |
628 | to see your program run on the 29K board, use the _GDBN__ command |
629 | @code{run}. | |
630 | ||
631 | To stop debugging the remote program, use the _GDBN__ @code{detach} | |
1041a570 | 632 | command. |
919de9a1 RP |
633 | |
634 | To return control of the PC to its console, use @code{tip} or @code{cu} | |
635 | once again, after your _GDBN__ session has concluded, to attach to | |
636 | @code{EBMON}. You can then type the command @code{q} to shut down | |
637 | @code{EBMON}, returning control to the DOS command-line interpreter. | |
638 | Type @code{CTTY con} to return command input to the main DOS console, | |
639 | and type @kbd{~.} to leave @code{tip} or @code{cu}. | |
640 | ||
4eb4cf57 | 641 | @node Remote Log |
919de9a1 RP |
642 | @subsubsection Remote Log |
643 | @kindex eb.log | |
644 | @cindex log file for EB29K | |
1041a570 | 645 | |
919de9a1 RP |
646 | The @code{target amd-eb} command creates a file @file{eb.log} in the |
647 | current working directory, to help debug problems with the connection. | |
648 | @file{eb.log} records all the output from @code{EBMON}, including echoes | |
649 | of the commands sent to it. Running @samp{tail -f} on this file in | |
650 | another window often helps to understand trouble with @code{EBMON}, or | |
651 | unexpected events on the PC side of the connection. | |
652 | _fi__(_AMD29K__) | |
653 | ||
654 | _if__(_VXWORKS__) | |
4eb4cf57 | 655 | @node VxWorks Remote |
919de9a1 RP |
656 | @subsection _GDBN__ and VxWorks |
657 | @cindex VxWorks | |
1041a570 | 658 | |
919de9a1 RP |
659 | _GDBN__ enables developers to spawn and debug tasks running on networked |
660 | VxWorks targets from a Unix host. Already-running tasks spawned from | |
661 | the VxWorks shell can also be debugged. _GDBN__ uses code that runs on | |
662 | both the UNIX host and on the VxWorks target. The program | |
1041a570 | 663 | @code{_GDBP__} is installed and executed on the UNIX host. |
919de9a1 | 664 | |
9941f866 RP |
665 | The following information on connecting to VxWorks was current when |
666 | this manual was produced; newer releases of VxWorks may use revised | |
667 | procedures. | |
668 | ||
919de9a1 RP |
669 | The remote debugging interface (RDB) routines are installed and executed |
670 | on the VxWorks target. These routines are included in the VxWorks library | |
671 | @file{rdb.a} and are incorporated into the system image when source-level | |
672 | debugging is enabled in the VxWorks configuration. | |
673 | ||
674 | @kindex INCLUDE_RDB | |
1041a570 RP |
675 | If you wish, you can define @code{INCLUDE_RDB} in the VxWorks |
676 | configuration file @file{configAll.h} to include the RDB interface | |
677 | routines and spawn the source debugging task @code{tRdbTask} when | |
678 | VxWorks is booted. For more information on configuring and remaking | |
679 | _if__(_FSF__) | |
680 | VxWorks, see the manufacturer's manual. | |
681 | _fi__(_FSF__) | |
682 | _if__(!_FSF__) | |
683 | VxWorks, see the @cite{VxWorks Programmer's Guide}. | |
684 | _fi__(!_FSF__) | |
919de9a1 RP |
685 | |
686 | Once you have included the RDB interface in your VxWorks system image | |
687 | and set your Unix execution search path to find _GDBN__, you are ready | |
688 | to run _GDBN__. From your UNIX host, type: | |
689 | ||
690 | @smallexample | |
691 | % _GDBP__ | |
692 | @end smallexample | |
693 | ||
694 | _GDBN__ will come up showing the prompt: | |
695 | ||
696 | @smallexample | |
697 | (_GDBP__) | |
698 | @end smallexample | |
699 | ||
700 | @menu | |
701 | * VxWorks connection:: Connecting to VxWorks | |
702 | * VxWorks download:: VxWorks Download | |
703 | * VxWorks attach:: Running Tasks | |
704 | @end menu | |
705 | ||
4eb4cf57 | 706 | @node VxWorks connection |
919de9a1 RP |
707 | @subsubsection Connecting to VxWorks |
708 | ||
709 | The _GDBN__ command @code{target} lets you connect to a VxWorks target on the | |
710 | network. To connect to a target whose host name is ``@code{tt}'', type: | |
711 | ||
712 | @smallexample | |
713 | (_GDBP__) target vxworks tt | |
714 | @end smallexample | |
715 | ||
716 | _GDBN__ will display a message similar to the following: | |
717 | ||
718 | @smallexample | |
719 | Attaching remote machine across net... Success! | |
720 | @end smallexample | |
721 | ||
1041a570 RP |
722 | _GDBN__ will then attempt to read the symbol tables of any object modules |
723 | loaded into the VxWorks target since it was last booted. _GDBN__ locates | |
724 | these files by searching the directories listed in the command search | |
725 | path (@pxref{Environment, ,Your Program's Environment}); if it fails | |
726 | to find an object file, it will display a message such as: | |
919de9a1 RP |
727 | |
728 | @smallexample | |
729 | prog.o: No such file or directory. | |
730 | @end smallexample | |
731 | ||
732 | This will cause the @code{target} command to abort. When this happens, | |
733 | you should add the appropriate directory to the search path, with the | |
734 | _GDBN__ command @code{path}, and execute the @code{target} command | |
735 | again. | |
736 | ||
4eb4cf57 | 737 | @node VxWorks download |
919de9a1 RP |
738 | @subsubsection VxWorks Download |
739 | ||
740 | @cindex download to VxWorks | |
741 | If you have connected to the VxWorks target and you want to debug an | |
742 | object that has not yet been loaded, you can use the _GDBN__ @code{load} | |
743 | command to download a file from UNIX to VxWorks incrementally. The | |
744 | object file given as an argument to the @code{load} command is actually | |
745 | opened twice: first by the VxWorks target in order to download the code, | |
746 | then by _GDBN__ in order to read the symbol table. This can lead to | |
747 | problems if the current working directories on the two systems differ. | |
748 | It is simplest to set the working directory on both systems to the | |
749 | directory in which the object file resides, and then to reference the | |
750 | file by its name, without any path. Thus, to load a program | |
751 | @file{prog.o}, residing in @file{wherever/vw/demo/rdb}, on VxWorks type: | |
752 | ||
753 | @smallexample | |
754 | -> cd "wherever/vw/demo/rdb" | |
755 | @end smallexample | |
756 | ||
757 | On _GDBN__ type: | |
758 | ||
759 | @smallexample | |
760 | (_GDBP__) cd wherever/vw/demo/rdb | |
761 | (_GDBP__) load prog.o | |
762 | @end smallexample | |
763 | ||
764 | _GDBN__ will display a response similar to the following: | |
765 | ||
766 | @smallexample | |
767 | Reading symbol data from wherever/vw/demo/rdb/prog.o... done. | |
768 | @end smallexample | |
769 | ||
770 | You can also use the @code{load} command to reload an object module | |
771 | after editing and recompiling the corresponding source file. Note that | |
772 | this will cause _GDBN__ to delete all currently-defined breakpoints, | |
773 | auto-displays, and convenience variables, and to clear the value | |
774 | history. (This is necessary in order to preserve the integrity of | |
775 | debugger data structures that reference the target system's symbol | |
776 | table.) | |
777 | ||
4eb4cf57 | 778 | @node VxWorks attach |
919de9a1 RP |
779 | @subsubsection Running Tasks |
780 | ||
781 | @cindex running VxWorks tasks | |
782 | You can also attach to an existing task using the @code{attach} command as | |
783 | follows: | |
784 | ||
785 | @smallexample | |
786 | (_GDBP__) attach @var{task} | |
787 | @end smallexample | |
788 | ||
1041a570 | 789 | @noindent |
919de9a1 RP |
790 | where @var{task} is the VxWorks hexadecimal task ID. The task can be running |
791 | or suspended when you attach to it. If running, it will be suspended at | |
792 | the time of attachment. | |
919de9a1 | 793 | _fi__(_VXWORKS__) |
4eb4cf57 | 794 | |
c7cb8acb | 795 | _if__(_H8__) |
4eb4cf57 | 796 | @node Hitachi H8/300 Remote |
c7cb8acb | 797 | @subsection _GDBN__ and the Hitachi H8/300 |
4eb4cf57 | 798 | _GDBN__ needs to know these things to talk to your H8/300: |
c7cb8acb RP |
799 | |
800 | @enumerate | |
801 | @item | |
802 | that you want to use @samp{target hms}, the remote debugging | |
4eb4cf57 RP |
803 | interface for the H8/300 (this is the default when |
804 | GDB is configured specifically for the H8/300); | |
c7cb8acb RP |
805 | |
806 | @item | |
807 | what serial device connects your host to your H8/300 (the first serial | |
808 | device available on your host is the default); | |
809 | ||
4eb4cf57 RP |
810 | @ignore |
811 | @c this is only for Unix hosts, not currently of interest. | |
c7cb8acb RP |
812 | @item |
813 | what speed to use over the serial device. | |
4eb4cf57 | 814 | @end ignore |
c7cb8acb RP |
815 | @end enumerate |
816 | ||
817 | @kindex device | |
818 | @cindex serial device for H8/300 | |
4eb4cf57 RP |
819 | @ignore |
820 | @c only for Unix hosts | |
a89f94c2 RP |
821 | Use the special @code{gdb83} command @samp{device @var{port}} if you |
822 | need to explicitly set the serial device. The default @var{port} is the | |
823 | first available port on your host. This is only necessary on Unix | |
824 | hosts, where it is typically something like @file{/dev/ttya}. | |
825 | ||
c7cb8acb RP |
826 | @kindex speed |
827 | @cindex serial line speed for H8/300 | |
828 | @code{gdb83} has another special command to set the communications speed | |
a89f94c2 RP |
829 | for the H8/300: @samp{speed @var{bps}}. This command also is only used |
830 | from Unix hosts; on DOS hosts, set the line speed as usual from outside | |
831 | GDB with the DOS @kbd{mode} command (for instance, @w{@samp{mode | |
832 | com2:9600,n,8,1,p}} for a 9600 bps connection). | |
4eb4cf57 RP |
833 | @end ignore |
834 | ||
835 | _GDBN__ depends on an auxiliary terminate-and-stay-resident program | |
836 | called @code{asynctsr} to communicate with the H8/300 development board | |
837 | through a PC serial port. You must also use the DOS @code{mode} command | |
838 | to set up the serial port on the DOS side. | |
839 | ||
840 | The following sample session illustrates the steps needed to start a | |
841 | program under _GDBN__ control on your H8/300. The example uses a sample | |
842 | H8/300 program called @file{t.x}. | |
843 | ||
844 | First hook up your H8/300 development board. In this example, we use a | |
845 | board attached to serial port @code{COM2}; if you use a different serial | |
846 | port, substitute its name in the argument of the @code{mode} command. | |
847 | When you call @code{asynctsr}, the auxiliary comms program used by the | |
848 | degugger, you give it just the numeric part of the serial port's name; | |
849 | for example, @samp{asyncstr 2} below runs @code{asyncstr} on | |
850 | @code{COM2}. | |
851 | ||
0005054f | 852 | @smallexample |
4eb4cf57 | 853 | (eg-C:\H8300\TEST) mode com2:9600,n,8,1,p |
c7cb8acb | 854 | |
4eb4cf57 | 855 | Resident portion of MODE loaded |
c7cb8acb | 856 | |
4eb4cf57 | 857 | COM2: 9600, n, 8, 1, p |
c7cb8acb | 858 | |
4eb4cf57 | 859 | (eg-C:\H8300\TEST) asynctsr 2 |
0005054f | 860 | @end smallexample |
4eb4cf57 RP |
861 | |
862 | @quotation | |
863 | @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with | |
864 | @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to | |
865 | disable it, or even boot without it, to use @code{asynctsr} to control | |
866 | your H8/300 board. | |
867 | @end quotation | |
c7cb8acb | 868 | |
4eb4cf57 RP |
869 | Now that serial communications are set up, and the H8/300 is connected, |
870 | you can start up _GDBN__. Call @code{_GDBP__} with the name of your | |
871 | program as the argument. @code{_GDBP__} prompts you, as usual, with the | |
872 | prompt @samp{(_GDBP__)}. Use two special commands to begin your debugging | |
873 | session: @samp{target hms} to specify cross-debugging to the Hitachi board, | |
874 | and the @code{load} command to download your program to the board. | |
875 | @code{load} displays the names of the | |
876 | program's sections, and a @samp{*} for each 2K of data downloaded. (If | |
877 | you want to refresh _GDBN__ data on symbols or on the executable file | |
878 | without downloading, use the _GDBN__ commands @code{file} or | |
879 | @code{symbol-file}. These commands, and @code{load} itself, are | |
880 | described in @ref{Files,,Commands to Specify Files}.) | |
881 | ||
0005054f | 882 | @smallexample |
4eb4cf57 RP |
883 | (eg-C:\H8300\TEST) _GDBP__ t.x |
884 | GDB is free software and you are welcome to distribute copies | |
885 | of it under certain conditions; type "show copying" to see | |
886 | the conditions. | |
887 | There is absolutely no warranty for GDB; type "show warranty" | |
888 | for details. | |
889 | GDB _GDB_VN__, Copyright 1992 Free Software Foundation, Inc... | |
890 | (gdb) target hms | |
891 | Connected to remote H8/300 HMS system. | |
892 | (gdb) load t.x | |
893 | .text : 0x8000 .. 0xabde *********** | |
894 | .data : 0xabde .. 0xad30 * | |
895 | .stack : 0xf000 .. 0xf014 * | |
0005054f | 896 | @end smallexample |
c7cb8acb | 897 | |
4eb4cf57 RP |
898 | At this point, you're ready to run or debug your program. From here on, |
899 | you can use all the usual _GDBN__ commands. The @code{break} command | |
900 | sets breakpoints; the @code{run} command starts your program; | |
901 | @code{print} or @code{x} display data; the @code{continue} command | |
902 | resumes execution after stopping at a breakpoint. You can use the | |
903 | @code{help} command at any time to find out more about _GDBN__ commands. | |
c7cb8acb RP |
904 | |
905 | Remember, however, that @emph{operating system} facilities aren't | |
906 | available on your H8/300; for example, if your program hangs, you can't | |
4eb4cf57 RP |
907 | send an interrupt---but you can press the @sc{reset} switch! |
908 | ||
909 | Use the @sc{reset} button on the H8/300 board | |
910 | @itemize @bullet | |
911 | @item | |
912 | to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has | |
913 | no way to pass an interrupt signal to the H8/300); and | |
914 | ||
915 | @item | |
916 | to return to the _GDBN__ command prompt after your program finishes | |
917 | normally. The communications protocol provides no other way for _GDBN__ | |
918 | to detect program completion. | |
919 | @end itemize | |
920 | ||
921 | In either case, _GDBN__ will see the effect of a @sc{reset} on the | |
922 | H8/300 board as a ``normal exit'' of your program. | |
c7cb8acb | 923 | _fi__(_H8__) |