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