From patchwork Thu Nov 12 00:59:59 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Don Breazeal X-Patchwork-Id: 9650 Received: (qmail 84272 invoked by alias); 12 Nov 2015 01:00:11 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 84231 invoked by uid 89); 12 Nov 2015 01:00:09 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.9 required=5.0 tests=AWL, BAYES_50, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 12 Nov 2015 01:00:04 +0000 Received: from svr-orw-fem-06.mgc.mentorg.com ([147.34.97.120]) by relay1.mentorg.com with esmtp id 1ZwgF7-0004yl-HI from Don_Breazeal@mentor.com ; Wed, 11 Nov 2015 17:00:01 -0800 Received: from build4-lucid-cs (147.34.91.1) by SVR-ORW-FEM-06.mgc.mentorg.com (147.34.97.120) with Microsoft SMTP Server id 14.3.224.2; Wed, 11 Nov 2015 17:00:01 -0800 Received: by build4-lucid-cs (Postfix, from userid 1905) id 9270F41132; Wed, 11 Nov 2015 17:00:00 -0800 (PST) From: Don Breazeal To: , Subject: Re: [PATCH 3/3] Target remote mode fork and exec docs Date: Wed, 11 Nov 2015 16:59:59 -0800 Message-ID: <1447290000-31393-1-git-send-email-donb@codesourcery.com> In-Reply-To: <83a8qqql38.fsf@gnu.org> MIME-Version: 1.0 X-IsSubscribed: yes Hi Eli, Thanks for the review. On 11/7/2015 12:18 AM, Eli Zaretskii wrote: >> From: Don Breazeal >> Date: Fri, 6 Nov 2015 15:56:28 -0800 >> >> diff --git a/gdb/NEWS b/gdb/NEWS >> index b2b1e99..166a6ca 100644 >> --- a/gdb/NEWS >> +++ b/gdb/NEWS >> @@ -87,6 +87,14 @@ set remote exec-event-feature-packet >> show remote exec-event-feature-packet >> Set/show the use of the remote exec event feature. >> >> +* Target remote mode fork and exec events >> + >> + ** GDB now has support for fork and exec events on target remote mode >> + Linux targets. For such targets with Linux kernels 2.5.46 and later, >> + this enables follow-fork-mode, detach-on-fork and fork and exec >> + catchpoints. Note that follow-exec-mode is not supported, because >> + target remote mode does not support the 'run' command. >> + >> *** Changes in GDB 7.10 > > This part is OK. > >> -@value{GDBN} needs an unstripped copy of your program to access symbol >> -and debugging information. Some remote targets (@pxref{qXfer >> -executable filename read}, and @pxref{Host I/O Packets}) allow >> -@value{GDBN} to access program files over the same connection used to >> -communicate with @value{GDBN}. With such a target, if the remote >> -program is unstripped, the only command you need is @code{target >> -remote}. Otherwise, start up @value{GDBN} using the name of the local >> +@value{GDBN} supports two types of remote connections, @kbd{target remote} >> +mode and @kbd{target extended-remote} mode. There are several major >> +differences between the two. In @kbd{target extended-remote} mode, GDB > ^^^ > @value{GDBN} > >> +stays connected to @code{gdbserver} after the debugged program exits or you >> +detach from it, and @code{gdbserver} provides support for the @code{run} >> +and @code{attach} commands. > > Saying "several major differences" and then neither describing them > nor providing a reference (not even just "described below") will leave > the reader confused, I think. How about a short summary of the > differences, e.g. as an itemized list, here? > > Also, does the sentence that follow (the last one in the above > excerpt) need to be here? It reads strange, especially since it > doesn't seem like it belongs to the aforementioned differences. Maybe > you could reword it so it did contrast the two modes. > > Alternatively, perhaps the following subsections are better rearranged > as extended descriptions of each of the differences, e.g. using @table. > Right now, they read somewhat confusingly, because the description > jumps between the two modes without providing any intermediate summary > for the reader, and thus it is easy to become confused as to what mode > and what difference you are describing. Some better organization of > the same material could help the reader organize their thoughts and > come out with a better understanding of the differences. I went with the latter suggestion. I hope my interpretation of this doesn't violate any doc conventions. In the previous version I had tried to leave some paragraphs unmodified, just reorganizing where they were. I've been more liberal in my changes in this version. > > Last, but not least: please consider adding @cindex entries to each of > the subsections, with text that describes the main subject of each > subsection. In many cases, just the down-cased name of the section is > a good starting point. This will help the readers find the subsection > quickly using the Info index-searching commands, which is important > for using the manual as a reference. I added a number of these. > >> +@item >> +Finally, connect to your target. For TCP connections, you must start up >> +@code{gdbserver} prior to using the @kbd{target remote} or >> +@kbd{target extended-remote} command. Otherwise you may get an error >> +whose text depends on the host system, but which usually looks something >> +like @samp{Connection refused}. Don't use the @code{load} command in >> +@value{GDBN} when using @code{gdbserver}, since the program is already on >> +the target. > > There's some inconsistency in your usage of @code and @kbd markup for > commands. In general, the correct markup is @kbd when the context is > about commands typed by the user, and @code otherwise. (The GDB > manual almost never uses @kbd, for historical reasons, btw.) You have > changed some of the @code to @kbd regardless of context, or so it > seems. But in the above passage, you use @code as well, so I'm unsure > what is your rule for selecting one or the other. I misunderstood the convention here. Thanks for clarifying. I think I have more-or-less restored things. Basically, as I understand it, the rule is: use @kbd where the sentence is saying "type @kbd{foo}" or "use @kbd{foo}", but use @code if it is just referring to it, like "in the case of the @code{foo} command". > >> @item target remote @var{serial-device} >> -@cindex serial line, @code{target remote} >> +@item target extended-remote @var{serial-device} > ^^^^^ > Should be @itemx. I fixed all of these. >> -@subsection Running @code{gdbserver} >> +@subsection Running gdbserver > > Not sure why you removed the markup from "gdbserver" here. My ignorance about how to implement cross-references. I've figured out the right thing to do, and restored the markup. Let me know what you think about this version. thanks --Don ----------------------- This patch implements documentation updates for target remote mode fork and exec events. A summary of the rationale for the changes made here: * Types of Remote Connections -- explain that the two protocols exist, and describe the differences between the two. * Host and Target Files -- collect paragraphs dealing with how to locate symbol files from original sections "Connecting to a remote target" and "Using the gdbserver program | Connecting to gdbserver". * Remote connection commands -- used to be the bulk of "Connecting to a remote target". Added "target extended-remote" commands and information. * Multi-Process Mode for gdbserver -- delete section, move information to "Types of Remote Connections". * Other assorted cleanups, @cindex entries, @anchor and @pxref entries. Thanks, --Don gdb/ 2015-11-11 Don Breazeal * NEWS: Announce fork and exec event support for target remote. gdb/doc/ 2015-11-11 Don Breazeal * gdb.texinfo (Forks): Correct Linux kernel version where fork and exec events are supported, add notes about support of these events in target remote mode. (Connecting): Reorganize and clarify distinctions between target remote, extended-remote, and multiprocess. Reorganize related text from separate sections into new sections. (Server): Note effects of target extended-remote mode. Delete section on Multi-Process Mode for gdbserver. Move some text to "Connecting" node. --- gdb/NEWS | 8 ++ gdb/doc/gdb.texinfo | 270 +++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 201 insertions(+), 77 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index b2b1e99..166a6ca 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -87,6 +87,14 @@ set remote exec-event-feature-packet show remote exec-event-feature-packet Set/show the use of the remote exec event feature. +* Target remote mode fork and exec events + + ** GDB now has support for fork and exec events on target remote mode + Linux targets. For such targets with Linux kernels 2.5.46 and later, + this enables follow-fork-mode, detach-on-fork and fork and exec + catchpoints. Note that follow-exec-mode is not supported, because + target remote mode does not support the 'run' command. + *** Changes in GDB 7.10 * Support for process record-replay and reverse debugging on aarch64*-linux* diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 3c1f785..c06e95d 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -3133,10 +3133,11 @@ the child process just like any other process which you attached to. On some systems, @value{GDBN} provides support for debugging programs that create additional processes using the @code{fork} or @code{vfork} functions. Currently, the only platforms with this feature are HP-UX (11.x and later -only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later). +only?) and @sc{gnu}/Linux (kernel version 2.5.46 and later). -The fork debugging commands are supported in both native mode and when -connected to @code{gdbserver} using @kbd{target extended-remote}. +The fork debugging commands are supported in native mode and when +connected to @code{gdbserver} in either @code{target remote} mode or +@code{target extended-remote} mode. By default, when a program forks, @value{GDBN} will continue to debug the parent process and the child process will run unimpeded. @@ -3282,6 +3283,11 @@ Program exited normally. @end table @end table +@code{follow-exec-mode} is supported in native mode and +@code{target extended-remote} mode. It has no real effect in +@code{target remote} mode since the run command is not supported in that +mode. + You can use the @code{catch} command to make @value{GDBN} stop whenever a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set Catchpoints, ,Setting Catchpoints}. @@ -19220,28 +19226,150 @@ configuration of @value{GDBN}; use @code{help target} to list them. @node Connecting @section Connecting to a Remote Target +@cindex remote debugging, connecting +@cindex @code{gdbserver}, connecting +@cindex remote debugging, types of connections +@cindex @code{gdbserver}, types of connections +@cindex @code{gdbserver}, @code{target remote} mode +@cindex @code{gdbserver}, @code{target extended-remote} mode + +This section describes how to connect to a remote target, including the +types of connections and their differences, how to set up executable and +symbol files on the host and target, and the commands used for +connecting to and disconnecting from the remote target. + +@subsection Types of Remote Connections + +@value{GDBN} supports two types of remote connections, @code{target remote} +mode and @code{target extended-remote} mode. Note that many remote targets +support only @code{target remote} mode. There are several major +differences between the two types of connections, enumerated here: + +@table @asis + +@cindex remote debugging, detach and program exit +@item Result of detach or program exit + +@strong{target remote mode:} When the debugged program exits or you +detach from it, @value{GDBN} disconnects from the target. When using +@code{gdbserver}, @code{gdbserver} will exit. + +@strong{target extended-remote mode:} When the debugged program exits or +you detach from it, @value{GDBN} remains connected to the target, even +though no program is running. You can rerun the program, attach to a +running program, or use @code{monitor} commands specific to the target. + +When using @code{gdbserver} in this case, it does not exit unless it was +invoked using the @option{--once} option. If the @option{--once} option +was not used, you can ask @code{gdbserver} to exit using the +@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}). + +@item Specifying the program to debug + +For both connection types you use the @code{file} command to specify the +program on the host system. If you are using @code{gdbserver} there are +some differences in how to specify the location of the program on the +target. + +@strong{target remote mode:} You must either specify the program to debug +on the @code{gdbserver} command line or use the @option{--attach} option +(@pxref{Attaching to a program,,Attaching to a Running Program}). + +@cindex @option{--multi}, @code{gdbserver} option +@strong{target extended-remote mode:} You may specify the program to debug +on the @code{gdbserver} command line, or you can load the program or attach +to it using @value{GDBN} commands after connecting to @code{gdbserver}. + +@anchor{Types of Remote Connnections: --multi option} +You can start @code{gdbserver} without supplying an initial command to run +or process ID to attach. To do this, use the @option{--multi} command line +option. Then you can connect using @code{target extended-remote} and start +the program you want to debug (see below for details on using the +@code{run} command in this scenario). Note that the conditions under which +@code{gdbserver} terminates depend on how @value{GDBN} connects to it +(@code{target remote} or @code{target extended-remote}). The +@option{--multi} option to @code{gdbserver} has no influence on that. -@value{GDBN} needs an unstripped copy of your program to access symbol -and debugging information. Some remote targets (@pxref{qXfer -executable filename read}, and @pxref{Host I/O Packets}) allow -@value{GDBN} to access program files over the same connection used to -communicate with @value{GDBN}. With such a target, if the remote -program is unstripped, the only command you need is @code{target -remote}. Otherwise, start up @value{GDBN} using the name of the local +@item The @code{run} command +@strong{target remote mode:} The @code{run} command is not supported. +Once a connection has been established, you can use all the usual +@value{GDBN} commands to examine and change data. The remote program +is already running, so you can use commands like @kbd{step} and +@kbd{continue}. + +@strong{target extended-remote mode:} The @code{run} command is supported. +The @code{run} command uses the value set by @code{set remote exec-file} +(@pxref{set remote exec-file}) to select the program to run. Command line +arguments are supported, except for wildcard expansion and I/O +redirection (@pxref{Arguments}). + +If you specify the program to debug on the command line, then the +@code{run} command is not required to start execution, and you can +resume using commands like @kbd{step} and @kbd{continue} as with +@code{target remote} mode. + +@anchor{Types of Remote Connections: Attaching} +@item Attaching +@strong{target remote mode:} The @value{GDBN} command @code{attach} is +not supported. To attach to a running program using @code{gdbserver}, you +must use the @option{--attach} option (@pxref{Running gdbserver}). + +@strong{target extended-remote mode:} To attach to a running program, +you may use the @code{attach} command after the connection has been +established. If you are using @code{gdbserver}, you may also invoke +@code{gdbserver} using the @option{--attach} option +(@pxref{Running gdbserver}). + +@end table + +@anchor{Host and target files} +@subsection Host and Target Files +@cindex remote debugging, symbol files +@cindex symbol files, remote debugging + +@value{GDBN}, running on the host, needs access to symbol and debugging +information for your program running on the target. This requires +access to an unstripped copy of your program, and possibly any associated +symbol files. Note that this section applies equally to both @code{target +remote} mode and @code{target extended-remote} mode. + +Some remote targets (@pxref{qXfer executable filename read}, and +@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over +the same connection used to communicate with @value{GDBN}. With such a +target, if the remote program is unstripped, the only command you need is +@code{target remote} (or @code{target extended-remote}). + +If the remote program is stripped, or the target does not support remote +program file access, start up @value{GDBN} using the name of the local unstripped copy of your program as the first argument, or use the -@code{file} command. +@code{file} command. Use @code{set sysroot} to specify the location (on +the host) of target libraries (unless your @value{GDBN} was compiled with +the correct sysroot using @code{--with-sysroot}). Alternatively, you +may use @code{set solib-search-path} to specify how @value{GDBN} locates +target libraries. + +The symbol file and target libraries must exactly match the executable +and libraries on the target, with one exception: the files on the host +system should not be stripped, even if the files on the target system +are. Mismatched or missing files will lead to confusing results +during debugging. On @sc{gnu}/Linux targets, mismatched or missing +files may also prevent @code{gdbserver} from debugging multi-threaded +programs. -@cindex @code{target remote} +@subsection Remote Connection Commands +@cindex remote connection commands @value{GDBN} can communicate with the target over a serial line, or over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In each case, @value{GDBN} uses the same protocol for debugging your program; only the medium carrying the debugging packets varies. The -@code{target remote} command establishes a connection to the target. -Its arguments indicate which medium to use: +@code{target remote} and @code{target extended-remote} commands +establish a connection to the target. Both commands accept the same +arguments, which indicate the medium to use: @table @code @item target remote @var{serial-device} +@itemx target extended-remote @var{serial-device} @cindex serial line, @code{target remote} Use @var{serial-device} to communicate with the target. For example, to use a serial line connected to the device named @file{/dev/ttyb}: @@ -19257,6 +19385,8 @@ If you're using a serial line, you may want to give @value{GDBN} the @item target remote @code{@var{host}:@var{port}} @itemx target remote @code{tcp:@var{host}:@var{port}} +@itemx target extended-remote @code{@var{host}:@var{port}} +@itemx target extended-remote @code{tcp:@var{host}:@var{port}} @cindex @acronym{TCP} port, @code{target remote} Debug using a @acronym{TCP} connection to @var{port} on @var{host}. The @var{host} may be either a host name or a numeric @acronym{IP} @@ -19285,6 +19415,7 @@ target remote :1234 Note that the colon is still required here. @item target remote @code{udp:@var{host}:@var{port}} +@itemx target extended-remote @code{udp:@var{host}:@var{port}} @cindex @acronym{UDP} port, @code{target remote} Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: @@ -19299,6 +19430,7 @@ can silently drop packets on busy or unreliable networks, which will cause havoc with your debugging session. @item target remote | @var{command} +@itemx target extended-remote | @var{command} @cindex pipe, @code{target remote} to Run @var{command} in the background and communicate with it using a pipe. The @var{command} is a shell command, to be parsed and expanded @@ -19314,11 +19446,6 @@ program has already exited, this will have no effect.) @end table -Once the connection has been established, you can use all the usual -commands to examine and change data. The remote program is already -running; you can use @kbd{step} and @kbd{continue}, and you do not -need to use @kbd{run}. - @cindex interrupting remote programs @cindex remote programs, interrupting Whenever @value{GDBN} is waiting for the remote program, if you type the @@ -19332,10 +19459,13 @@ Interrupted while waiting for the program. Give up (and stop debugging it)? (y or n) @end smallexample -If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. -(If you decide you want to try again later, you can use @samp{target -remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} -goes back to waiting. +In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons +the remote debugging session. (If you decide you want to try again later, +you can use @kbd{target remote} again to connect once more.) If you type +@kbd{n}, @value{GDBN} goes back to waiting. + +In @code{target extended-remote} mode, typing @kbd{n} will leave +@value{GDBN} connected to the target. @table @code @kindex detach (remote) @@ -19344,11 +19474,13 @@ When you have finished debugging the remote program, you can use the @code{detach} command to release it from @value{GDBN} control. Detaching from the target normally resumes its execution, but the results will depend on your particular remote stub. After the @code{detach} -command, @value{GDBN} is free to connect to another target. +command in @code{target remote} mode, @value{GDBN} is free to connect to +another target. In @code{target extended-remote} mode, @value{GDBN} is +still connected to the target. @kindex disconnect @item disconnect -The @code{disconnect} command behaves like @code{detach}, except that +The @code{disconnect} command closes the connection to the target, and the target is generally not resumed. It will wait for @value{GDBN} (this instance or another one) to connect and continue debugging. After the @code{disconnect} command, @value{GDBN} is again free to connect to @@ -19405,7 +19537,8 @@ Delete @var{targetfile} from the target system. @cindex remote connection without stubs @code{gdbserver} is a control program for Unix-like systems, which allows you to connect your program with a remote @value{GDBN} via -@code{target remote}---but without linking in the usual debugging stub. +@code{target remote} or @code{target extended-remote}---but without +linking in the usual debugging stub. @code{gdbserver} is not a complete replacement for the debugging stubs, because it requires essentially the same operating-system facilities @@ -19433,6 +19566,7 @@ target system with the same privileges as the user running @code{gdbserver}. @end quotation +@anchor{Running gdbserver} @subsection Running @code{gdbserver} @cindex arguments, to @code{gdbserver} @cindex @code{gdbserver}, command-line arguments @@ -19500,6 +19634,7 @@ Programs started with stdio-connected gdbserver have @file{/dev/null} for display through a pipe connected to gdbserver. Both @code{stdout} and @code{stderr} use the same pipe. +@anchor{Attaching to a program} @subsubsection Attaching to a Running Program @cindex attach to a program, @code{gdbserver} @cindex @option{--attach}, @code{gdbserver} option @@ -19511,8 +19646,12 @@ This is accomplished via the @code{--attach} argument. The syntax is: target> gdbserver --attach @var{comm} @var{pid} @end smallexample -@var{pid} is the process ID of a currently running process. It isn't necessary -to point @code{gdbserver} at a binary for the running process. +@var{pid} is the process ID of a currently running process. It isn't +necessary to point @code{gdbserver} at a binary for the running process. + +In @code{target extended-remote} mode, you can also attach using the +@value{GDBN} attach command +(@pxref{Types of Remote Connections: Attaching}). @pindex pidof You can debug processes by name instead of process ID if your target has the @@ -19526,41 +19665,10 @@ In case more than one copy of @var{program} is running, or @var{program} has multiple threads, most versions of @code{pidof} support the @code{-s} option to only return the first process ID. -@subsubsection Multi-Process Mode for @code{gdbserver} -@cindex @code{gdbserver}, multiple processes -@cindex multiple processes with @code{gdbserver} - -When you connect to @code{gdbserver} using @code{target remote}, -@code{gdbserver} debugs the specified program only once. When the -program exits, or you detach from it, @value{GDBN} closes the connection -and @code{gdbserver} exits. - -If you connect using @kbd{target extended-remote}, @code{gdbserver} -enters multi-process mode. When the debugged program exits, or you -detach from it, @value{GDBN} stays connected to @code{gdbserver} even -though no program is running. The @code{run} and @code{attach} -commands instruct @code{gdbserver} to run or attach to a new program. -The @code{run} command uses @code{set remote exec-file} (@pxref{set -remote exec-file}) to select the program to run. Command line -arguments are supported, except for wildcard expansion and I/O -redirection (@pxref{Arguments}). - -@cindex @option{--multi}, @code{gdbserver} option -To start @code{gdbserver} without supplying an initial command to run -or process ID to attach, use the @option{--multi} command line option. -Then you can connect using @kbd{target extended-remote} and start -the program you want to debug. - -In multi-process mode @code{gdbserver} does not automatically exit unless you -use the option @option{--once}. You can terminate it by using -@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the -conditions under which @code{gdbserver} terminates depend on how @value{GDBN} -connects to it (@kbd{target remote} or @kbd{target extended-remote}). The -@option{--multi} option to @code{gdbserver} has no influence on that. - @subsubsection TCP port allocation lifecycle of @code{gdbserver} -This section applies only when @code{gdbserver} is run to listen on a TCP port. +This section applies only when @code{gdbserver} is run to listen on a TCP +port. @code{gdbserver} normally terminates after all of its debugged processes have terminated in @kbd{target remote} mode. On the other hand, for @kbd{target @@ -19591,6 +19699,12 @@ instance closes its port after the first connection. @anchor{Other Command-Line Arguments for gdbserver} @subsubsection Other Command-Line Arguments for @code{gdbserver} +You can use the @option{--multi} option to start @code{gdbserver} without +specifying a program to debug or a process to attach to. Then you can +attach in @code{target extended-remote} mode and run or attach to a +program. For more information, +@pxref{Types of Remote Connnections: --multi option}. + @cindex @option{--debug}, @code{gdbserver} option The @option{--debug} option tells @code{gdbserver} to display extra status information about the debugging process. @@ -19642,32 +19756,34 @@ $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog @subsection Connecting to @code{gdbserver} -Run @value{GDBN} on the host system. +The basic procedure for connecting to the remote target is: +@itemize -First make sure you have the necessary symbol files. Load symbols for -your application using the @code{file} command before you connect. Use -@code{set sysroot} to locate target libraries (unless your @value{GDBN} -was compiled with the correct sysroot using @code{--with-sysroot}). +@item +Run @value{GDBN} on the host system. -The symbol file and target libraries must exactly match the executable -and libraries on the target, with one exception: the files on the host -system should not be stripped, even if the files on the target system -are. Mismatched or missing files will lead to confusing results -during debugging. On @sc{gnu}/Linux targets, mismatched or missing -files may also prevent @code{gdbserver} from debugging multi-threaded -programs. +@item +Make sure you have the necessary symbol files +(@pxref{Host and target files}). +Load symbols for your application using the @code{file} command before you +connect. Use @code{set sysroot} to locate target libraries (unless your +@value{GDBN} was compiled with the correct sysroot using +@code{--with-sysroot}). +@item Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). For TCP connections, you must start up @code{gdbserver} prior to using -the @code{target remote} command. Otherwise you may get an error whose +the @code{target} command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like @samp{Connection refused}. Don't use the @code{load} -command in @value{GDBN} when using @code{gdbserver}, since the program is -already on the target. +command in @value{GDBN} when using @code{target remote} mode, since the +program is already on the target. +@end itemize + +@anchor{Monitor Commands for gdbserver} @subsection Monitor Commands for @code{gdbserver} @cindex monitor commands, for @code{gdbserver} -@anchor{Monitor Commands for gdbserver} During a @value{GDBN} session using @code{gdbserver}, you can use the @code{monitor} command to send special requests to @code{gdbserver}.