From patchwork Mon Dec 7 22:14:07 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Don Breazeal X-Patchwork-Id: 9930 Received: (qmail 92066 invoked by alias); 7 Dec 2015 22:15:01 -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 92054 invoked by uid 89); 7 Dec 2015 22:15:01 -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; Mon, 07 Dec 2015 22:14:58 +0000 Received: from svr-orw-fem-06.mgc.mentorg.com ([147.34.97.120]) by relay1.mentorg.com with esmtp id 1a643b-000121-12 from Don_Breazeal@mentor.com for gdb-patches@sourceware.org; Mon, 07 Dec 2015 14:14:55 -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; Mon, 7 Dec 2015 14:14:54 -0800 Received: by build4-lucid-cs (Postfix, from userid 1905) id 91B38410AC; Mon, 7 Dec 2015 14:14:54 -0800 (PST) From: Don Breazeal To: Subject: [PATCH v2 3/3] Target remote mode fork and exec docs Date: Mon, 7 Dec 2015 14:14:07 -0800 Message-ID: <1449526447-10039-4-git-send-email-donb@codesourcery.com> In-Reply-To: <1449526447-10039-1-git-send-email-donb@codesourcery.com> References: <564F1A6A.3030301@redhat.com> <1449526447-10039-1-git-send-email-donb@codesourcery.com> MIME-Version: 1.0 X-IsSubscribed: yes This is version two of a patch that updates the documentation for fork and exec event support in target remote mode. Most of the changes in this version are those requested by Eli in a previous review (https://sourceware.org/ml/gdb-patches/2015-11/msg00278.html). Those issues included: start table item text with capital letter, be consistent with empty lines after @item lines, be consistent in use of @code and @kbd, and fix a couple of @pxref problems. All of those are dealt with in this version. In addition, I made a minor change to the text in both the NEWS and gdb.texinfo files, modifying "follow-exec-mode is not supported in target remote mode" to say instead that follow-exec-mode is of limited usefulness in that mode since the 'run' command is not supported there. 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: * Connecting to a remote target -- explain that the two protocols exist. * Connecting in target remote mode -- explain invoking gdbserver for target remote mode, and move remote-specific text from original "Connecting to a remote target" section. * Connecting in target extended-remote mode -- promote this section from "Using the gdbserver Program | Running gdbserver | Multi-Process Mode for gdbserver". Put it next to the target remote mode section. * 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". * Steps for connecting to a remote target -- used to be "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. gdb/ 2015-12-07 Don Breazeal * NEWS: Announce fork and exec event support for target remote. gdb/doc/ 2015-12-07 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 | 9 ++ gdb/doc/gdb.texinfo | 268 +++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 200 insertions(+), 77 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index a222dfb..bec9810 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -127,6 +127,15 @@ show remote exec-event-feature-packet The reply to qXfer:threads:read may now include a name attribute for each thread. +* 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, follow-exec-mode, and + fork and exec catchpoints. Note that follow-exec-mode is of limited + usefulness, 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 b82f3c6..5b60231 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 is of limited usefulness 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}. @@ -19234,28 +19240,148 @@ 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 -@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 +@cindex remote debugging, detach and program exit +@item Result of detach or program exit +@strong{With 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{With 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{With 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{With 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{--multi Option in Types of Remote Connnections} +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. + +@item The @code{run} command +@strong{With 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{With 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{Attaching in Types of Remote Connections} +@item Attaching +@strong{With 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{With 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. -@cindex @code{target remote} +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. + +@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}: @@ -19271,6 +19397,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} @@ -19299,6 +19427,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}: @@ -19313,6 +19442,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 @@ -19328,11 +19458,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 @@ -19346,10 +19471,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) @@ -19358,11 +19486,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 @@ -19419,7 +19549,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 @@ -19447,6 +19578,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 @@ -19514,6 +19646,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 @@ -19525,8 +19658,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{Attaching in Types of Remote Connections}). @pindex pidof You can debug processes by name instead of process ID if your target has the @@ -19540,41 +19677,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 @@ -19605,6 +19711,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{--multi Option in Types of Remote Connnections}. + @cindex @option{--debug}, @code{gdbserver} option The @option{--debug} option tells @code{gdbserver} to display extra status information about the debugging process. @@ -19656,32 +19768,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}.