diff mbox

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

Message ID 1447290000-31393-2-git-send-email-donb@codesourcery.com
State New
Headers show

Commit Message

Don Breazeal Nov. 12, 2015, 1 a.m. UTC
Hi Eli,
Thanks for the review.

On 11/7/2015 12:18 AM, Eli Zaretskii wrote:
>> 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.

I went with the latter suggestion.  I hope my interpretation of this
doesn't violate any doc conventions.  In the previous version I had
tried to leave some paragraphs unmodified, just reorganizing where
they were.  I've been more liberal in my changes in this version.

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

I added a number of these.

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

I misunderstood the convention here.  Thanks for clarifying.  I think I
have more-or-less restored things.  Basically, as I understand it, the rule
is: use @kbd where the sentence is saying "type @kbd{foo}" or "use
@kbd{foo}", but use @code if it is just referring to it, like "in the
case of the @code{foo} command".

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

I fixed all of these.

>> -@subsection Running @code{gdbserver}
>> +@subsection Running gdbserver
> 
> Not sure why you removed the markup from "gdbserver" here.

My ignorance about how to implement cross-references.  I've figured out
the right thing to do, and restored the markup.

Let me know what you think about this version.
thanks
--Don
-----------------------
This patch implements documentation updates for target remote mode
fork and exec events.  A summary of the rationale for the changes
made here:

* Types of Remote Connections -- explain that the two protocols exist,
and describe the differences between the two.

* 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".

* 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-11  Don Breazeal  <donb@sourceware.org>

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

gdb/doc/
2015-11-11  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.
	(Server): Note effects of target extended-remote mode.
	Delete section on Multi-Process Mode for gdbserver.
	Move some text to "Connecting" node.

---
 gdb/NEWS            |   8 ++
 gdb/doc/gdb.texinfo | 272 +++++++++++++++++++++++++++++++++++++---------------
 2 files changed, 202 insertions(+), 78 deletions(-)

Comments

Eli Zaretskii Nov. 12, 2015, 4:48 p.m. UTC | #1
> From: Don Breazeal <donb@codesourcery.com>
> Date: Wed, 11 Nov 2015 17:00:00 -0800
> 
> >> +@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.
> 
> I misunderstood the convention here.  Thanks for clarifying.  I think I
> have more-or-less restored things.  Basically, as I understand it, the rule
> is: use @kbd where the sentence is saying "type @kbd{foo}" or "use
> @kbd{foo}", but use @code if it is just referring to it, like "in the
> case of the @code{foo} command".

Yes, that's it.

