gdb/doc/gdb.tgts-m4

   1 _dnl__                                                          -*- Texinfo -*-
   2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
   3 _dnl__ This file is part of the source for the GDB manual.
   4 _dnl__ $Id$
   5 @node     Targets, Controlling _GDBN__, _GDBN__ Files, Top
   6 @chapter Specifying a Debugging Target
   7 @cindex debugging target
   8 @kindex target
   9 A @dfn{target} is an interface between the debugger and a particular
  10 kind of file or process.
  11
  12 Often, you will be able to run _GDBN__ in the same host environment as the
  13 program you are debugging; in that case, the debugging target can just be
  14 specified as a side effect of the @code{file} or @code{core} commands.
  15 When you need more flexibility---for example, running _GDBN__ on a
  16 physically separate host, controlling standalone systems over a
  17 serial port, or realtime systems over a TCP/IP connection---you can use
  18 the @code{target} command.
  19
  20 @menu
  21 * Active Targets::              Active Targets
  22 * Target Commands::             Commands for Managing Targets
  23 * Remote::                      Remote Debugging
  24 @end menu
  25
  26 @node Active Targets, Target Commands, Targets, Targets
  27 @section Active Targets
  28 @cindex stacking targets
  29 @cindex active targets
  30 @cindex multiple targets
  31
  32 Targets are managed in three @dfn{strata} that correspond to different
  33 classes of target: processes, core files, and executable files.  This
  34 allows you to (for example) start a process and inspect its activity
  35 without abandoning your work on a core file.
  36
  37 More than one target can potentially respond to a request.  In
  38 particular, when you access memory _GDBN__ will examine the three strata of
  39 targets until it finds a target that can handle that particular address.
  40 Strata are always examined in a fixed order: first a process if there is
  41 one, then a core file if there is one, and finally an executable file if
  42 there is one of those.
  43
  44 When you specify a new target in a given stratum, it replaces any target
  45 previously in that stratum.
  46
  47 To get rid of a target without replacing it, use the @code{detach}
  48 command.  The related command @code{attach} provides you with a way of
  49 choosing a particular running process as a new target. @xref{Attach}.
  50
  51 @node Target Commands, Remote, Active Targets, Targets
  52 @section Commands for Managing Targets
  53
  54 @table @code
  55 @item target @var{type} @var{parameters}
  56 Connects the _GDBN__ host environment to a target machine or process.  A
  57 target is typically a protocol for talking to debugging facilities.  You
  58 use the argument @var{type} to specify the type or protocol of the
  59 target machine.
  60
  61 Further @var{parameters} are interpreted by the target protocol, but
  62 typically include things like device names or host names to connect
  63 with, process numbers, and baud rates.
  64
  65 The @code{target} command will not repeat if you press @key{RET} again
  66 after executing the command.
  67
  68 @item help target
  69 @kindex help target
  70 Displays the names of all targets available.  To display targets
  71 currently selected, use either @code{info target} or @code{info files}
  72 (@pxref{Files}).
  73
  74 @item help target @var{name}
  75 Describe a particular target, including any parameters necessary to
  76 select it.
  77 @end table
  78
  79 Here are some common targets (available, or not, depending on the _GDBN__
  80 configuration):
  81
  82 @table @code
  83 @item target exec @var{prog}
  84 @kindex target exec
  85 An executable file.  @samp{target exec @var{prog}} is the same as
  86 @samp{exec-file @var{prog}}.
  87
  88 @item target core @var{filename}
  89 @kindex target core
  90 A core dump file.  @samp{target core @var{filename}} is the same as
  91 @samp{core-file @var{filename}}.
  92
  93 @item target remote @var{dev}
  94 @kindex target remote
  95 Remote serial target in _GDBN__-specific protocol.  The argument @var{dev}
  96 specifies what serial device to use for the connection (e.g.
  97 @file{/dev/ttya}). @xref{Remote}.
  98
  99 _if__(_AMD29K__)
 100 @item target amd-eb @var{dev} @var{speed} @var{PROG}
 101 @kindex target amd-eb
 102 @cindex AMD EB29K
 103 Remote PC-resident AMD EB29K board, attached over serial lines.
 104 @var{dev} is the serial device, as for @code{target remote};
 105 @var{speed} allows you to specify the linespeed; and @var{PROG} is the
 106 name of the program to be debugged, as it appears to DOS on the PC.
 107 @xref{EB29K Remote}.
 108
 109 _fi__(_AMD29K__)
 110 _if__(_I960__)
 111 @item target nindy @var{devicename}
 112 @kindex target nindy
 113 An Intel 960 board controlled by a Nindy Monitor.  @var{devicename} is
 114 the name of the serial device to use for the connection, e.g.
 115 @file{/dev/ttya}.  @xref{i960-Nindy Remote}.
 116
 117 _fi__(_I960__)
 118 _if__(_VXWORKS__)
 119 @item target vxworks @var{machinename}
 120 @kindex target vxworks
 121 A VxWorks system, attached via TCP/IP.  The argument @var{machinename}
 122 is the target system's machine name or IP address.
 123 @xref{VxWorks Remote}.
 124 _fi__(_VXWORKS__)
 125 @end table
 126
 127 _if__(_GENERIC__)
 128 Different targets are available on different configurations of _GDBN__; your
 129 configuration may have more or fewer targets.
 130 _fi__(_GENERIC__)
 131
 132 @node Remote,  , Target Commands, Targets
 133 @section Remote Debugging
 134 @cindex remote debugging
 135
 136 _if__(_GENERIC__)
 137 @menu
 138 _include__(gdb.inv.m-m4)<>_dnl__
 139 @end menu
 140 _fi__(_GENERIC__)
 141
 142 If you are trying to debug a program running on a machine that can't run
 143 _GDBN__ in the usual way, it is often useful to use remote debugging.  For
 144 example, you might use remote debugging on an operating system kernel, or on
 145 a small system which does not have a general purpose operating system
 146 powerful enough to run a full-featured debugger.
 147
 148 Some configurations of _GDBN__ have special serial or TCP/IP interfaces
 149 to make this work with particular debugging targets.  In addition,
 150 _GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
 151 not specific to any particular target system) which you can use if you
 152 write the remote stubs---the code that will run on the remote system to
 153 communicate with _GDBN__.
 154
 155 To use the _GDBN__ remote serial protocol, the program to be debugged on
 156 the remote machine needs to contain a debugging stub which talks to
 157 _GDBN__ over the serial line.  Several working remote stubs are
 158 distributed with _GDBN__; see the @file{README} file in the _GDBN__
 159 distribution for more information.
 160
 161 For details of this communication protocol, see the comments in the
 162 _GDBN__ source file @file{remote.c}.
 163
 164 To start remote debugging, first run _GDBN__ and specify as an executable file
 165 the program that is running in the remote machine.  This tells _GDBN__ how
 166 to find the program's symbols and the contents of its pure text.  Then
 167 establish communication using the @code{target remote} command with a device
 168 name as an argument.  For example:
 169
 170 @example
 171 target remote /dev/ttyb
 172 @end example
 173
 174 @noindent
 175 if the serial line is connected to the device named @file{/dev/ttyb}.  This
 176 will stop the remote machine if it is not already stopped.
 177
 178 Now you can use all the usual commands to examine and change data and to
 179 step and continue the remote program.
 180
 181 To resume the remote program and stop debugging it, use the @code{detach}
 182 command.
 183
 184 Other remote targets may be available in your
 185 configuration of _GDBN__; use @code{help targets} to list them.
 186
 187 _if__(_GENERIC__)
 188 _include__(gdb.inv.s-m4)
 189 @c Text on starting up GDB in various specific cases; it goes up front
 190 @c in manuals configured for any of those particular situations, here
 191 @c otherwise.
 192 _fi__(_GENERIC__)