Commit | Line | Data |
---|---|---|
18fae2a8 RP |
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. | |
4 | @c This text diverted to "Remote Debugging" section in general case; | |
5 | @c however, if we're doing a manual specifically for one of these, it | |
6 | @c belongs up front (in "Getting In and Out" chapter). | |
18fae2a8 | 7 | |
ed447b95 | 8 | @ifset REMOTESTUB |
18fae2a8 RP |
9 | @node Remote Serial |
10 | @subsection The @value{GDBN} remote serial protocol | |
11 | ||
12 | @cindex remote serial debugging, overview | |
13 | To debug a program running on another machine (the debugging | |
14 | @dfn{target} machine), you must first arrange for all the usual | |
15 | prerequisites for the program to run by itself. For example, for a C | |
16 | program, you need | |
17 | ||
18 | @enumerate | |
19 | @item | |
20 | A startup routine to set up the C runtime environment; these usually | |
21 | have a name like @file{crt0}. The startup routine may be supplied by | |
22 | your hardware supplier, or you may have to write your own. | |
23 | ||
24 | @item | |
25 | You probably need a C subroutine library to support your program's | |
26 | subroutine calls, notably managing input and output. | |
27 | ||
28 | @item | |
29 | A way of getting your program to the other machine---for example, a | |
30 | download program. These are often supplied by the hardware | |
31 | manufacturer, but you may have to write your own from hardware | |
32 | documentation. | |
33 | @end enumerate | |
34 | ||
35 | The next step is to arrange for your program to use a serial port to | |
36 | communicate with the machine where @value{GDBN} is running (the @dfn{host} | |
37 | machine). In general terms, the scheme looks like this: | |
38 | ||
39 | @table @emph | |
40 | @item On the host, | |
41 | @value{GDBN} already understands how to use this protocol; when everything | |
42 | else is set up, you can simply use the @samp{target remote} command | |
43 | (@pxref{Targets,,Specifying a Debugging Target}). | |
44 | ||
45 | @item On the target, | |
46 | you must link with your program a few special-purpose subroutines that | |
47 | implement the @value{GDBN} remote serial protocol. The file containing these | |
48 | subroutines is called a @dfn{debugging stub}. | |
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 | ||
18fae2a8 RP |
58 | @table @code |
59 | @item sparc-stub.c | |
60 | @kindex sparc-stub.c | |
61 | For @sc{sparc} architectures. | |
62 | ||
63 | @item m68k-stub.c | |
49f09e18 JK |
64 | @kindex m68k-stub.c |
65 | @kindex Motorola 680x0 | |
66 | @kindex 680x0 | |
18fae2a8 RP |
67 | For Motorola 680x0 architectures. |
68 | ||
69 | @item i386-stub.c | |
49f09e18 JK |
70 | @kindex i386-stub.c |
71 | @kindex Intel | |
72 | @kindex 386 | |
18fae2a8 RP |
73 | For Intel 386 and compatible architectures. |
74 | @end table | |
75 | ||
76 | The @file{README} file in the @value{GDBN} distribution may list other | |
77 | recently added stubs. | |
78 | ||
79 | @menu | |
ed447b95 RP |
80 | * Stub Contents:: What the stub can do for you |
81 | * Bootstrapping:: What you must do for the stub | |
82 | * Debug Session:: Putting it all together | |
83 | * Protocol:: Outline of the communication protocol | |
18fae2a8 RP |
84 | @end menu |
85 | ||
ed447b95 | 86 | @node Stub Contents |
18fae2a8 RP |
87 | @subsubsection What the stub can do for you |
88 | ||
89 | @cindex remote serial stub | |
90 | The debugging stub for your architecture supplies these three | |
91 | subroutines: | |
92 | ||
93 | @table @code | |
94 | @item set_debug_traps | |
95 | @kindex set_debug_traps | |
96 | @cindex remote serial stub, initialization | |
8c69096b RP |
97 | This routine arranges for @code{handle_exception} to run when your |
98 | program stops. You must call this subroutine explicitly near the | |
99 | beginning of your program. | |
18fae2a8 RP |
100 | |
101 | @item handle_exception | |
102 | @kindex handle_exception | |
103 | @cindex remote serial stub, main routine | |
104 | This is the central workhorse, but your program never calls it | |
105 | explicitly---the setup code arranges for @code{handle_exception} to | |
106 | run when a trap is triggered. | |
107 | ||
108 | @code{handle_exception} takes control when your program stops during | |
109 | execution (for example, on a breakpoint), and mediates communications | |
110 | with @value{GDBN} on the host machine. This is where the communications | |
111 | protocol is implemented; @code{handle_exception} acts as the @value{GDBN} | |
112 | representative on the target machine; it begins by sending summary | |
113 | information on the state of your program, then continues to execute, | |
114 | retrieving and transmitting any information @value{GDBN} needs, until you | |
115 | execute a @value{GDBN} command that makes your program resume; at that point, | |
116 | @code{handle_exception} returns control to your own code on the target | |
117 | machine. | |
118 | ||
119 | @item breakpoint | |
120 | @cindex @code{breakpoint} subroutine, remote | |
121 | Use this auxiliary subroutine to make your program contain a | |
122 | breakpoint. Depending on the particular situation, this may be the only | |
123 | way for @value{GDBN} to get control. For instance, if your target | |
124 | machine has some sort of interrupt button, you won't need to call this; | |
125 | pressing the interrupt button will transfer control to | |
d55320a0 | 126 | @code{handle_exception}---in effect, to @value{GDBN}. On some machines, |
18fae2a8 RP |
127 | simply receiving characters on the serial port may also trigger a trap; |
128 | again, in that situation, you don't need to call @code{breakpoint} from | |
129 | your own program---simply running @samp{target remote} from the host | |
130 | @value{GDBN} session will get control. | |
131 | ||
132 | Call @code{breakpoint} if none of these is true, or if you simply want | |
133 | to make certain your program stops at a predetermined point for the | |
134 | start of your debugging session. | |
135 | @end table | |
136 | ||
ed447b95 | 137 | @node Bootstrapping |
18fae2a8 RP |
138 | @subsubsection What you must do for the stub |
139 | ||
140 | @cindex remote stub, support routines | |
141 | The debugging stubs that come with @value{GDBN} are set up for a particular | |
142 | chip architecture, but they have no information about the rest of your | |
143 | debugging target machine. To allow the stub to work, you must supply | |
144 | these special low-level subroutines: | |
145 | ||
146 | @table @code | |
147 | @item int getDebugChar() | |
148 | @kindex getDebugChar | |
149 | Write this subroutine to read a single character from the serial port. | |
150 | It may be identical to @code{getchar} for your target system; a | |
151 | different name is used to allow you to distinguish the two if you wish. | |
152 | ||
153 | @item void putDebugChar(int) | |
154 | @kindex putDebugChar | |
155 | Write this subroutine to write a single character to the serial port. | |
156 | It may be identical to @code{putchar} for your target system; a | |
157 | different name is used to allow you to distinguish the two if you wish. | |
158 | ||
159 | @item void flush_i_cache() | |
160 | @kindex flush_i_cache | |
161 | Write this subroutine to flush the instruction cache, if any, on your | |
162 | target machine. If there is no instruction cache, this subroutine may | |
163 | be a no-op. | |
164 | ||
165 | On target machines that have instruction caches, @value{GDBN} requires this | |
166 | function to make certain that the state of your program is stable. | |
167 | @end table | |
168 | ||
169 | @noindent | |
170 | You must also make sure this library routine is available: | |
171 | ||
172 | @table @code | |
173 | @item void *memset(void *, int, int) | |
174 | @kindex memset | |
175 | This is the standard library function @code{memset} that sets an area of | |
176 | memory to a known value. If you have one of the free versions of | |
177 | @code{libc.a}, @code{memset} can be found there; otherwise, you must | |
178 | either obtain it from your hardware manufacturer, or write your own. | |
179 | @end table | |
180 | ||
181 | If you do not use the GNU C compiler, you may need other standard | |
182 | library subroutines as well; this will vary from one stub to another, | |
183 | but in general the stubs are likely to use any of the common library | |
184 | subroutines which @code{gcc} generates as inline code. | |
185 | ||
186 | ||
ed447b95 | 187 | @node Debug Session |
18fae2a8 RP |
188 | @subsubsection Putting it all together |
189 | ||
190 | @cindex remote serial debugging summary | |
191 | In summary, when your program is ready to debug, you must follow these | |
192 | steps. | |
193 | ||
194 | @enumerate | |
195 | @item | |
196 | Make sure you have the supporting low-level routines: | |
8c69096b RP |
197 | @display |
198 | @code{getDebugChar}, @code{putDebugChar}, | |
199 | @code{flush_i_cache}, @code{memset}. | |
200 | @end display | |
18fae2a8 RP |
201 | |
202 | @item | |
203 | Insert these lines near the top of your program: | |
204 | ||
205 | @example | |
206 | set_debug_traps(); | |
207 | breakpoint(); | |
208 | @end example | |
209 | ||
49f09e18 JK |
210 | @item |
211 | For the 680x0 stub only, you need to provide a variable called | |
d55320a0 | 212 | @code{exceptionHook}. Normally you just use |
49f09e18 JK |
213 | |
214 | @example | |
215 | void (*exceptionHook)() = 0; | |
216 | @end example | |
217 | ||
d55320a0 RP |
218 | but if before calling @code{set_debug_traps}, you set it to point to a |
219 | function in your program, that function is called when | |
220 | @code{@value{GDBN}} continues after stopping on a trap (for example, bus | |
221 | error). The function indicated by @code{exceptionHook} is called with | |
222 | one parameter: an @code{int} which is the exception number. | |
49f09e18 | 223 | |
18fae2a8 RP |
224 | @item |
225 | Compile and link together: your program, the @value{GDBN} debugging stub for | |
226 | your target architecture, and the supporting subroutines. | |
227 | ||
228 | @item | |
229 | Make sure you have a serial connection between your target machine and | |
230 | the @value{GDBN} host, and identify the serial port used for this on the host. | |
231 | ||
232 | @item | |
233 | Download your program to your target machine (or get it there by | |
234 | whatever means the manufacturer provides), and start it. | |
235 | ||
236 | @item | |
237 | To start remote debugging, run @value{GDBN} on the host machine, and specify | |
238 | as an executable file the program that is running in the remote machine. | |
239 | This tells @value{GDBN} how to find your program's symbols and the contents | |
240 | of its pure text. | |
241 | ||
242 | Then establish communication using the @code{target remote} command. | |
243 | Its argument is the name of the device you're using to control the | |
244 | target machine. For example: | |
245 | ||
246 | @example | |
247 | target remote /dev/ttyb | |
248 | @end example | |
249 | ||
250 | @noindent | |
251 | if the serial line is connected to the device named @file{/dev/ttyb}. | |
252 | @ignore | |
253 | @c this is from the old text, but it doesn't seem to make sense now that I've | |
254 | @c seen an example... pesch 4sep1992 | |
255 | This will stop the remote machine if it is not already stopped. | |
256 | @end ignore | |
18fae2a8 RP |
257 | @end enumerate |
258 | ||
259 | Now you can use all the usual commands to examine and change data and to | |
260 | step and continue the remote program. | |
261 | ||
262 | To resume the remote program and stop debugging it, use the @code{detach} | |
263 | command. | |
264 | ||
c5f69ff8 RP |
265 | @cindex interrupting remote programs |
266 | @cindex remote programs, interrupting | |
267 | Whenever @value{GDBN} is waiting for the remote program, if you type the | |
268 | interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the | |
269 | program. This may or may not succeed, depending in part on the hardware | |
270 | and the serial drivers the remote system uses. If you type the | |
271 | interrupt character once again, @value{GDBN} displays this prompt: | |
272 | ||
273 | @example | |
274 | Interrupted while waiting for the program. | |
275 | Give up (and stop debugging it)? (y or n) | |
276 | @end example | |
277 | ||
278 | If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. | |
279 | (If you decide you want to try again later, you can use @samp{target | |
280 | remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} | |
281 | goes back to waiting. | |
282 | ||
ed447b95 | 283 | @node Protocol |
18fae2a8 RP |
284 | @subsubsection Outline of the communication protocol |
285 | ||
286 | @cindex debugging stub, example | |
287 | @cindex remote stub, example | |
288 | @cindex stub example, remote debugging | |
289 | The stub files provided with @value{GDBN} implement the target side of the | |
290 | communication protocol, and the @value{GDBN} side is implemented in the | |
291 | @value{GDBN} source file @file{remote.c}. Normally, you can simply allow | |
292 | these subroutines to communicate, and ignore the details. (If you're | |
293 | implementing your own stub file, you can still ignore the details: start | |
294 | with one of the existing stub files. @file{sparc-stub.c} is the best | |
295 | organized, and therefore the easiest to read.) | |
296 | ||
297 | However, there may be occasions when you need to know something about | |
298 | the protocol---for example, if there is only one serial port to your | |
299 | target machine, you might want your program to do something special if | |
300 | it recognizes a packet meant for @value{GDBN}. | |
301 | ||
302 | @cindex protocol, @value{GDBN} remote serial | |
303 | @cindex serial protocol, @value{GDBN} remote | |
304 | @cindex remote serial protocol | |
305 | All @value{GDBN} commands and responses (other than acknowledgements, which | |
306 | are single characters) are sent as a packet which includes a | |
307 | checksum. A packet is introduced with the character @samp{$}, and ends | |
308 | with the character @samp{#} followed by a two-digit checksum: | |
309 | ||
310 | @example | |
311 | $@var{packet info}#@var{checksum} | |
312 | @end example | |
313 | ||
314 | @cindex checksum, for @value{GDBN} remote | |
315 | @noindent | |
316 | @var{checksum} is computed as the modulo 256 sum of the @var{packet | |
317 | info} characters. | |
318 | ||
319 | When either the host or the target machine receives a packet, the first | |
320 | response expected is an acknowledgement: a single character, either | |
321 | @samp{+} (to indicate the package was received correctly) or @samp{-} | |
322 | (to request retransmission). | |
323 | ||
324 | The host (@value{GDBN}) sends commands, and the target (the debugging stub | |
325 | incorporated in your program) sends data in response. The target also | |
326 | sends data when your program stops. | |
327 | ||
328 | Command packets are distinguished by their first character, which | |
329 | identifies the kind of command. | |
330 | ||
331 | These are the commands currently supported: | |
332 | ||
333 | @table @code | |
334 | @item g | |
335 | Requests the values of CPU registers. | |
336 | ||
337 | @item G | |
338 | Sets the values of CPU registers. | |
339 | ||
340 | @item m@var{addr},@var{count} | |
341 | Read @var{count} bytes at location @var{addr}. | |
342 | ||
343 | @item M@var{addr},@var{count}:@dots{} | |
344 | Write @var{count} bytes at location @var{addr}. | |
345 | ||
346 | @item c | |
347 | @itemx c@var{addr} | |
348 | Resume execution at the current address (or at @var{addr} if supplied). | |
349 | ||
350 | @item s | |
351 | @itemx s@var{addr} | |
352 | Step the target program for one instruction, from either the current | |
353 | program counter or from @var{addr} if supplied. | |
354 | ||
355 | @item k | |
356 | Kill the target program. | |
357 | ||
358 | @item ? | |
359 | Report the most recent signal. To allow you to take advantage of the | |
360 | @value{GDBN} signal handling commands, one of the functions of the debugging | |
361 | stub is to report CPU traps as the corresponding POSIX signal values. | |
362 | @end table | |
363 | ||
364 | @kindex set remotedebug | |
365 | @kindex show remotedebug | |
366 | @cindex packets, reporting on stdout | |
367 | @cindex serial connections, debugging | |
368 | If you have trouble with the serial connection, you can use the command | |
369 | @code{set remotedebug}. This makes @value{GDBN} report on all packets sent | |
370 | back and forth across the serial line to the remote machine. The | |
371 | packet-debugging information is printed on the @value{GDBN} standard output | |
372 | stream. @code{set remotedebug off} turns it off, and @code{show | |
373 | remotedebug} will show you its current state. | |
374 | @end ifset | |
375 | ||
a64a6c2b | 376 | @ifset I960 |
18fae2a8 | 377 | @node i960-Nindy Remote |
93928b60 | 378 | @subsection @value{GDBN} with a remote i960 (Nindy) |
18fae2a8 RP |
379 | |
380 | @cindex Nindy | |
381 | @cindex i960 | |
382 | @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When | |
383 | @value{GDBN} is configured to control a remote Intel 960 using Nindy, you can | |
384 | tell @value{GDBN} how to connect to the 960 in several ways: | |
385 | ||
386 | @itemize @bullet | |
387 | @item | |
388 | Through command line options specifying serial port, version of the | |
389 | Nindy protocol, and communications speed; | |
390 | ||
391 | @item | |
392 | By responding to a prompt on startup; | |
393 | ||
394 | @item | |
395 | By using the @code{target} command at any point during your @value{GDBN} | |
93928b60 | 396 | session. @xref{Target Commands, ,Commands for managing targets}. |
18fae2a8 RP |
397 | |
398 | @end itemize | |
399 | ||
400 | @menu | |
401 | * Nindy Startup:: Startup with Nindy | |
402 | * Nindy Options:: Options for Nindy | |
ed447b95 | 403 | * Nindy Reset:: Nindy reset command |
18fae2a8 RP |
404 | @end menu |
405 | ||
406 | @node Nindy Startup | |
407 | @subsubsection Startup with Nindy | |
408 | ||
409 | If you simply start @code{@value{GDBP}} without using any command-line | |
410 | options, you are prompted for what serial port to use, @emph{before} you | |
411 | reach the ordinary @value{GDBN} prompt: | |
412 | ||
413 | @example | |
414 | Attach /dev/ttyNN -- specify NN, or "quit" to quit: | |
415 | @end example | |
416 | ||
417 | @noindent | |
418 | Respond to the prompt with whatever suffix (after @samp{/dev/tty}) | |
419 | identifies the serial port you want to use. You can, if you choose, | |
420 | simply start up with no Nindy connection by responding to the prompt | |
ed447b95 | 421 | with an empty line. If you do this and later wish to attach to Nindy, |
93928b60 | 422 | use @code{target} (@pxref{Target Commands, ,Commands for managing targets}). |
18fae2a8 RP |
423 | |
424 | @node Nindy Options | |
425 | @subsubsection Options for Nindy | |
426 | ||
427 | These are the startup options for beginning your @value{GDBN} session with a | |
428 | Nindy-960 board attached: | |
429 | ||
430 | @table @code | |
431 | @item -r @var{port} | |
432 | Specify the serial port name of a serial interface to be used to connect | |
433 | to the target system. This option is only available when @value{GDBN} is | |
434 | configured for the Intel 960 target architecture. You may specify | |
435 | @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a | |
436 | device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique | |
437 | suffix for a specific @code{tty} (e.g. @samp{-r a}). | |
438 | ||
439 | @item -O | |
440 | (An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use | |
441 | the ``old'' Nindy monitor protocol to connect to the target system. | |
442 | This option is only available when @value{GDBN} is configured for the Intel 960 | |
443 | target architecture. | |
444 | ||
445 | @quotation | |
446 | @emph{Warning:} if you specify @samp{-O}, but are actually trying to | |
447 | connect to a target system that expects the newer protocol, the connection | |
34ae25cd RP |
448 | fails, appearing to be a speed mismatch. @value{GDBN} repeatedly |
449 | attempts to reconnect at several different line speeds. You can abort | |
18fae2a8 RP |
450 | this process with an interrupt. |
451 | @end quotation | |
452 | ||
453 | @item -brk | |
454 | Specify that @value{GDBN} should first send a @code{BREAK} signal to the target | |
455 | system, in an attempt to reset it, before connecting to a Nindy target. | |
456 | ||
457 | @quotation | |
458 | @emph{Warning:} Many target systems do not have the hardware that this | |
459 | requires; it only works with a few boards. | |
460 | @end quotation | |
461 | @end table | |
462 | ||
463 | The standard @samp{-b} option controls the line speed used on the serial | |
464 | port. | |
465 | ||
466 | @c @group | |
ed447b95 | 467 | @node Nindy Reset |
93928b60 | 468 | @subsubsection Nindy reset command |
18fae2a8 RP |
469 | |
470 | @table @code | |
471 | @item reset | |
472 | @kindex reset | |
473 | For a Nindy target, this command sends a ``break'' to the remote target | |
474 | system; this is only useful if the target has been equipped with a | |
475 | circuit to perform a hard reset (or some other interesting action) when | |
476 | a break is detected. | |
477 | @end table | |
478 | @c @end group | |
479 | @end ifset | |
480 | ||
a64a6c2b | 481 | @ifset AMD29K |
fe715d06 RP |
482 | @node UDI29K Remote |
483 | @subsection @value{GDBN} and the UDI protocol for AMD29K | |
484 | ||
485 | @cindex UDI | |
486 | @cindex AMD29K via UDI | |
487 | @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'') | |
d7d35f00 | 488 | protocol for debugging the a29k processor family. To use this |
fe715d06 RP |
489 | configuration with AMD targets running the MiniMON monitor, you need the |
490 | program @code{MONTIP}, available from AMD at no charge. You can also | |
d7d35f00 | 491 | use @value{GDBN} with the UDI conformant a29k simulator program |
fe715d06 RP |
492 | @code{ISSTIP}, also available from AMD. |
493 | ||
494 | @table @code | |
495 | @item target udi @var{keyword} | |
496 | @kindex udi | |
d7d35f00 | 497 | Select the UDI interface to a remote a29k board or simulator, where |
fe715d06 RP |
498 | @var{keyword} is an entry in the AMD configuration file @file{udi_soc}. |
499 | This file contains keyword entries which specify parameters used to | |
d7d35f00 | 500 | connect to a29k targets. If the @file{udi_soc} file is not in your |
fe715d06 RP |
501 | working directory, you must set the environment variable @samp{UDICONF} |
502 | to its pathname. | |
503 | @end table | |
504 | ||
18fae2a8 | 505 | @node EB29K Remote |
d55320a0 | 506 | @subsection @value{GDBN} and the EBMON protocol for AMD29K |
18fae2a8 RP |
507 | |
508 | @cindex EB29K board | |
509 | @cindex running 29K programs | |
510 | ||
d55320a0 RP |
511 | AMD distributes a 29K development board meant to fit in a PC, together |
512 | with a DOS-hosted monitor program called @code{EBMON}. As a shorthand | |
513 | term, this development system is called the ``EB29K''. To use | |
514 | @value{GDBN} from a Unix system to run programs on the EB29K board, you | |
515 | must first connect a serial cable between the PC (which hosts the EB29K | |
516 | board) and a serial port on the Unix system. In the following, we | |
517 | assume you've hooked the cable between the PC's @file{COM1} port and | |
18fae2a8 RP |
518 | @file{/dev/ttya} on the Unix system. |
519 | ||
520 | @menu | |
ed447b95 | 521 | * Comms (EB29K):: Communications setup |
18fae2a8 | 522 | * gdb-EB29K:: EB29K cross-debugging |
ed447b95 | 523 | * Remote Log:: Remote log |
18fae2a8 RP |
524 | @end menu |
525 | ||
526 | @node Comms (EB29K) | |
93928b60 | 527 | @subsubsection Communications setup |
18fae2a8 | 528 | |
ed447b95 RP |
529 | The next step is to set up the PC's port, by doing something like this |
530 | in DOS on the PC: | |
18fae2a8 RP |
531 | |
532 | @example | |
533 | C:\> MODE com1:9600,n,8,1,none | |
534 | @end example | |
535 | ||
536 | @noindent | |
537 | This example---run on an MS DOS 4.0 system---sets the PC port to 9600 | |
538 | bps, no parity, eight data bits, one stop bit, and no ``retry'' action; | |
539 | you must match the communications parameters when establishing the Unix | |
540 | end of the connection as well. | |
541 | @c FIXME: Who knows what this "no retry action" crud from the DOS manual may | |
542 | @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91 | |
543 | ||
544 | To give control of the PC to the Unix side of the serial line, type | |
545 | the following at the DOS console: | |
546 | ||
547 | @example | |
548 | C:\> CTTY com1 | |
549 | @end example | |
550 | ||
551 | @noindent | |
552 | (Later, if you wish to return control to the DOS console, you can use | |
553 | the command @code{CTTY con}---but you must send it over the device that | |
554 | had control, in our example over the @file{COM1} serial line). | |
555 | ||
556 | From the Unix host, use a communications program such as @code{tip} or | |
557 | @code{cu} to communicate with the PC; for example, | |
558 | ||
559 | @example | |
560 | cu -s 9600 -l /dev/ttya | |
561 | @end example | |
562 | ||
563 | @noindent | |
564 | The @code{cu} options shown specify, respectively, the linespeed and the | |
565 | serial port to use. If you use @code{tip} instead, your command line | |
566 | may look something like the following: | |
567 | ||
568 | @example | |
569 | tip -9600 /dev/ttya | |
570 | @end example | |
571 | ||
572 | @noindent | |
fe715d06 | 573 | Your system may require a different name where we show |
18fae2a8 RP |
574 | @file{/dev/ttya} as the argument to @code{tip}. The communications |
575 | parameters, including which port to use, are associated with the | |
576 | @code{tip} argument in the ``remote'' descriptions file---normally the | |
577 | system table @file{/etc/remote}. | |
578 | @c FIXME: What if anything needs doing to match the "n,8,1,none" part of | |
579 | @c the DOS side's comms setup? cu can support -o (odd | |
580 | @c parity), -e (even parity)---apparently no settings for no parity or | |
581 | @c for character size. Taken from stty maybe...? John points out tip | |
582 | @c can set these as internal variables, eg ~s parity=none; man stty | |
583 | @c suggests that it *might* work to stty these options with stdin or | |
584 | @c stdout redirected... ---pesch@cygnus.com, 25feb91 | |
585 | ||
586 | @kindex EBMON | |
587 | Using the @code{tip} or @code{cu} connection, change the DOS working | |
588 | directory to the directory containing a copy of your 29K program, then | |
589 | start the PC program @code{EBMON} (an EB29K control program supplied | |
590 | with your board by AMD). You should see an initial display from | |
591 | @code{EBMON} similar to the one that follows, ending with the | |
592 | @code{EBMON} prompt @samp{#}--- | |
593 | ||
594 | @example | |
595 | C:\> G: | |
596 | ||
597 | G:\> CD \usr\joe\work29k | |
598 | ||
599 | G:\USR\JOE\WORK29K> EBMON | |
600 | Am29000 PC Coprocessor Board Monitor, version 3.0-18 | |
601 | Copyright 1990 Advanced Micro Devices, Inc. | |
602 | Written by Gibbons and Associates, Inc. | |
603 | ||
604 | Enter '?' or 'H' for help | |
605 | ||
606 | PC Coprocessor Type = EB29K | |
607 | I/O Base = 0x208 | |
608 | Memory Base = 0xd0000 | |
609 | ||
610 | Data Memory Size = 2048KB | |
611 | Available I-RAM Range = 0x8000 to 0x1fffff | |
612 | Available D-RAM Range = 0x80002000 to 0x801fffff | |
613 | ||
614 | PageSize = 0x400 | |
615 | Register Stack Size = 0x800 | |
616 | Memory Stack Size = 0x1800 | |
617 | ||
618 | CPU PRL = 0x3 | |
619 | Am29027 Available = No | |
620 | Byte Write Available = Yes | |
621 | ||
622 | # ~. | |
623 | @end example | |
624 | ||
625 | Then exit the @code{cu} or @code{tip} program (done in the example by | |
626 | typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep | |
627 | running, ready for @value{GDBN} to take over. | |
628 | ||
629 | For this example, we've assumed what is probably the most convenient | |
630 | way to make sure the same 29K program is on both the PC and the Unix | |
631 | system: a PC/NFS connection that establishes ``drive @code{G:}'' on the | |
632 | PC as a file system on the Unix host. If you do not have PC/NFS or | |
633 | something similar connecting the two systems, you must arrange some | |
634 | other way---perhaps floppy-disk transfer---of getting the 29K program | |
635 | from the Unix system to the PC; @value{GDBN} will @emph{not} download it over the | |
636 | serial line. | |
637 | ||
638 | @node gdb-EB29K | |
639 | @subsubsection EB29K cross-debugging | |
640 | ||
641 | Finally, @code{cd} to the directory containing an image of your 29K | |
642 | program on the Unix system, and start @value{GDBN}---specifying as argument the | |
643 | name of your 29K program: | |
644 | ||
645 | @example | |
646 | cd /usr/joe/work29k | |
647 | @value{GDBP} myfoo | |
648 | @end example | |
649 | ||
650 | Now you can use the @code{target} command: | |
651 | ||
652 | @example | |
653 | target amd-eb /dev/ttya 9600 MYFOO | |
654 | @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to | |
655 | @c emphasize that this is the name as seen by DOS (since I think DOS is | |
656 | @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91 | |
657 | @end example | |
658 | ||
659 | @noindent | |
660 | In this example, we've assumed your program is in a file called | |
661 | @file{myfoo}. Note that the filename given as the last argument to | |
662 | @code{target amd-eb} should be the name of the program as it appears to DOS. | |
663 | In our example this is simply @code{MYFOO}, but in general it can include | |
664 | a DOS path, and depending on your transfer mechanism may not resemble | |
665 | the name on the Unix side. | |
666 | ||
667 | At this point, you can set any breakpoints you wish; when you are ready | |
668 | to see your program run on the 29K board, use the @value{GDBN} command | |
669 | @code{run}. | |
670 | ||
671 | To stop debugging the remote program, use the @value{GDBN} @code{detach} | |
672 | command. | |
673 | ||
674 | To return control of the PC to its console, use @code{tip} or @code{cu} | |
675 | once again, after your @value{GDBN} session has concluded, to attach to | |
676 | @code{EBMON}. You can then type the command @code{q} to shut down | |
677 | @code{EBMON}, returning control to the DOS command-line interpreter. | |
678 | Type @code{CTTY con} to return command input to the main DOS console, | |
679 | and type @kbd{~.} to leave @code{tip} or @code{cu}. | |
680 | ||
681 | @node Remote Log | |
93928b60 | 682 | @subsubsection Remote log |
18fae2a8 RP |
683 | @kindex eb.log |
684 | @cindex log file for EB29K | |
685 | ||
686 | The @code{target amd-eb} command creates a file @file{eb.log} in the | |
687 | current working directory, to help debug problems with the connection. | |
688 | @file{eb.log} records all the output from @code{EBMON}, including echoes | |
689 | of the commands sent to it. Running @samp{tail -f} on this file in | |
690 | another window often helps to understand trouble with @code{EBMON}, or | |
691 | unexpected events on the PC side of the connection. | |
692 | ||
693 | @end ifset | |
694 | ||
a64a6c2b | 695 | @ifset ST2000 |
18fae2a8 RP |
696 | @node ST2000 Remote |
697 | @subsection @value{GDBN} with a Tandem ST2000 | |
698 | ||
699 | To connect your ST2000 to the host system, see the manufacturer's | |
700 | manual. Once the ST2000 is physically attached, you can run | |
701 | ||
702 | @example | |
703 | target st2000 @var{dev} @var{speed} | |
704 | @end example | |
705 | ||
706 | @noindent | |
707 | to establish it as your debugging environment. | |
708 | ||
709 | The @code{load} and @code{attach} commands are @emph{not} defined for | |
710 | this target; you must load your program into the ST2000 as you normally | |
711 | would for standalone operation. @value{GDBN} will read debugging information | |
712 | (such as symbols) from a separate, debugging version of the program | |
713 | available on your host computer. | |
714 | @c FIXME!! This is terribly vague; what little content is here is | |
715 | @c basically hearsay. | |
716 | ||
717 | @cindex ST2000 auxiliary commands | |
718 | These auxiliary @value{GDBN} commands are available to help you with the ST2000 | |
719 | environment: | |
720 | ||
721 | @table @code | |
722 | @item st2000 @var{command} | |
723 | @kindex st2000 @var{cmd} | |
724 | @cindex STDBUG commands (ST2000) | |
725 | @cindex commands to STDBUG (ST2000) | |
726 | Send a @var{command} to the STDBUG monitor. See the manufacturer's | |
727 | manual for available commands. | |
728 | ||
729 | @item connect | |
730 | @cindex connect (to STDBUG) | |
731 | Connect the controlling terminal to the STDBUG command monitor. When | |
732 | you are done interacting with STDBUG, typing either of two character | |
733 | sequences will get you back to the @value{GDBN} command prompt: | |
734 | @kbd{@key{RET}~.} (Return, followed by tilde and period) or | |
735 | @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). | |
736 | @end table | |
737 | @end ifset | |
738 | ||
739 | @ifset VXWORKS | |
740 | @node VxWorks Remote | |
741 | @subsection @value{GDBN} and VxWorks | |
742 | @cindex VxWorks | |
743 | ||
744 | @value{GDBN} enables developers to spawn and debug tasks running on networked | |
745 | VxWorks targets from a Unix host. Already-running tasks spawned from | |
746 | the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on | |
747 | both the UNIX host and on the VxWorks target. The program | |
d55320a0 RP |
748 | @code{gdb} is installed and executed on the UNIX host. (It may be |
749 | installed with the name @code{vxgdb}, to distinguish it from a | |
750 | @value{GDBN} for debugging programs on the host itself.) | |
18fae2a8 RP |
751 | |
752 | The following information on connecting to VxWorks was current when | |
753 | this manual was produced; newer releases of VxWorks may use revised | |
754 | procedures. | |
755 | ||
756 | The remote debugging interface (RDB) routines are installed and executed | |
757 | on the VxWorks target. These routines are included in the VxWorks library | |
758 | @file{rdb.a} and are incorporated into the system image when source-level | |
759 | debugging is enabled in the VxWorks configuration. | |
760 | ||
761 | @kindex INCLUDE_RDB | |
762 | If you wish, you can define @code{INCLUDE_RDB} in the VxWorks | |
763 | configuration file @file{configAll.h} to include the RDB interface | |
764 | routines and spawn the source debugging task @code{tRdbTask} when | |
765 | VxWorks is booted. For more information on configuring and remaking | |
766 | VxWorks, see the manufacturer's manual. | |
767 | @c VxWorks, see the @cite{VxWorks Programmer's Guide}. | |
768 | ||
769 | Once you have included the RDB interface in your VxWorks system image | |
770 | and set your Unix execution search path to find @value{GDBN}, you are ready | |
d55320a0 RP |
771 | to run @value{GDBN}. From your UNIX host, run @code{gdb} (or |
772 | @code{vxgdb}, depending on your installation). | |
18fae2a8 | 773 | |
d55320a0 | 774 | @value{GDBN} comes up showing the prompt: |
18fae2a8 | 775 | |
ed447b95 | 776 | @example |
d55320a0 | 777 | (vxgdb) |
ed447b95 | 778 | @end example |
18fae2a8 RP |
779 | |
780 | @menu | |
ed447b95 RP |
781 | * VxWorks Connection:: Connecting to VxWorks |
782 | * VxWorks Download:: VxWorks download | |
783 | * VxWorks Attach:: Running tasks | |
18fae2a8 RP |
784 | @end menu |
785 | ||
ed447b95 | 786 | @node VxWorks Connection |
18fae2a8 RP |
787 | @subsubsection Connecting to VxWorks |
788 | ||
789 | The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the | |
790 | network. To connect to a target whose host name is ``@code{tt}'', type: | |
791 | ||
ed447b95 | 792 | @example |
d55320a0 | 793 | (vxgdb) target vxworks tt |
ed447b95 | 794 | @end example |
18fae2a8 | 795 | |
d55320a0 | 796 | @value{GDBN} displays messages like these: |
18fae2a8 RP |
797 | |
798 | @smallexample | |
d55320a0 RP |
799 | Attaching remote machine across net... |
800 | Connected to tt. | |
18fae2a8 RP |
801 | @end smallexample |
802 | ||
d55320a0 | 803 | @value{GDBN} then attempts to read the symbol tables of any object modules |
18fae2a8 RP |
804 | loaded into the VxWorks target since it was last booted. @value{GDBN} locates |
805 | these files by searching the directories listed in the command search | |
93928b60 | 806 | path (@pxref{Environment, ,Your program's environment}); if it fails |
d55320a0 | 807 | to find an object file, it displays a message such as: |
18fae2a8 | 808 | |
ed447b95 | 809 | @example |
18fae2a8 | 810 | prog.o: No such file or directory. |
ed447b95 | 811 | @end example |
18fae2a8 | 812 | |
d55320a0 RP |
813 | When this happens, add the appropriate directory to the search path with |
814 | the @value{GDBN} command @code{path}, and execute the @code{target} | |
815 | command again. | |
18fae2a8 | 816 | |
ed447b95 | 817 | @node VxWorks Download |
93928b60 | 818 | @subsubsection VxWorks download |
18fae2a8 RP |
819 | |
820 | @cindex download to VxWorks | |
821 | If you have connected to the VxWorks target and you want to debug an | |
d55320a0 RP |
822 | object that has not yet been loaded, you can use the @value{GDBN} |
823 | @code{load} command to download a file from UNIX to VxWorks | |
824 | incrementally. The object file given as an argument to the @code{load} | |
825 | command is actually opened twice: first by the VxWorks target in order | |
826 | to download the code, then by @value{GDBN} in order to read the symbol | |
827 | table. This can lead to problems if the current working directories on | |
828 | the two systems differ. If both systems have NFS mounted the same | |
829 | filesystems, you can avoid these problems by using absolute paths. | |
830 | Otherwise, it is simplest to set the working directory on both systems | |
831 | to the directory in which the object file resides, and then to reference | |
832 | the file by its name, without any path. For instance, a program | |
833 | @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks | |
834 | and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this | |
835 | program, type this on VxWorks: | |
18fae2a8 | 836 | |
ed447b95 | 837 | @example |
d55320a0 | 838 | -> cd "@var{vxpath}/vw/demo/rdb" |
ed447b95 | 839 | @end example |
18fae2a8 | 840 | |
d55320a0 | 841 | Then, in @value{GDBN}, type: |
18fae2a8 | 842 | |
ed447b95 | 843 | @example |
d55320a0 RP |
844 | (vxgdb) cd @var{hostpath}/vw/demo/rdb |
845 | (vxgdb) load prog.o | |
ed447b95 | 846 | @end example |
18fae2a8 | 847 | |
d55320a0 | 848 | @value{GDBN} displays a response similar to this: |
18fae2a8 RP |
849 | |
850 | @smallexample | |
851 | Reading symbol data from wherever/vw/demo/rdb/prog.o... done. | |
852 | @end smallexample | |
853 | ||
854 | You can also use the @code{load} command to reload an object module | |
855 | after editing and recompiling the corresponding source file. Note that | |
856 | this will cause @value{GDBN} to delete all currently-defined breakpoints, | |
857 | auto-displays, and convenience variables, and to clear the value | |
858 | history. (This is necessary in order to preserve the integrity of | |
859 | debugger data structures that reference the target system's symbol | |
860 | table.) | |
861 | ||
ed447b95 | 862 | @node VxWorks Attach |
93928b60 | 863 | @subsubsection Running tasks |
18fae2a8 RP |
864 | |
865 | @cindex running VxWorks tasks | |
866 | You can also attach to an existing task using the @code{attach} command as | |
867 | follows: | |
868 | ||
ed447b95 | 869 | @example |
d55320a0 | 870 | (vxgdb) attach @var{task} |
ed447b95 | 871 | @end example |
18fae2a8 RP |
872 | |
873 | @noindent | |
874 | where @var{task} is the VxWorks hexadecimal task ID. The task can be running | |
875 | or suspended when you attach to it. If running, it will be suspended at | |
876 | the time of attachment. | |
877 | @end ifset | |
878 | ||
a64a6c2b RP |
879 | @ifset H8 |
880 | @node Hitachi Remote | |
881 | @subsection @value{GDBN} and Hitachi Microprocessors | |
882 | @value{GDBN} needs to know these things to talk to your | |
883 | Hitachi SH, H8/300, or H8/500: | |
18fae2a8 RP |
884 | |
885 | @enumerate | |
886 | @item | |
a64a6c2b RP |
887 | that you want to use @samp{target hms}, the remote debugging interface |
888 | for Hitachi microprocessors (this is the default when GDB is configured | |
889 | specifically for the Hitachi SH, H8/300, or H8/500); | |
18fae2a8 RP |
890 | |
891 | @item | |
1d7c3357 RP |
892 | what serial device connects your host to your Hitachi board (the first |
893 | serial device available on your host is the default); | |
18fae2a8 RP |
894 | |
895 | @ignore | |
896 | @c this is only for Unix hosts, not currently of interest. | |
897 | @item | |
898 | what speed to use over the serial device. | |
899 | @end ignore | |
900 | @end enumerate | |
901 | ||
a64a6c2b | 902 | @ifclear H8EXCLUSIVE |
18fae2a8 | 903 | @c only for Unix hosts |
1d7c3357 | 904 | @kindex device |
a64a6c2b | 905 | @cindex serial device, Hitachi micros |
1d7c3357 | 906 | Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you |
18fae2a8 RP |
907 | need to explicitly set the serial device. The default @var{port} is the |
908 | first available port on your host. This is only necessary on Unix | |
909 | hosts, where it is typically something like @file{/dev/ttya}. | |
910 | ||
911 | @kindex speed | |
a64a6c2b | 912 | @cindex serial line speed, Hitachi micros |
1d7c3357 RP |
913 | @code{@value{GDBP}} has another special command to set the communications |
914 | speed: @samp{speed @var{bps}}. This command also is only used from Unix | |
915 | hosts; on DOS hosts, set the line speed as usual from outside GDB with | |
916 | the DOS @kbd{mode} command (for instance, @w{@samp{mode | |
18fae2a8 | 917 | com2:9600,n,8,1,p}} for a 9600 bps connection). |
18fae2a8 | 918 | |
a64a6c2b RP |
919 | The @samp{device} and @samp{speed} commands are available only when you |
920 | use a Unix host to debug your Hitachi microprocessor programs. If you | |
921 | use a DOS host, | |
922 | @end ifclear | |
18fae2a8 | 923 | @value{GDBN} depends on an auxiliary terminate-and-stay-resident program |
1d7c3357 | 924 | called @code{asynctsr} to communicate with the development board |
18fae2a8 RP |
925 | through a PC serial port. You must also use the DOS @code{mode} command |
926 | to set up the serial port on the DOS side. | |
927 | ||
a64a6c2b | 928 | @ifset DOSHOST |
18fae2a8 | 929 | The following sample session illustrates the steps needed to start a |
a64a6c2b RP |
930 | program under @value{GDBN} control on an H8/300. The example uses a |
931 | sample H8/300 program called @file{t.x}. The procedure is the same for | |
932 | the Hitachi SH and the H8/500. | |
18fae2a8 | 933 | |
1d7c3357 | 934 | First hook up your development board. In this example, we use a |
18fae2a8 RP |
935 | board attached to serial port @code{COM2}; if you use a different serial |
936 | port, substitute its name in the argument of the @code{mode} command. | |
937 | When you call @code{asynctsr}, the auxiliary comms program used by the | |
938 | degugger, you give it just the numeric part of the serial port's name; | |
939 | for example, @samp{asyncstr 2} below runs @code{asyncstr} on | |
940 | @code{COM2}. | |
941 | ||
ed447b95 | 942 | @example |
18fae2a8 RP |
943 | (eg-C:\H8300\TEST) mode com2:9600,n,8,1,p |
944 | ||
945 | Resident portion of MODE loaded | |
946 | ||
947 | COM2: 9600, n, 8, 1, p | |
948 | ||
949 | (eg-C:\H8300\TEST) asynctsr 2 | |
ed447b95 | 950 | @end example |
18fae2a8 RP |
951 | |
952 | @quotation | |
953 | @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with | |
954 | @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to | |
955 | disable it, or even boot without it, to use @code{asynctsr} to control | |
1d7c3357 | 956 | your development board. |
18fae2a8 RP |
957 | @end quotation |
958 | ||
1d7c3357 RP |
959 | @kindex target hms |
960 | Now that serial communications are set up, and the development board is | |
961 | connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with | |
962 | the name of your program as the argument. @code{@value{GDBP}} prompts | |
963 | you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special | |
964 | commands to begin your debugging session: @samp{target hms} to specify | |
965 | cross-debugging to the Hitachi board, and the @code{load} command to | |
966 | download your program to the board. @code{load} displays the names of | |
967 | the program's sections, and a @samp{*} for each 2K of data downloaded. | |
968 | (If you want to refresh @value{GDBN} data on symbols or on the | |
969 | executable file without downloading, use the @value{GDBN} commands | |
970 | @code{file} or @code{symbol-file}. These commands, and @code{load} | |
971 | itself, are described in @ref{Files,,Commands to specify files}.) | |
18fae2a8 RP |
972 | |
973 | @smallexample | |
974 | (eg-C:\H8300\TEST) @value{GDBP} t.x | |
975 | GDB is free software and you are welcome to distribute copies | |
976 | of it under certain conditions; type "show copying" to see | |
977 | the conditions. | |
978 | There is absolutely no warranty for GDB; type "show warranty" | |
979 | for details. | |
980 | GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... | |
981 | (gdb) target hms | |
982 | Connected to remote H8/300 HMS system. | |
983 | (gdb) load t.x | |
984 | .text : 0x8000 .. 0xabde *********** | |
985 | .data : 0xabde .. 0xad30 * | |
986 | .stack : 0xf000 .. 0xf014 * | |
987 | @end smallexample | |
988 | ||
989 | At this point, you're ready to run or debug your program. From here on, | |
990 | you can use all the usual @value{GDBN} commands. The @code{break} command | |
991 | sets breakpoints; the @code{run} command starts your program; | |
992 | @code{print} or @code{x} display data; the @code{continue} command | |
993 | resumes execution after stopping at a breakpoint. You can use the | |
994 | @code{help} command at any time to find out more about @value{GDBN} commands. | |
995 | ||
996 | Remember, however, that @emph{operating system} facilities aren't | |
1d7c3357 RP |
997 | available on your development board; for example, if your program hangs, |
998 | you can't send an interrupt---but you can press the @sc{reset} switch! | |
18fae2a8 | 999 | |
1d7c3357 | 1000 | Use the @sc{reset} button on the development board |
18fae2a8 RP |
1001 | @itemize @bullet |
1002 | @item | |
1003 | to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has | |
1d7c3357 | 1004 | no way to pass an interrupt signal to the development board); and |
18fae2a8 RP |
1005 | |
1006 | @item | |
1007 | to return to the @value{GDBN} command prompt after your program finishes | |
1008 | normally. The communications protocol provides no other way for @value{GDBN} | |
1009 | to detect program completion. | |
1010 | @end itemize | |
1011 | ||
1012 | In either case, @value{GDBN} will see the effect of a @sc{reset} on the | |
1d7c3357 | 1013 | development board as a ``normal exit'' of your program. |
18fae2a8 | 1014 | @end ifset |
a64a6c2b | 1015 | @end ifset |
18fae2a8 | 1016 | |
34ae25cd RP |
1017 | @ifset MIPS |
1018 | @node MIPS Remote | |
1019 | @subsection @value{GDBN} and remote MIPS boards | |
1020 | ||
1021 | @cindex MIPS boards | |
1022 | @value{GDBN} can use the MIPS remote debugging protocol to talk to a | |
1023 | MIPS board attached to a serial line. This is available when | |
1024 | you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. | |
1025 | ||
1026 | @kindex target mips @var{port} | |
1027 | To run a program on the board, start up @code{@value{GDBP}} with the | |
1028 | name of your program as the argument. To connect to the board, use the | |
1029 | command @samp{target mips @var{port}}, where @var{port} is the name of | |
1030 | the serial port connected to the board. If the program has not already | |
1031 | been downloaded to the board, you may use the @code{load} command to | |
1032 | download it. You can then use all the usual @value{GDBN} commands. | |
1033 | ||
1034 | @cindex @code{remotedebug}, MIPS protocol | |
1035 | @c FIXME! For this to be useful, you must know something about the MIPS | |
1036 | @c FIXME...protocol. Where is it described? | |
1037 | You can see some debugging information about communications with the board | |
1038 | by setting the @code{remotedebug} variable. If you set it to 1 using | |
1039 | @samp{set remotedebug 1} every packet will be displayed. If you set it | |
1040 | to 2 every character will be displayed. You can check the current value | |
1041 | at any time with the command @samp{show remotedebug}. | |
1042 | ||
1043 | @kindex set mipsfpu off | |
1044 | @cindex MIPS remote floating point | |
1045 | @cindex floating point, MIPS remote | |
1046 | If your target board does not support the MIPS floating point | |
1047 | coprocessor, you should use the command @samp{set mipsfpu off} (you may | |
1048 | wish to put this in your @value{GDBINIT} file). This will tell | |
1049 | @value{GDBN} how to find the return value of functions which return | |
1050 | floating point values, and tell it to call functions on the board | |
1051 | without saving the floating point registers. | |
1052 | @end ifset | |
1053 | ||
fe715d06 RP |
1054 | @ifset SIMS |
1055 | @node Simulator | |
1056 | @subsection Simulated CPU target | |
18fae2a8 | 1057 | |
fe715d06 RP |
1058 | @ifset GENERIC |
1059 | @cindex simulator | |
1060 | @cindex simulator, Z8000 | |
fe715d06 | 1061 | @cindex Z8000 simulator |
a64a6c2b | 1062 | @cindex simulator, H8/300 or H8/500 |
1d7c3357 | 1063 | @cindex H8/300 or H8/500 simulator |
a64a6c2b RP |
1064 | @cindex simulator, Hitachi SH |
1065 | @cindex Hitachi SH simulator | |
fe715d06 RP |
1066 | @cindex CPU simulator |
1067 | For some configurations, @value{GDBN} includes a CPU simulator that you | |
1068 | can use instead of a hardware CPU to debug your programs. Currently, | |
1069 | a simulator is available when @value{GDBN} is configured to debug Zilog | |
a64a6c2b | 1070 | Z8000 or Hitachi microprocessor targets. |
fe715d06 RP |
1071 | @end ifset |
1072 | ||
1073 | @ifclear GENERIC | |
a64a6c2b | 1074 | @ifset H8 |
1d7c3357 RP |
1075 | @cindex simulator, H8/300 or H8/500 |
1076 | @cindex Hitachi H8/300 or H8/500 simulator | |
a64a6c2b RP |
1077 | @cindex simulator, Hitachi SH |
1078 | @cindex Hitachi SH simulator | |
1079 | When configured for debugging Hitachi microprocessor targets, | |
1080 | @value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH, | |
1081 | H8/300, or H8/500). | |
fe715d06 RP |
1082 | @end ifset |
1083 | ||
a64a6c2b | 1084 | @ifset Z8K |
18fae2a8 RP |
1085 | @cindex simulator, Z8000 |
1086 | @cindex Zilog Z8000 simulator | |
e55d2728 RP |
1087 | When configured for debugging Zilog Z8000 targets, @value{GDBN} includes |
1088 | a Z8000 simulator. | |
fe715d06 RP |
1089 | @end ifset |
1090 | @end ifclear | |
1091 | ||
a64a6c2b | 1092 | @ifset Z8K |
fe715d06 RP |
1093 | For the Z8000 family, @samp{target sim} simulates either the Z8002 (the |
1094 | unsegmented variant of the Z8000 architecture) or the Z8001 (the | |
1095 | segmented variant). The simulator recognizes which architecture is | |
1096 | appropriate by inspecting the object code. | |
1097 | @end ifset | |
18fae2a8 RP |
1098 | |
1099 | @table @code | |
e55d2728 RP |
1100 | @item target sim |
1101 | @kindex sim | |
1102 | @kindex target sim | |
fe715d06 RP |
1103 | Debug programs on a simulated CPU |
1104 | @ifset GENERIC | |
1105 | (which CPU depends on the @value{GDBN} configuration) | |
1106 | @end ifset | |
18fae2a8 RP |
1107 | @end table |
1108 | ||
1109 | @noindent | |
fe715d06 RP |
1110 | After specifying this target, you can debug programs for the simulated |
1111 | CPU in the same style as programs for your host computer; use the | |
1112 | @code{file} command to load a new program image, the @code{run} command | |
1113 | to run your program, and so on. | |
18fae2a8 | 1114 | |
fe715d06 | 1115 | As well as making available all the usual machine registers (see |
18fae2a8 RP |
1116 | @code{info reg}), this debugging target provides three additional items |
1117 | of information as specially named registers: | |
1118 | ||
1119 | @table @code | |
1120 | @item cycles | |
1121 | Counts clock-ticks in the simulator. | |
1122 | ||
1123 | @item insts | |
1124 | Counts instructions run in the simulator. | |
1125 | ||
1126 | @item time | |
1127 | Execution time in 60ths of a second. | |
1128 | @end table | |
1129 | ||
1130 | You can refer to these values in @value{GDBN} expressions with the usual | |
1131 | conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a | |
1132 | conditional breakpoint that will suspend only after at least 5000 | |
1133 | simulated clock ticks. | |
1134 | @end ifset |