From 19d9d4efd18bcc633e99cb6a3e39bd9b22ca70ce Mon Sep 17 00:00:00 2001 From: Don Breazeal Date: Mon, 14 Dec 2015 11:18:06 -0800 Subject: [PATCH] Target remote mode fork and exec event documentation 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/ChangeLog: * NEWS: Announce fork and exec event support for target remote. gdb/doc/ChangeLog: * 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/ChangeLog | 4 + gdb/NEWS | 7 ++ gdb/doc/ChangeLog | 13 +++ gdb/doc/gdb.texinfo | 266 +++++++++++++++++++++++++++++++------------- 4 files changed, 213 insertions(+), 77 deletions(-) diff --git a/gdb/ChangeLog b/gdb/ChangeLog index 9ded377f720..5eece01721f 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,3 +1,7 @@ +2015-12-11 Don Breazeal + + * NEWS: Announce fork and exec event support for target remote. + 2015-12-11 Don Breazeal * inferior.c (number_of_live_inferiors): New function. diff --git a/gdb/NEWS b/gdb/NEWS index 9ca7f4985f5..484d98d2414 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -135,6 +135,13 @@ 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. + * MI changes ** The -var-set-format command now accepts the zero-hexadecimal diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index fc81d096525..ef3bdaae2be 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,16 @@ +2015-12-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. + 2015-12-10 Pedro Alves * gdb.texinfo (Threads): Replace warning with explanation diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index bb68e21baf9..7cc1b357022 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -3119,10 +3119,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. On @sc{gnu}/Linux platforms, this feature is supported -with kernel version 2.5.60 and later. +with 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. @@ -3268,6 +3269,9 @@ Program exited normally. @end table @end table +@code{follow-exec-mode} is supported in native mode and +@code{target extended-remote} 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}. @@ -19248,28 +19252,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: -@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 +@table @asis + +@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. + +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}: @@ -19285,6 +19409,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} @@ -19313,6 +19439,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}: @@ -19327,6 +19454,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 @@ -19342,11 +19470,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 @@ -19360,10 +19483,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) @@ -19372,11 +19498,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 @@ -19433,7 +19561,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 @@ -19461,6 +19590,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 @@ -19528,6 +19658,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 @@ -19539,8 +19670,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 @@ -19554,41 +19689,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 @@ -19619,6 +19723,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. @@ -19670,32 +19780,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}. -- 2.30.2