Commit | Line | Data |
---|---|---|
9bcc06ef RP |
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__) |