> +@table @asis
> +
> +@cindex remote debugging, detach and program exit
> +@item Result of detach or program exit
> +
> +@strong{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{target extended-remote mode:} When the debugged program exits or

This is OK, but the fact that "target extended-remote mode:" part that
begins a sentence doesn't start with a capital letter looks wrong.
How about starting with @strong{With target extended-remote mode:}
instead?

> +@item The @code{run} command
> +@strong{target remote mode:} The @code{run} command is not supported.

Please be consistent regarding whether or not you leave an empty line
after the @item line.  (My suggestion is not to leave such a line in a
@table.)

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

Here you show 2 commands in the same sentence, one with @code, the
other with @kbd.  I think both should use @code.

> +In @code{target extended-remote} mode, you can also attach using the
> +@value{GDBN} attach command
> +(@pxref{Types of Remote Connections: Attaching}).

I don't understand this @pxref -- there's no such node or anchor in
the text.  Does this work for you?  (Also, using a colon in
cross-reference or node names is a bad idea, as that confuses Info
readers.)

The patch is approved, assuming the above minor issues are fixed.

Thanks.
Don Breazeal Nov. 13, 2015, 1:12 a.m. UTC | #2
On 11/12/2015 8:48 AM, Eli Zaretskii wrote:
>> From: Don Breazeal <donb@codesourcery.com>
>> Date: Wed, 11 Nov 2015 17:00:00 -0800
>>

> 
>> +@table @asis
>> +
>> +@cindex remote debugging, detach and program exit
>> +@item Result of detach or program exit
>> +
>> +@strong{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{target extended-remote mode:} When the debugged program exits or
> 
> This is OK, but the fact that "target extended-remote mode:" part that
> begins a sentence doesn't start with a capital letter looks wrong.
> How about starting with @strong{With target extended-remote mode:}
> instead?
>> +@item The @code{run} command
>> +@strong{target remote mode:} The @code{run} command is not supported.
> 
> Please be consistent regarding whether or not you leave an empty line
> after the @item line.  (My suggestion is not to leave such a line in a
> @table.)

Items above are now done in my sandbox.

> 
>>  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.
> 
> Here you show 2 commands in the same sentence, one with @code, the
> other with @kbd.  I think both should use @code.
> 
>> +In @code{target extended-remote} mode, you can also attach using the
>> +@value{GDBN} attach command
>> +(@pxref{Types of Remote Connections: Attaching}).
> 
> I don't understand this @pxref -- there's no such node or anchor in
> the text.  Does this work for you?  (Also, using a colon in
> cross-reference or node names is a bad idea, as that confuses Info
> readers.)

These last two I had fixed in my sandbox but apparently the fixes didn't
make it into the patch I posted, sorry about that. :-S

Regarding the @pxrefs that had colons in them, I have a question.  I was
making a cross-reference into the middle of a section, so
there is no section heading to use as the name of the reference.  I was
trying to refer to "The part about Attaching that is in the section
'Types of Remote Connections'".  How about:

@anchor{Attaching in Types of Remote Connections}

> 
> The patch is approved, assuming the above minor issues are fixed.
> 
> Thanks.
> 
Thanks again for the review and the suggestions.
--Don
Eli Zaretskii Nov. 13, 2015, 8:15 a.m. UTC | #3
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> From: Don Breazeal <donb@codesourcery.com>
> Date: Thu, 12 Nov 2015 17:12:55 -0800
> 
> >> +In @code{target extended-remote} mode, you can also attach using the
> >> +@value{GDBN} attach command
> >> +(@pxref{Types of Remote Connections: Attaching}).
> > 
> > I don't understand this @pxref -- there's no such node or anchor in
> > the text.  Does this work for you?  (Also, using a colon in
> > cross-reference or node names is a bad idea, as that confuses Info
> > readers.)
> 
> These last two I had fixed in my sandbox but apparently the fixes didn't
> make it into the patch I posted, sorry about that. :-S
> 
> Regarding the @pxrefs that had colons in them, I have a question.  I was
> making a cross-reference into the middle of a section, so
> there is no section heading to use as the name of the reference.  I was
> trying to refer to "The part about Attaching that is in the section
> 'Types of Remote Connections'".  How about:
> 
> @anchor{Attaching in Types of Remote Connections}

That's one possibility, yes.  Another is to use @pxref with 2
arguments (see the Texinfo manual for the details), with the 2nd
argument being some phrase that begins the part of the text to which
you want to jump.  Unfortunately, the second alternative is only
supported by some Info readers, not all of them.

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..4adbfed 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 @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.
@@ -3282,6 +3283,11 @@  Program exited normally.
 @end table
 @end table
 
+@code{follow-exec-mode} is supported in native mode and
+@code{target extended-remote} mode.  It has no real effect in
+@code{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}.
@@ -19220,28 +19226,150 @@  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:
+
+@table @asis
+
+@cindex remote debugging, detach and program exit
+@item Result of detach or program exit
+
+@strong{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{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{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{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{Types of Remote Connnections: --multi option}
+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.
 
-@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
+@item The @code{run} command
+@strong{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{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{Types of Remote Connections: Attaching}
+@item Attaching
+@strong{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{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}:
@@ -19253,10 +19381,12 @@  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}}
+@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}
@@ -19285,6 +19415,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}:
@@ -19299,6 +19430,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
@@ -19314,11 +19446,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
@@ -19332,10 +19459,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)
@@ -19344,11 +19474,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
@@ -19405,7 +19537,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
@@ -19433,6 +19566,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
@@ -19500,6 +19634,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
@@ -19511,8 +19646,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{Types of Remote Connections: Attaching}).
 
 @pindex pidof
 You can debug processes by name instead of process ID if your target has the
@@ -19526,41 +19665,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
@@ -19591,6 +19699,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{Types of Remote Connnections: --multi option}.
+
 @cindex @option{--debug}, @code{gdbserver} option
 The @option{--debug} option tells @code{gdbserver} to display extra
 status information about the debugging process.
@@ -19642,32 +19756,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}.