diff mbox

[pushed] Re: [PATCH v2 3/3] Target remote mode fork and exec docs

Message ID 566F18B1.2040802@codesourcery.com
State New
Headers show

Commit Message

Don Breazeal Dec. 14, 2015, 7:29 p.m. UTC 
On 12/8/2015 5:07 AM, Pedro Alves wrote:
> On 12/07/2015 10:14 PM, Don Breazeal wrote:
> 
>> 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.
> 
> ...
> 
>>  
>> +@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.
> 
> Thinking about this some more, I'm really not sure we should be calling out
> this limited usefulness here (and NEWS).  It seems just as useful in
> remote mode -- it's just that when you want to restart the debugging from
> the starting binary, you do "target remote" again instead of "run" then.

This comment has been removed everywhere.

> 
> Thanks,
> Pedro Alves
> 

This is now pushed.
Thanks
--Don

From: Don Breazeal <donb@codesourcery.com>
Subject: [pushed][PATCH v3 3/3] Target remote mode fork and exec docs

This is the version of the patch that was pushed.  The only differences
between this version and v2 are that any comments about the usefulness
of follow-exec-mode in target remote mode have been removed.

Here is the commit message:

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(-)

 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}.
diff mbox

Patch

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 9ded377..5eece01 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,5 +1,9 @@ 
 2015-12-11  Don Breazeal  <donb@codesourcery.com>

+	* NEWS: Announce fork and exec event support for target remote.
+
+2015-12-11  Don Breazeal  <donb@codesourcery.com>
+
 	* inferior.c (number_of_live_inferiors): New function.
 	(have_live_inferiors): Use number_of_live_inferiors in place
 	of duplicate code.
diff --git a/gdb/NEWS b/gdb/NEWS
index 9ca7f49..484d98d 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 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