diff options
Diffstat (limited to 'gdb/doc/gdbinv-s.m4.in')
| -rw-r--r-- | gdb/doc/gdbinv-s.m4.in | 186 |
1 files changed, 106 insertions, 80 deletions
diff --git a/gdb/doc/gdbinv-s.m4.in b/gdb/doc/gdbinv-s.m4.in index eae7e21..c9355ae 100644 --- a/gdb/doc/gdbinv-s.m4.in +++ b/gdb/doc/gdbinv-s.m4.in @@ -6,12 +6,7 @@ _dnl__ This text diverted to "Remote Debugging" section in general case; _dnl__ however, if we're doing a manual specifically for one of these, it _dnl__ belongs up front (in "Getting In and Out" chapter). _if__(_I960__) -_if__(!_GENERIC__) -@node i960-Nindy Remote, EB29K Remote, Mode Options, Starting _GDBN__ -_fi__(!_GENERIC__) -_if__(_GENERIC__) -@node i960-Nindy Remote, EB29K Remote, Remote, Remote -_fi__(_GENERIC__) +@node i960-Nindy Remote @subsection _GDBN__ with a Remote i960 (Nindy) @cindex Nindy @@ -40,7 +35,7 @@ session. @xref{Target Commands, ,Commands for Managing Targets}. * Nindy reset:: Nindy Reset Command @end menu -@node Nindy Startup, Nindy Options, i960-Nindy Remote, i960-Nindy Remote +@node Nindy Startup @subsubsection Startup with Nindy If you simply start @code{_GDBP__} without using any command-line @@ -58,7 +53,7 @@ simply start up with no Nindy connection by responding to the prompt with an empty line. If you do this, and later wish to attach to Nindy, use @code{target} (@pxref{Target Commands, ,Commands for Managing Targets}). -@node Nindy Options, Nindy reset, Nindy Startup, i960-Nindy Remote +@node Nindy Options @subsubsection Options for Nindy These are the startup options for beginning your _GDBN__ session with a @@ -101,7 +96,7 @@ The standard @samp{-b} option controls the line speed used on the serial port. @c @group -@node Nindy reset, , Nindy Options, i960-Nindy Remote +@node Nindy reset @subsubsection Nindy Reset Command @table @code @@ -116,12 +111,7 @@ a break is detected. _fi__(_I960__) _if__(_AMD29K__) -_if__(!_GENERIC__) -@node EB29K Remote, VxWorks Remote, i960-Nindy Remote, Starting _GDBN__ -_fi__(!_GENERIC__) -_if__(_GENERIC__) -@node EB29K Remote, VxWorks Remote, i960-Nindy Remote, Remote -_fi__(_GENERIC__) +@node EB29K Remote @subsection _GDBN__ with a Remote EB29K @cindex EB29K board @@ -139,7 +129,7 @@ you've hooked the cable between the PC's @file{COM1} port and * Remote Log:: Remote Log @end menu -@node Comms (EB29K), _GDBP__-EB29K, EB29K Remote, EB29K Remote +@node Comms (EB29K) @subsubsection Communications Setup The next step is to set up the PC's port, by doing something like the @@ -251,7 +241,7 @@ other way---perhaps floppy-disk transfer---of getting the 29K program from the Unix system to the PC; _GDBN__ will @emph{not} download it over the serial line. -@node _GDBP__-EB29K, Remote Log, Comms (EB29K), EB29K Remote +@node _GDBP__-EB29K @subsubsection EB29K cross-debugging Finally, @code{cd} to the directory containing an image of your 29K @@ -294,7 +284,7 @@ once again, after your _GDBN__ session has concluded, to attach to Type @code{CTTY con} to return command input to the main DOS console, and type @kbd{~.} to leave @code{tip} or @code{cu}. -@node Remote Log, , _GDBP__-EB29K, EB29K Remote +@node Remote Log @subsubsection Remote Log @kindex eb.log @cindex log file for EB29K @@ -308,12 +298,7 @@ unexpected events on the PC side of the connection. _fi__(_AMD29K__) _if__(_VXWORKS__) -_if__(!_GENERIC__) -@node VxWorks Remote, , EB29K Remote, Starting _GDBN__ -_fi__(!_GENERIC__) -_if__(_GENERIC__) -@node VxWorks Remote, , EB29K Remote, Remote -_fi__(_GENERIC__) +@node VxWorks Remote @subsection _GDBN__ and VxWorks @cindex VxWorks @@ -364,7 +349,7 @@ _GDBN__ will come up showing the prompt: * VxWorks attach:: Running Tasks @end menu -@node VxWorks connection, VxWorks download, VxWorks Remote, VxWorks Remote +@node VxWorks connection @subsubsection Connecting to VxWorks The _GDBN__ command @code{target} lets you connect to a VxWorks target on the @@ -395,7 +380,7 @@ you should add the appropriate directory to the search path, with the _GDBN__ command @code{path}, and execute the @code{target} command again. -@node VxWorks download, VxWorks attach, VxWorks connection, VxWorks Remote +@node VxWorks download @subsubsection VxWorks Download @cindex download to VxWorks @@ -436,7 +421,7 @@ history. (This is necessary in order to preserve the integrity of debugger data structures that reference the target system's symbol table.) -@node VxWorks attach, , VxWorks download, VxWorks Remote +@node VxWorks attach @subsubsection Running Tasks @cindex running VxWorks tasks @@ -452,42 +437,38 @@ where @var{task} is the VxWorks hexadecimal task ID. The task can be running or suspended when you attach to it. If running, it will be suspended at the time of attachment. _fi__(_VXWORKS__) + _if__(_H8__) -_if__(!_GENERIC__) -@node Hitachi H8/300 Remote, , VxWorks Remote, Starting _GDBN__ -_fi__(!_GENERIC__) -_if__(_GENERIC__) -@node Hitachi H8/300 Remote, , VxWorks Remote, Remote -_fi__(_GENERIC__) +@node Hitachi H8/300 Remote @subsection _GDBN__ and the Hitachi H8/300 -_GDBN__ needs to know three things to talk to your H8/300: +_GDBN__ needs to know these things to talk to your H8/300: @enumerate @item that you want to use @samp{target hms}, the remote debugging -interface for the H8/300 (this is the default for @code{gdb83}, the -version of GDB configured specifically for the H8/300); +interface for the H8/300 (this is the default when +GDB is configured specifically for the H8/300); @item what serial device connects your host to your H8/300 (the first serial device available on your host is the default); +@ignore +@c this is only for Unix hosts, not currently of interest. @item what speed to use over the serial device. +@end ignore @end enumerate @kindex device @cindex serial device for H8/300 +@ignore +@c only for Unix hosts Use the special @code{gdb83} command @samp{device @var{port}} if you need to explicitly set the serial device. The default @var{port} is the first available port on your host. This is only necessary on Unix hosts, where it is typically something like @file{/dev/ttya}. -On DOS hosts, communication with the serial device is handled by an -auxiliary program, @code{asynctsr}. For example, to use @code{COM2} as -the serial device from a DOS host, execute @samp{asynctsr 2} -@emph{before} starting GDB. - @kindex speed @cindex serial line speed for H8/300 @code{gdb83} has another special command to set the communications speed @@ -495,53 +476,98 @@ for the H8/300: @samp{speed @var{bps}}. This command also is only used from Unix hosts; on DOS hosts, set the line speed as usual from outside GDB with the DOS @kbd{mode} command (for instance, @w{@samp{mode com2:9600,n,8,1,p}} for a 9600 bps connection). +@end ignore + +_GDBN__ depends on an auxiliary terminate-and-stay-resident program +called @code{asynctsr} to communicate with the H8/300 development board +through a PC serial port. You must also use the DOS @code{mode} command +to set up the serial port on the DOS side. + +The following sample session illustrates the steps needed to start a +program under _GDBN__ control on your H8/300. The example uses a sample +H8/300 program called @file{t.x}. + +First hook up your H8/300 development board. In this example, we use a +board attached to serial port @code{COM2}; if you use a different serial +port, substitute its name in the argument of the @code{mode} command. +When you call @code{asynctsr}, the auxiliary comms program used by the +degugger, you give it just the numeric part of the serial port's name; +for example, @samp{asyncstr 2} below runs @code{asyncstr} on +@code{COM2}. + +@cartouche +@example +(eg-C:\H8300\TEST) mode com2:9600,n,8,1,p -For example, you might start an H8/300 debugging session at 19200 bps -like this (exploiting the default target and device): +Resident portion of MODE loaded -@smallexample -$ gdb83 -@c FIXME: this falsifies the linebreaks in the exact text played out, to -@c FIXME... permit smallbook format to come out better. -GDB is free software and you are welcome to distribute copies - of it under certain conditions; type "show copying" to see - the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB _GDB_VN__, Copyright 1992 Free Software Foundation, Inc. -(gdb83) speed 19200 -Remote debugging on an H8/300 HMS via /dev/ttya. -Checking target is in sync -Sending commands to set target to 19200 -(gdb83) -@end smallexample +COM2: 9600, n, 8, 1, p -@noindent -To download your program and make it the current _GDBN__ target, use the -@code{load} command: +(eg-C:\H8300\TEST) asynctsr 2 +@end example +@end cartouche + +@quotation +@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with +@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to +disable it, or even boot without it, to use @code{asynctsr} to control +your H8/300 board. +@end quotation +Now that serial communications are set up, and the H8/300 is connected, +you can start up _GDBN__. Call @code{_GDBP__} with the name of your +program as the argument. @code{_GDBP__} prompts you, as usual, with the +prompt @samp{(_GDBP__)}. Use two special commands to begin your debugging +session: @samp{target hms} to specify cross-debugging to the Hitachi board, +and the @code{load} command to download your program to the board. +@code{load} displays the names of the +program's sections, and a @samp{*} for each 2K of data downloaded. (If +you want to refresh _GDBN__ data on symbols or on the executable file +without downloading, use the _GDBN__ commands @code{file} or +@code{symbol-file}. These commands, and @code{load} itself, are +described in @ref{Files,,Commands to Specify Files}.) + +@cartouche @example -(gdb83) load smain -.text: 8000 .. 9d92 **** -.data: 9d92 .. 9e34 * -(gdb83) +(eg-C:\H8300\TEST) _GDBP__ t.x +GDB is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. +There is absolutely no warranty for GDB; type "show warranty" +for details. +GDB _GDB_VN__, Copyright 1992 Free Software Foundation, Inc... +(gdb) target hms +Connected to remote H8/300 HMS system. +(gdb) load t.x +.text : 0x8000 .. 0xabde *********** +.data : 0xabde .. 0xad30 * +.stack : 0xf000 .. 0xf014 * @end example +@end cartouche -@noindent -While downloading the program (@samp{smain} in this example), _GDBN__ -displays the names of the program's sections, and a @samp{*} for each 2K -of data downloaded. (If you want to refresh _GDBN__ data on symbols or -on the executable file without downloading, use the _GDBN__ commands -@code{file} or @code{symbol-file}. These commands, and @code{load} -itself, are described in @ref{Files,,Commands to Specify Files}.) - -All the standard _GDBN__ facilities are at your disposal for controlling -the program on the H8/300; you can start the program with @code{run}, -set breakpoints with @code{break}, display data with @code{print} or -@code{x}, and so on. +At this point, you're ready to run or debug your program. From here on, +you can use all the usual _GDBN__ commands. The @code{break} command +sets breakpoints; the @code{run} command starts your program; +@code{print} or @code{x} display data; the @code{continue} command +resumes execution after stopping at a breakpoint. You can use the +@code{help} command at any time to find out more about _GDBN__ commands. Remember, however, that @emph{operating system} facilities aren't available on your H8/300; for example, if your program hangs, you can't -send an interrupt---but you can press the @sc{reset} switch! _GDBN__ -will see the effect of a @sc{reset} on the H8/300 board as a ``normal -exit'' of your program. +send an interrupt---but you can press the @sc{reset} switch! + +Use the @sc{reset} button on the H8/300 board +@itemize @bullet +@item +to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has +no way to pass an interrupt signal to the H8/300); and + +@item +to return to the _GDBN__ command prompt after your program finishes +normally. The communications protocol provides no other way for _GDBN__ +to detect program completion. +@end itemize + +In either case, _GDBN__ will see the effect of a @sc{reset} on the +H8/300 board as a ``normal exit'' of your program. _fi__(_H8__) |