Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ -*- Texinfo -*- |
2 | _dnl__ Copyright (c) 1990 1991 Free Software Foundation, Inc. | |
3 | _dnl__ This file is part of the source for the GDB manual. | |
54e4cbe8 | 4 | @c M4 FRAGMENT $Id$ |
9bcc06ef RP |
5 | @c This text diverted to "Remote Debugging" section in general case; |
6 | @c however, if we're doing a manual specifically for one of these, it | |
7 | @c belongs up front (in "Getting In and Out" chapter). | |
9bcc06ef | 8 | _if__(_I960__) |
54e4cbe8 | 9 | _if__(!_GENERIC__) |
9bcc06ef | 10 | @node i960-Nindy Remote, EB29K Remote, Mode Options, Starting _GDBN__ |
54e4cbe8 RP |
11 | _fi__(!_GENERIC__) |
12 | _if__(_GENERIC__) | |
13 | @node i960-Nindy Remote, EB29K Remote, Remote, Remote | |
14 | _fi__(_GENERIC__) | |
9bcc06ef RP |
15 | @subsection _GDBN__ with a Remote i960 (Nindy) |
16 | ||
17 | @cindex Nindy | |
18 | @cindex i960 | |
19 | @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When | |
20 | _GDBN__ is configured to control a remote Intel 960 using Nindy, you can | |
21 | tell _GDBN__ how to connect to the 960 in several ways: | |
22 | ||
23 | @itemize @bullet | |
24 | @item | |
25 | Through command line options specifying serial port, version of the | |
26 | Nindy protocol, and communications speed; | |
27 | ||
28 | @item | |
29 | By responding to a prompt on startup; | |
30 | ||
31 | @item | |
32 | By using the @code{target} command at any point during your _GDBN__ | |
33 | session. @xref{Target Commands}. | |
34 | ||
35 | @end itemize | |
36 | ||
37 | @menu | |
0c81306b RP |
38 | * Nindy Startup:: Startup with Nindy |
39 | * Nindy Options:: Options for Nindy | |
40 | * Nindy reset:: Nindy Reset Command | |
9bcc06ef RP |
41 | @end menu |
42 | ||
43 | @node Nindy Startup, Nindy Options, i960-Nindy Remote, i960-Nindy Remote | |
44 | @subsubsection Startup with Nindy | |
45 | ||
46 | If you simply start @code{_GDBN__} without using any command-line | |
47 | options, you are prompted for what serial port to use, @emph{before} you | |
48 | reach the ordinary _GDBN__ prompt: | |
49 | @example | |
50 | Attach /dev/ttyNN -- specify NN, or "quit" to quit: | |
51 | @end example | |
52 | @noindent | |
53 | Respond to the prompt with whatever suffix (after @samp{/dev/tty}) | |
54 | identifies the serial port you want to use. You can, if you choose, | |
55 | simply start up with no Nindy connection by responding to the prompt | |
56 | with an empty line. If you do this, and later wish to attach to Nindy, | |
57 | use @code{target} (@pxref{Target Commands}). | |
58 | ||
59 | @node Nindy Options, Nindy reset, Nindy Startup, i960-Nindy Remote | |
60 | @subsubsection Options for Nindy | |
61 | ||
62 | These are the startup options for beginning your _GDBN__ session with a | |
63 | Nindy-960 board attached: | |
64 | ||
65 | @table @code | |
66 | @item -r @var{port} | |
67 | Specify the serial port name of a serial interface to be used to connect | |
68 | to the target system. This option is only available when _GDBN__ is | |
69 | configured for the Intel 960 target architecture. You may specify | |
70 | @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a | |
71 | device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique | |
72 | suffix for a specific @code{tty} (e.g. @samp{-r a}). | |
73 | ||
74 | @item -O | |
75 | (An uppercase letter ``O'', not a zero.) Specify that _GDBN__ should use | |
76 | the ``old'' Nindy monitor protocol to connect to the target system. | |
77 | This option is only available when _GDBN__ is configured for the Intel 960 | |
78 | target architecture. | |
79 | ||
80 | @quotation | |
81 | @emph{Warning:} if you specify @samp{-O}, but are actually trying to | |
82 | connect to a target system that expects the newer protocol, the connection | |
83 | will fail, appearing to be a speed mismatch. _GDBN__ will repeatedly | |
84 | attempt to reconnect at several different line speeds. You can abort | |
85 | this process with an interrupt. | |
86 | @end quotation | |
87 | ||
88 | @item -brk | |
89 | Specify that _GDBN__ should first send a @code{BREAK} signal to the target | |
90 | system, in an attempt to reset it, before connecting to a Nindy target. | |
91 | ||
92 | @quotation | |
93 | @emph{Warning:} Many target systems do not have the hardware that this | |
94 | requires; it only works with a few boards. | |
95 | @end quotation | |
96 | ||
97 | @end table | |
98 | ||
99 | The standard @samp{-b} option controls the line speed used on the serial | |
100 | port. | |
101 | ||
9bcc06ef | 102 | @node Nindy reset, , Nindy Options, i960-Nindy Remote |
54e4cbe8 | 103 | @c @group |
9bcc06ef RP |
104 | @subsubsection Nindy Reset Command |
105 | @table @code | |
106 | @item reset | |
107 | @kindex reset | |
108 | For a Nindy target, this command sends a ``break'' to the remote target | |
109 | system; this is only useful if the target has been equipped with a | |
110 | circuit to perform a hard reset (or some other interesting action) when | |
111 | a break is detected. | |
112 | @end table | |
54e4cbe8 | 113 | @c @end group |
9bcc06ef RP |
114 | _fi__(_I960__) |
115 | ||
116 | _if__(_AMD29K__) | |
54e4cbe8 | 117 | _if__(!_GENERIC__) |
9bcc06ef | 118 | @node EB29K Remote, VxWorks Remote, i960-Nindy Remote, Starting _GDBN__ |
54e4cbe8 RP |
119 | _fi__(!_GENERIC__) |
120 | _if__(_GENERIC__) | |
121 | @node EB29K Remote, VxWorks Remote, i960-Nindy Remote, Remote | |
122 | _fi__(_GENERIC__) | |
9bcc06ef RP |
123 | @subsection _GDBN__ with a Remote EB29K |
124 | ||
125 | @cindex EB29K board | |
126 | @cindex running 29K programs | |
127 | ||
128 | To use _GDBN__ from a Unix system to run programs on AMD's EB29K | |
129 | board in a PC, you must first connect a serial cable between the PC | |
130 | and a serial port on the Unix system. In the following, we assume | |
131 | you've hooked the cable between the PC's @file{COM1} port and | |
132 | @file{/dev/ttya} on the Unix system. | |
133 | ||
134 | @menu | |
0c81306b RP |
135 | * Comms (EB29K):: Communications Setup |
136 | * _GDBP__-EB29K:: EB29K cross-debugging | |
137 | * Remote Log:: Remote Log | |
9bcc06ef RP |
138 | @end menu |
139 | ||
140 | @node Comms (EB29K), _GDBP__-EB29K, EB29K Remote, EB29K Remote | |
141 | @subsubsection Communications Setup | |
142 | The next step is to set up the PC's port, by doing something like the | |
143 | following in DOS on the PC: | |
144 | _0__@example | |
145 | C:\> MODE com1:9600,n,8,1,none | |
146 | _1__@end example | |
147 | @noindent | |
148 | This example---run on an MS DOS 4.0 system---sets the PC port to 9600 | |
149 | bps, no parity, eight data bits, one stop bit, and no ``retry'' action; | |
150 | you must match the communications parameters when establishing the Unix | |
151 | end of the connection as well. | |
152 | @c FIXME: Who knows what this "no retry action" crud from the DOS manual may | |
153 | @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91 | |
154 | ||
155 | To give control of the PC to the Unix side of the serial line, type | |
156 | the following at the DOS console: | |
157 | _0__@example | |
158 | C:\> CTTY com1 | |
159 | _1__@end example | |
160 | @noindent | |
161 | (Later, if you wish to return control to the DOS console, you can use | |
162 | the command @code{CTTY con}---but you must send it over the device that | |
163 | had control, in our example over the @file{COM1} serial line). | |
164 | ||
165 | From the Unix host, use a communications program such as @code{tip} or | |
166 | @code{cu} to communicate with the PC; for example, | |
167 | @example | |
168 | cu -s 9600 -l /dev/ttya | |
169 | @end example | |
170 | @noindent | |
171 | The @code{cu} options shown specify, respectively, the linespeed and the | |
172 | serial port to use. If you use @code{tip} instead, your command line | |
173 | may look something like the following: | |
174 | @example | |
175 | tip -9600 /dev/ttya | |
176 | @end example | |
177 | @noindent | |
178 | Your system may define a different name where our example uses | |
179 | @file{/dev/ttya} as the argument to @code{tip}. The communications | |
180 | parameters, including what port to use, are associated with the | |
181 | @code{tip} argument in the ``remote'' descriptions file---normally the | |
182 | system table @file{/etc/remote}. | |
183 | @c FIXME: What if anything needs doing to match the "n,8,1,none" part of | |
184 | @c the DOS side's comms setup? cu can support -o (odd | |
185 | @c parity), -e (even parity)---apparently no settings for no parity or | |
186 | @c for character size. Taken from stty maybe...? John points out tip | |
187 | @c can set these as internal variables, eg ~s parity=none; man stty | |
188 | @c suggests that it *might* work to stty these options with stdin or | |
189 | @c stdout redirected... ---pesch@cygnus.com, 25feb91 | |
190 | ||
191 | @kindex EBMON | |
192 | Using the @code{tip} or @code{cu} connection, change the DOS working | |
193 | directory to the directory containing a copy of your 29K program, then | |
194 | start the PC program @code{EBMON} (an EB29K control program supplied | |
195 | with your board by AMD). You should see an initial display from | |
196 | @code{EBMON} similar to the one that follows, ending with the | |
197 | @code{EBMON} prompt @samp{#}--- | |
198 | _0__@example | |
199 | C:\> G: | |
200 | ||
201 | G:\> CD \usr\joe\work29k | |
202 | ||
203 | G:\USR\JOE\WORK29K> EBMON | |
204 | Am29000 PC Coprocessor Board Monitor, version 3.0-18 | |
205 | Copyright 1990 Advanced Micro Devices, Inc. | |
206 | Written by Gibbons and Associates, Inc. | |
207 | ||
208 | Enter '?' or 'H' for help | |
209 | ||
210 | PC Coprocessor Type = EB29K | |
211 | I/O Base = 0x208 | |
212 | Memory Base = 0xd0000 | |
213 | ||
214 | Data Memory Size = 2048KB | |
215 | Available I-RAM Range = 0x8000 to 0x1fffff | |
216 | Available D-RAM Range = 0x80002000 to 0x801fffff | |
217 | ||
218 | PageSize = 0x400 | |
219 | Register Stack Size = 0x800 | |
220 | Memory Stack Size = 0x1800 | |
221 | ||
222 | CPU PRL = 0x3 | |
223 | Am29027 Available = No | |
224 | Byte Write Available = Yes | |
225 | ||
226 | # ~. | |
227 | _1__@end example | |
228 | ||
229 | Then exit the @code{cu} or @code{tip} program (done in the example by | |
230 | typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep | |
231 | running, ready for _GDBN__ to take over. | |
232 | ||
233 | For this example, we've assumed what is probably the most convenient | |
234 | way to make sure the same 29K program is on both the PC and the Unix | |
235 | system: a PC/NFS connection that establishes ``drive @code{G:}'' on the | |
236 | PC as a file system on the Unix host. If you don't have PC/NFS or | |
237 | something similar connecting the two systems, you must arrange some | |
238 | other way---perhaps floppy-disk transfer---of getting the 29K program | |
239 | from the Unix system to the PC; _GDBN__ will @emph{not} download it over the | |
240 | serial line. | |
241 | ||
242 | @node _GDBP__-EB29K, Remote Log, Comms (EB29K), EB29K Remote | |
243 | @subsubsection EB29K cross-debugging | |
244 | Finally, @code{cd} to the directory containing an image of your 29K | |
245 | program on the Unix system, and start _GDBN__---specifying as argument the | |
246 | name of your 29K program: | |
247 | @example | |
248 | cd /usr/joe/work29k | |
249 | _GDBP__ myfoo | |
250 | @end example | |
251 | Now you can use the @code{target} command: | |
252 | @example | |
253 | target amd-eb /dev/ttya 9600 MYFOO | |
254 | @end example | |
255 | @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to | |
256 | @c emphasize that this is the name as seen by DOS (since I think DOS is | |
257 | @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91 | |
258 | ||
259 | @noindent | |
260 | In this example, we've assumed your program is in a file called | |
261 | @file{myfoo}. Note that the filename given as the last argument to | |
262 | @code{target amd-eb} should be the name of the program as it appears to DOS. | |
263 | In our example this is simply @code{MYFOO}, but in general it can include | |
264 | a DOS path, and depending on your transfer mechanism may not resemble | |
265 | the name on the Unix side. | |
266 | ||
267 | At this point, you can set any breakpoints you wish; when you're ready | |
268 | to see your program run on the 29K board, use the _GDBN__ command | |
269 | @code{run}. | |
270 | ||
271 | To stop debugging the remote program, use the _GDBN__ @code{detach} | |
272 | command. | |
273 | ||
274 | To return control of the PC to its console, use @code{tip} or @code{cu} | |
275 | once again, after your _GDBN__ session has concluded, to attach to | |
276 | @code{EBMON}. You can then type the command @code{q} to shut down | |
277 | @code{EBMON}, returning control to the DOS command-line interpreter. | |
278 | Type @code{CTTY con} to return command input to the main DOS console, | |
279 | and type @kbd{~.} to leave @code{tip} or @code{cu}. | |
280 | ||
281 | @node Remote Log, , _GDBP__-EB29K, EB29K Remote | |
282 | @subsubsection Remote Log | |
283 | @kindex eb.log | |
284 | @cindex log file for EB29K | |
285 | The @code{target amd-eb} command creates a file @file{eb.log} in the | |
286 | current working directory, to help debug problems with the connection. | |
287 | @file{eb.log} records all the output from @code{EBMON}, including echoes | |
288 | of the commands sent to it. Running @samp{tail -f} on this file in | |
289 | another window often helps to understand trouble with @code{EBMON}, or | |
290 | unexpected events on the PC side of the connection. | |
291 | _fi__(_AMD29K__) | |
292 | ||
293 | _if__(_VXWORKS__) | |
54e4cbe8 | 294 | _if__(!_GENERIC__) |
9bcc06ef | 295 | @node VxWorks Remote, , EB29K Remote, Starting _GDBN__ |
54e4cbe8 RP |
296 | _fi__(!_GENERIC__) |
297 | _if__(_GENERIC__) | |
298 | @node VxWorks Remote, , EB29K Remote, Remote | |
299 | _fi__(_GENERIC__) | |
9bcc06ef RP |
300 | @subsection _GDBN__ and VxWorks |
301 | @cindex VxWorks | |
302 | _GDBN__ enables developers to spawn and debug tasks running on networked | |
303 | VxWorks targets from a Unix host. Already-running tasks spawned from | |
304 | the VxWorks shell can also be debugged. _GDBN__ uses code that runs on | |
305 | both the UNIX host and on the VxWorks target. The program | |
306 | @code{_GDBP__} is installed and executed on the UNIX host. | |
307 | ||
308 | The remote debugging interface (RDB) routines are installed and executed | |
309 | on the VxWorks target. These routines are included in the VxWorks library | |
310 | @file{rdb.a} and are incorporated into the system image when source-level | |
311 | debugging is enabled in the VxWorks configuration. | |
312 | ||
54e4cbe8 | 313 | @kindex INCLUDE_RDB |
37daba7b RP |
314 | You can define @code{INCLUDE_RDB} in the VxWorks configuration file |
315 | @file{configAll.h} to include the RDB interface routines and spawn the | |
9bcc06ef RP |
316 | source debugging task @code{tRdbTask} when VxWorks is booted. For more |
317 | information on configuring and remaking VxWorks, see the @cite{VxWorks | |
318 | Programmer's Guide}. | |
319 | ||
320 | Once you have included the RDB interface in your VxWorks system image | |
321 | and set your Unix execution search path to find _GDBN__, you are ready | |
322 | to run _GDBN__. From your UNIX host, type: | |
323 | ||
324 | @smallexample | |
325 | % _GDBP__ | |
326 | @end smallexample | |
327 | ||
328 | _GDBN__ will come up showing the prompt: | |
329 | ||
330 | @smallexample | |
331 | (_GDBP__) | |
332 | @end smallexample | |
333 | ||
334 | @menu | |
0c81306b RP |
335 | * VxWorks connection:: Connecting to VxWorks |
336 | * VxWorks download:: VxWorks Download | |
337 | * VxWorks attach:: Running Tasks | |
9bcc06ef RP |
338 | @end menu |
339 | ||
340 | @node VxWorks connection, VxWorks download, VxWorks Remote, VxWorks Remote | |
341 | @subsubsection Connecting to VxWorks | |
342 | ||
343 | The _GDBN__ command @code{target} lets you connect to a VxWorks target on the | |
344 | network. To connect to a target whose host name is ``@code{tt}'', type: | |
345 | ||
346 | @smallexample | |
347 | (_GDBP__) target vxworks tt | |
348 | @end smallexample | |
349 | ||
350 | _GDBN__ will display a message similar to the following: | |
351 | ||
352 | @smallexample | |
353 | Attaching remote machine across net... Success! | |
354 | @end smallexample | |
355 | ||
356 | _GDBN__ will then attempt to read the symbol tables of any object | |
357 | modules loaded into the VxWorks target since it was last booted. | |
358 | _GDBN__ locates these files by searching the directories listed in the | |
359 | command search path (@pxref{Environment}); if it fails to find an | |
360 | object file, it will display a message such as: | |
361 | ||
362 | @smallexample | |
363 | prog.o: No such file or directory. | |
364 | @end smallexample | |
365 | ||
366 | This will cause the @code{target} command to abort. When this happens, | |
367 | you should add the appropriate directory to the search path, with the | |
368 | _GDBN__ command @code{path}, and execute the @code{target} command | |
369 | again. | |
370 | ||
371 | @node VxWorks download, VxWorks attach, VxWorks connection, VxWorks Remote | |
372 | @subsubsection VxWorks Download | |
373 | ||
374 | @cindex download to VxWorks | |
375 | If you have connected to the VxWorks target and you want to debug an | |
376 | object that has not yet been loaded, you can use the _GDBN__ @code{load} | |
377 | command to download a file from UNIX to VxWorks incrementally. The | |
378 | object file given as an argument to the @code{load} command is actually | |
379 | opened twice: first by the VxWorks target in order to download the code, | |
380 | then by _GDBN__ in order to read the symbol table. This can lead to | |
381 | problems if the current working directories on the two systems differ. | |
382 | It is simplest to set the working directory on both systems to the | |
383 | directory in which the object file resides, and then to reference the | |
384 | file by its name, without any path. Thus, to load a program | |
385 | @file{prog.o}, residing in @file{wherever/vw/demo/rdb}, on VxWorks type: | |
386 | ||
387 | @smallexample | |
388 | -> cd "wherever/vw/demo/rdb" | |
389 | @end smallexample | |
390 | ||
391 | On _GDBN__ type: | |
392 | ||
393 | @smallexample | |
394 | (_GDBP__) cd wherever/vw/demo/rdb | |
395 | (_GDBP__) load prog.o | |
396 | @end smallexample | |
397 | ||
398 | _GDBN__ will display a response similar to the following: | |
399 | ||
400 | @smallexample | |
401 | Reading symbol data from wherever/vw/demo/rdb/prog.o... done. | |
402 | @end smallexample | |
403 | ||
404 | You can also use the @code{load} command to reload an object module | |
405 | after editing and recompiling the corresponding source file. Note that | |
406 | this will cause _GDBN__ to delete all currently-defined breakpoints, | |
407 | auto-displays, and convenience variables, and to clear the value | |
408 | history. (This is necessary in order to preserve the integrity of | |
409 | debugger data structures that reference the target system's symbol | |
410 | table.) | |
411 | ||
412 | @node VxWorks attach, , VxWorks download, VxWorks Remote | |
413 | @subsubsection Running Tasks | |
414 | ||
415 | @cindex running VxWorks tasks | |
416 | You can also attach to an existing task using the @code{attach} command as | |
417 | follows: | |
418 | ||
419 | @smallexample | |
420 | (_GDBP__) attach @var{task} | |
421 | @end smallexample | |
422 | ||
423 | where @var{task} is the VxWorks hexadecimal task ID. The task can be running | |
424 | or suspended when you attach to it. If running, it will be suspended at | |
425 | the time of attachment. | |
426 | ||
427 | _fi__(_VXWORKS__) |