gdbinv-s.m4.in

早期freebsd实现

_if__(_ST2000__)
@node ST2000 Remote
@subsection _GDBN__ with a Tandem ST2000

To connect your ST2000 to the host system, see the manufacturer's
manual.  Once the ST2000 is physically attached, you can run

@example
target st2000 @var{dev} @var{speed}
@end example

@noindent
to establish it as your debugging environment.  

The @code{load} and @code{attach} commands are @emph{not} defined for
this target; you must load your program into the ST2000 as you normally
would for standalone operation.  _GDBN__ will read debugging information
(such as symbols) from a separate, debugging version of the program
available on your host computer.
@c FIXME!! This is terribly vague; what little content is here is
@c basically hearsay.

@cindex ST2000 auxiliary commands
These auxiliary _GDBN__ commands are available to help you with the ST2000
environment:

@table @code
@item st2000 @var{command}
@kindex st2000 @var{cmd}
@cindex STDBUG commands (ST2000)
@cindex commands to STDBUG (ST2000)
Send a @var{command} to the STDBUG monitor.  See the manufacturer's
manual for available commands.

@item connect
@cindex connect (to STDBUG)
Connect the controlling terminal to the STDBUG command monitor.  When
you are done interacting with STDBUG, typing either of two character
sequences will get you back to the _GDBN__ command prompt:
@kbd{@key{RET}~.} (Return, followed by tilde and period) or
@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
@end table
_fi__(_ST2000__)

_if__(_VXWORKS__)
@node VxWorks Remote
@subsection _GDBN__ and VxWorks
@cindex VxWorks

_GDBN__ enables developers to spawn and debug tasks running on networked
VxWorks targets from a Unix host.  Already-running tasks spawned from
the VxWorks shell can also be debugged.  _GDBN__ uses code that runs on
both the UNIX host and on the VxWorks target.  The program
@code{_GDBP__} is installed and executed on the UNIX host.

The following information on connecting to VxWorks was current when
this manual was produced; newer releases of VxWorks may use revised
procedures.

The remote debugging interface (RDB) routines are installed and executed
on the VxWorks target.  These routines are included in the VxWorks library
@file{rdb.a} and are incorporated into the system image when source-level
debugging is enabled in the VxWorks configuration.

@kindex INCLUDE_RDB
If you wish, you can define @code{INCLUDE_RDB} in the VxWorks
configuration file @file{configAll.h} to include the RDB interface
routines and spawn the source debugging task @code{tRdbTask} when
VxWorks is booted.  For more information on configuring and remaking
_if__(_FSF__)
VxWorks, see the manufacturer's manual.
_fi__(_FSF__)
_if__(!_FSF__)
VxWorks, see the @cite{VxWorks Programmer's Guide}.
_fi__(!_FSF__)

Once you have included the RDB interface in your VxWorks system image
and set your Unix execution search path to find _GDBN__, you are ready
to run _GDBN__.  From your UNIX host, type:

@smallexample
% _GDBP__
@end smallexample

_GDBN__ will come up showing the prompt:

@smallexample
(_GDBP__)
@end smallexample

@menu
* VxWorks connection::          Connecting to VxWorks
* VxWorks download::            VxWorks Download
* VxWorks attach::              Running Tasks
@end menu

@node VxWorks connection
@subsubsection Connecting to VxWorks

The _GDBN__ command @code{target} lets you connect to a VxWorks target on the
network.  To connect to a target whose host name is ``@code{tt}'', type:

@smallexample
(_GDBP__) target vxworks tt
@end smallexample

_GDBN__ will display a message similar to the following:

@smallexample
Attaching remote machine across net... Success!
@end smallexample

_GDBN__ will then attempt to read the symbol tables of any object modules
loaded into the VxWorks target since it was last booted.  _GDBN__ locates
these files by searching the directories listed in the command search
path (@pxref{Environment, ,Your Program's Environment}); if it fails
to find an object file, it will display a message such as:

@smallexample
prog.o: No such file or directory.
@end smallexample

This will cause the @code{target} command to abort.  When this happens,
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
@subsubsection VxWorks Download

@cindex download to VxWorks
If you have connected to the VxWorks target and you want to debug an
object that has not yet been loaded, you can use the _GDBN__ @code{load}
command to download a file from UNIX to VxWorks incrementally.  The
object file given as an argument to the @code{load} command is actually
opened twice: first by the VxWorks target in order to download the code,
then by _GDBN__ in order to read the symbol table.  This can lead to
problems if the current working directories on the two systems differ.
It is simplest to set the working directory on both systems to the
directory in which the object file resides, and then to reference the
file by its name, without any path.  Thus, to load a program
@file{prog.o}, residing in @file{wherever/vw/demo/rdb}, on VxWorks type:

@smallexample
-> cd "wherever/vw/demo/rdb"
@end smallexample

On _GDBN__ type:

@smallexample
(_GDBP__) cd wherever/vw/demo/rdb 
(_GDBP__) load prog.o
@end smallexample

_GDBN__ will display a response similar to the following:

@smallexample
Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
@end smallexample

You can also use the @code{load} command to reload an object module
after editing and recompiling the corresponding source file.  Note that
this will cause _GDBN__ to delete all currently-defined breakpoints,
auto-displays, and convenience variables, and to clear the value
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
@subsubsection Running Tasks

@cindex running VxWorks tasks
You can also attach to an existing task using the @code{attach} command as
follows:

@smallexample
(_GDBP__) attach @var{task}
@end smallexample

@noindent
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__)
@node Hitachi H8/300 Remote
@subsection _GDBN__ and the Hitachi 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 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}.

@kindex speed
@cindex serial line speed for H8/300
@code{gdb83} has another special command to set the communications speed
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}.

@smallexample
(eg-C:\H8300\TEST) mode com2:9600,n,8,1,p

Resident portion of MODE loaded

COM2: 9600, n, 8, 1, p

(eg-C:\H8300\TEST) asynctsr 2
@end smallexample

@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}.)

@smallexample
(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 smallexample

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!  

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__)