From patchwork Fri Nov 6 23:56:28 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Don Breazeal X-Patchwork-Id: 9597 Received: (qmail 34873 invoked by alias); 6 Nov 2015 23:57:50 -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 34814 invoked by uid 89); 6 Nov 2015 23:57:49 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.3 required=5.0 tests=AWL, BAYES_20, 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; Fri, 06 Nov 2015 23:57:46 +0000 Received: from svr-orw-fem-06.mgc.mentorg.com ([147.34.97.120]) by relay1.mentorg.com with esmtp id 1Zuqt6-00019X-1B from Don_Breazeal@mentor.com for gdb-patches@sourceware.org; Fri, 06 Nov 2015 15:57:44 -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; Fri, 6 Nov 2015 15:57:43 -0800 Received: by build4-lucid-cs (Postfix, from userid 1905) id 9A48F41048; Fri, 6 Nov 2015 15:57:43 -0800 (PST) From: Don Breazeal To: Subject: [PATCH 3/3] Target remote mode fork and exec docs Date: Fri, 6 Nov 2015 15:56:28 -0800 Message-ID: <1446854188-496-4-git-send-email-donb@codesourcery.com> In-Reply-To: <1446854188-496-1-git-send-email-donb@codesourcery.com> References: <1446854188-496-1-git-send-email-donb@codesourcery.com> MIME-Version: 1.0 X-IsSubscribed: yes 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. Thanks, --Don gdb/ 2015-11-06 Don Breazeal * NEWS: Announce fork and exec event support for target remote. gdb/doc/ 2015-11-06 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. Use @kbd consistently for target commands instead of @code or @samp. --- gdb/NEWS | 8 ++ gdb/doc/gdb.texinfo | 212 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 137 insertions(+), 83 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..e364efb 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 @kbd{target remote} mode or +@kbd{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 +@kbd{target extended-remote} mode. It has no real effect in +@kbd{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}. @@ -19221,28 +19227,126 @@ configuration of @value{GDBN}; use @code{help target} to list them. @node Connecting @section Connecting to a Remote Target -@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 +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. + +@subsection Connecting in @kbd{target remote} mode + +When you invoke @code{gdbserver} for a @kbd{target remote} mode +session, you must either specify the program to debug or use the +@option{--attach} option (@pxref{Server,,Running gdbserver}). + +Once the 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}. In @kbd{target remote} mode the @kbd{run} command is +not supported. + +@subsection Connecting in @kbd{target extended-remote} mode +@cindex @code{gdbserver}, extended-remote mode +@cindex @code{gdbserver}, exit + +When you connect to @code{gdbserver} using @kbd{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 extended 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 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}). + +@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 extended 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. + +@subsection Host and target files + +@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. + +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 +@kbd{target remote} (or @kbd{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. + +@subsection Steps for connecting to a remote target + +The basic procedure for connecting to the remote target is: + +@itemize @bullet +@item +First, run @value{GDBN} on the host system. + +@item +Next, specify the how @value{GDBN} finds symbol files +(@pxref{Connecting,,Host and target files}). + +@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. + +@end itemize + +@subsection Remote connection commands -@cindex @code{target remote} +@cindex @kbd{target remote} +@cindex @kbd{target extended-remote} @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: +@kbd{target remote} and @kbd{target extended-remote} commands establish +a connection to the target. Their arguments indicate which medium to use: @table @code @item target remote @var{serial-device} -@cindex serial line, @code{target remote} +@item target extended-remote @var{serial-device} +@cindex serial line, @kbd{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}: @@ -19253,11 +19357,13 @@ target remote /dev/ttyb If you're using a serial line, you may want to give @value{GDBN} the @samp{--baud} option, or use the @code{set serial baud} command (@pxref{Remote Configuration, set serial baud}) before the -@code{target} command. +@kbd{target} command. @item target remote @code{@var{host}:@var{port}} @itemx target remote @code{tcp:@var{host}:@var{port}} -@cindex @acronym{TCP} port, @code{target remote} +@item target extended-remote @code{@var{host}:@var{port}} +@itemx target extended-remote @code{tcp:@var{host}:@var{port}} +@cindex @acronym{TCP} port, @kbd{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} address; @var{port} must be a decimal number. The @var{host} could be @@ -19285,7 +19391,8 @@ target remote :1234 Note that the colon is still required here. @item target remote @code{udp:@var{host}:@var{port}} -@cindex @acronym{UDP} port, @code{target remote} +@item target extended-remote @code{udp:@var{host}:@var{port}} +@cindex @acronym{UDP} port, @kbd{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,7 +19406,8 @@ can silently drop packets on busy or unreliable networks, which will cause havoc with your debugging session. @item target remote | @var{command} -@cindex pipe, @code{target remote} to +@item target extended-remote | @var{command} +@cindex pipe, @kbd{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 by the system's command shell, @code{/bin/sh}; it should expect remote @@ -19314,11 +19422,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 @@ -19333,7 +19436,7 @@ 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 +(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. @@ -19433,7 +19536,7 @@ target system with the same privileges as the user running @code{gdbserver}. @end quotation -@subsection Running @code{gdbserver} +@subsection Running gdbserver @cindex arguments, to @code{gdbserver} @cindex @code{gdbserver}, command-line arguments @@ -19526,38 +19629,6 @@ 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. @@ -19640,31 +19711,6 @@ environment: $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog @end smallexample -@subsection Connecting to @code{gdbserver} - -Run @value{GDBN} on the host system. - -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}). - -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. - -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 -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. - @subsection Monitor Commands for @code{gdbserver} @cindex monitor commands, for @code{gdbserver} @anchor{Monitor Commands for gdbserver}