This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[PATCH 3/3] Target remote mode fork and exec docs


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  <donb@sourceware.org>

	* NEWS: Announce fork and exec event support for target remote.

gdb/doc/
2015-11-06  Don Breazeal  <donb@sourceware.org>

	* 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}
-- 
1.8.1.1


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]