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.

2 files changed, 202 insertions, 77 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index fc81d09..ef3bdaa 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,16 @@
+2015-12-11  Don Breazeal  <donb@codesourcery.com>
+
+	* 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  <palves@redhat.com>
 
 	* gdb.texinfo (Threads): Replace warning with explanation
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index bb68e21..7cc1b35 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}.