Fri Sep 4 18:53:57 1992 Roland H. Pesch (pesch@fowanton.cygnus.com)

[deliverable/binutils-gdb.git] / gdb / doc / gdb.tgts-m4

_dnl__								-*- Texinfo -*-
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
_dnl__ This file is part of the source for the GDB manual.
@c M4 FRAGMENT: $Id$
@node     Targets, Controlling _GDBN__, _GDBN__ Files, Top
@chapter Specifying a Debugging Target 
@cindex debugging target
@kindex target
A @dfn{target} is an interface between the debugger and a particular 
kind of file or process.  

Often, you will be able to run _GDBN__ in the same host environment as the
program you are debugging; in that case, the debugging target can just be
specified as a side effect of the @code{file} or @code{core} commands.
When you need more flexibility---for example, running _GDBN__ on a
physically separate host, controlling standalone systems over a
serial port, or realtime systems over a TCP/IP connection---you can use
the @code{target} command.

@menu
* Active Targets::		Active Targets
* Target Commands::		Commands for Managing Targets
* Remote::			Remote Debugging
@end menu

@node Active Targets, Target Commands, Targets, Targets
@section Active Targets
@cindex stacking targets
@cindex active targets
@cindex multiple targets

Targets are managed in three @dfn{strata} that correspond to different
classes of target: processes, core files, and executable files.  This
allows you to (for example) start a process and inspect its activity
without abandoning your work on a core file.

More than one target can potentially respond to a request.  In
particular, when you access memory _GDBN__ will examine the three strata of
targets until it finds a target that can handle that particular address.
Strata are always examined in a fixed order: first a process if there is
one, then a core file if there is one, and finally an executable file if
there is one of those.

When you specify a new target in a given stratum, it replaces any target
previously in that stratum.

To get rid of a target without replacing it, use the @code{detach}
command.  The related command @code{attach} provides you with a way of
choosing a particular running process as a new target. @xref{Attach}.

@node Target Commands, Remote, Active Targets, Targets
@section Commands for Managing Targets

@table @code
@item target @var{type} @var{parameters}
Connects the _GDBN__ host environment to a target machine or process.  A
target is typically a protocol for talking to debugging facilities.  You
use the argument @var{type} to specify the type or protocol of the
target machine.

Further @var{parameters} are interpreted by the target protocol, but
typically include things like device names or host names to connect
with, process numbers, and baud rates.  

The @code{target} command will not repeat if you press @key{RET} again
after executing the command.

@item help target
@kindex help target
Displays the names of all targets available.  To display targets
currently selected, use either @code{info target} or @code{info files}
(@pxref{Files}).

@item help target @var{name}
Describe a particular target, including any parameters necessary to
select it.
@end table

Here are some common targets (available, or not, depending on the _GDBN__
configuration):

@table @code
@item target exec @var{prog}
@kindex target exec
An executable file.  @samp{target exec @var{prog}} is the same as
@samp{exec-file @var{prog}}.

@item target core @var{filename}
@kindex target core
A core dump file.  @samp{target core @var{filename}} is the same as
@samp{core-file @var{filename}}.

@item target remote @var{dev}
@kindex target remote
Remote serial target in _GDBN__-specific protocol.  The argument @var{dev}
specifies what serial device to use for the connection (e.g.
@file{/dev/ttya}). @xref{Remote}.

_if__(_AMD29K__)
@item target amd-eb @var{dev} @var{speed} @var{PROG}
@kindex target amd-eb
@cindex AMD EB29K
Remote PC-resident AMD EB29K board, attached over serial lines.
@var{dev} is the serial device, as for @code{target remote};
@var{speed} allows you to specify the linespeed; and @var{PROG} is the
name of the program to be debugged, as it appears to DOS on the PC.
@xref{EB29K Remote}.

_fi__(_AMD29K__)
_if__(_I960__)
@item target nindy @var{devicename}
@kindex target nindy
An Intel 960 board controlled by a Nindy Monitor.  @var{devicename} is
the name of the serial device to use for the connection, e.g.
@file{/dev/ttya}.  @xref{i960-Nindy Remote}.

_fi__(_I960__)
_if__(_VXWORKS__)
@item target vxworks @var{machinename}
@kindex target vxworks
A VxWorks system, attached via TCP/IP.  The argument @var{machinename}
is the target system's machine name or IP address.
@xref{VxWorks Remote}.
_fi__(_VXWORKS__)
@end table

_if__(_GENERIC__)
Different targets are available on different configurations of _GDBN__; your
configuration may have more or fewer targets.
_fi__(_GENERIC__)

@node Remote,  , Target Commands, Targets
@section Remote Debugging
@cindex remote debugging

_if__(_GENERIC__)
@menu
_include__(gdb.inv.m-m4)<>_dnl__
@end menu
_fi__(_GENERIC__)

If you are trying to debug a program running on a machine that can't run
_GDBN__ in the usual way, it is often useful to use remote debugging.  For
example, you might use remote debugging on an operating system kernel, or on
a small system which does not have a general purpose operating system
powerful enough to run a full-featured debugger.  

Some configurations of _GDBN__ have special serial or TCP/IP interfaces
to make this work with particular debugging targets.  In addition,
_GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
not specific to any particular target system) which you can use if you
write the remote stubs---the code that will run on the remote system to
communicate with _GDBN__.

To use the _GDBN__ remote serial protocol, the program to be debugged on
the remote machine needs to contain a debugging stub which talks to
_GDBN__ over the serial line.  Several working remote stubs are
distributed with _GDBN__; see the @file{README} file in the _GDBN__
distribution for more information.

For details of this communication protocol, see the comments in the
_GDBN__ source file @file{remote.c}.

To start remote debugging, first run _GDBN__ and specify as an executable file
the program that is running in the remote machine.  This tells _GDBN__ how
to find the program's symbols and the contents of its pure text.  Then
establish communication using the @code{target remote} command with a device
name as an argument.  For example:

@example
target remote /dev/ttyb
@end example

@noindent
if the serial line is connected to the device named @file{/dev/ttyb}.  This
will stop the remote machine if it is not already stopped.

Now you can use all the usual commands to examine and change data and to
step and continue the remote program.

To resume the remote program and stop debugging it, use the @code{detach}
command.

Other remote targets may be available in your
configuration of _GDBN__; use @code{help targets} to list them.  

_if__(_GENERIC__)
_include__(gdb.inv.s-m4)
@c Text on starting up GDB in various specific cases; it goes up front
@c in manuals configured for any of those particular situations, here
@c otherwise. 
_fi__(_GENERIC__)