diff mbox

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

Message ID 1446854188-496-4-git-send-email-donb@codesourcery.com
State New, archived
Headers

Commit Message

Don Breazeal Nov. 6, 2015, 11:56 p.m. UTC 
  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(-)

Comments

Eli Zaretskii Nov. 7, 2015, 8:18 a.m. UTC | #1 
> From: Don Breazeal <donb@codesourcery.com>
> Date: Fri, 6 Nov 2015 15:56:28 -0800
> 
> 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

This part is OK.

> -@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
                                                                       ^^^
@value{GDBN}

> +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.

Saying "several major differences" and then neither describing them
nor providing a reference (not even just "described below") will leave
the reader confused, I think.  How about a short summary of the
differences, e.g. as an itemized list, here?

Also, does the sentence that follow (the last one in the above
excerpt) need to be here?  It reads strange, especially since it
doesn't seem like it belongs to the aforementioned differences.  Maybe
you could reword it so it did contrast the two modes.

Alternatively, perhaps the following subsections are better rearranged
as extended descriptions of each of the differences, e.g. using @table.
Right now, they read somewhat confusingly, because the description
jumps between the two modes without providing any intermediate summary
for the reader, and thus it is easy to become confused as to what mode
and what difference you are describing.  Some better organization of
the same material could help the reader organize their thoughts and
come out with a better understanding of the differences.

Last, but not least: please consider adding @cindex entries to each of
the subsections, with text that describes the main subject of each
subsection.  In many cases, just the down-cased name of the section is
a good starting point.  This will help the readers find the subsection
quickly using the Info index-searching commands, which is important
for using the manual as a reference.

> +@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.

There's some inconsistency in your usage of @code and @kbd markup for
commands.  In general, the correct markup is @kbd when the context is
about commands typed by the user, and @code otherwise.  (The GDB
manual almost never uses @kbd, for historical reasons, btw.)  You have
changed some of the @code to @kbd regardless of context, or so it
seems.  But in the above passage, you use @code as well, so I'm unsure
what is your rule for selecting one or the other.

>  @item target remote @var{serial-device}
> -@cindex serial line, @code{target remote}
> +@item target extended-remote @var{serial-device}
   ^^^^^
Should be @itemx.

>  @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}}

Likewise.

>  @item target remote | @var{command}
> -@cindex pipe, @code{target remote} to
> +@item target extended-remote | @var{command}

Likewise.

> -@subsection Running @code{gdbserver}
> +@subsection Running gdbserver

Not sure why you removed the markup from "gdbserver" here.

Thanks.
diff mbox

Patch

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}