* linux-low.c (linux_attach_lwp): Do not _exit after errors.

	(linux_kill, linux_detach): Clean up the process list.
	* remote-utils.c (remote_open): Improve port number parsing.
	(putpkt_binary, input_interrupt): Only send interrupts if the target
	is running.
	* server.c (extended_protocol): Make static.
	(attached): Define earlier.
	(exit_requested, response_needed, program_argv): New variables.
	(target_running): New.
	(start_inferior): Clear attached here.
	(attach_inferior): Set attached here.
	(require_running): Define.
	(handle_query): Use require_running and target_running.  Implement
	"monitor exit".
	(handle_v_attach, handle_v_run): New.
	(handle_v_requests): Use require_running.  Handle vAttach and vRun.
	(gdbserver_usage): Update.
	(main): Redo argument parsing.  Handle --debug and --multi.  Handle
	--attach along with other options or after the port.  Save
	program_argv.  Support no initial program.  Resynchronize
	communication with GDB after an error.  Handle "monitor exit".
	Use require_running and target_running.  Always allow the extended
	protocol.  Do not error out for Hc0 or Hc-1.  Do not automatically
	restart in extended mode.
	* README: Refer to the GDB manual.  Update --attach usage.

	* remote.c (struct remote_state): Add cached_wait_status.
	(remote_exec_file): New variable.
	(PACKET_vAttach, PACKET_vRun): New constants.
	(extended_remote_restart): Do not query for status.
	(struct start_remote_args): New.
	(remote_start_remote): Take it as a second argument.  Check
	whether the target is running.  Issue an error for non-running
	non-extended targets.  Cache the wait status.  Set inferior_ptid
	here.
	(remote_open_1): Prompt to disconnect non-running targets.  Make
	sure the target is marked running.  Do not set inferior_ptid here.
	Update call to remote_start_remote.  Do not call remote_check_symbols
	if the target is not running.
	(remote_detach_1): Rename from remote_detach.  Take an EXTENDED
	argument.  Handle a non-running target.
	(remote_detach): Use it.
	(extended_remote_detach): New.
	(remote_disconnect): Fix typo.  Use remoute_mourn_1.
	(extended_remote_attach_1, extended_remote_attach)
	(extended_async_remote_attach): New.
	(remote_vcont_resume): Remove unused variable.
	(remote_wait, remote_async_wait): Use any cached wait status.
	(putpkt_binary, getpkt): Clear any cached wait status.
	(extended_remoute_mourn_1): New.
	(extended_remote_mourn): Use it.
	(extended_async_remote_mourn, extended_remote_run): New.
	(extended_remote_create_inferior_1): New.
	(extended_remote_create_inferior): Use it.
	(extended_remote_async_create_inferior): Likewise.
	(remote_xfer_partial): Skip for non-executing targets.
	(init_extended_remote_ops): Set to_detach and to_attach.
	(init_extended_async_remote_ops): Likewise.  Use
	extended_async_remote_mourn.
	(_initialize_remote): Register vAttach, vRun, and
	set remote exec-file.
	* NEWS: Mention vAttach, vRun, and gdbserver extended-remote support.

	* gdb.server/ext-attach.c, gdb.server/ext-attach.exp,
	gdb.server/ext-run.exp: New files.
	* lib/gdbserver-support.exp (gdbserver_download): New.
	(gdbserver_start): New.  Update gdbserver expected
	output.
	(gdbserver_spawn): Use them.
	(gdbserver_start_extended): New.

	* gdb.texinfo (Using the `gdbserver' Program): Add security
	warning.  Rearrange into subsections and subsubsections.  Document
	--multi and --debug.  Correct --with-sysroot typo.  Update --attach
	usage.  Make load reference clearer.  Document monitor exit.
	(Remote Configuration): Document set remote exec-file, attach-packet,
	and run-packet.
	(Packets): Document vAttach and vRun.

2 files changed, 131 insertions, 14 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 5cafe2c..b5d144c 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,13 @@
+2008-01-29  Daniel Jacobowitz  <dan@codesourcery.com>
+
+	* gdb.texinfo (Using the `gdbserver' Program): Add security
+	warning.  Rearrange into subsections and subsubsections.  Document
+	--multi and --debug.  Correct --with-sysroot typo.  Update --attach
+	usage.  Make load reference clearer.  Document monitor exit.
+	(Remote Configuration): Document set remote exec-file, attach-packet,
+	and run-packet.
+	(Packets): Document vAttach and vRun.
+
 2008-01-30  Nick Roberts  <nickrob@snap.net.nz>
 
 	* gdb.texinfo (Processes): Mention process command.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7566294..c613270 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -12952,9 +12952,19 @@ choice for debugging.
 or a TCP connection, using the standard @value{GDBN} remote serial
 protocol.
 
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
+@quotation
+@emph{Warning:} @code{gdbserver} does not have any built-in security.
+Do not run @code{gdbserver} connected to any public network; a
+@value{GDBN} connection to @code{gdbserver} provides access to the
+target system with the same privileges as the user running
+@code{gdbserver}.
+@end quotation
+
+@subsection Running @code{gdbserver}
+@cindex arguments, to @code{gdbserver}
+
+Run @code{gdbserver} on the target system.  You need a copy of the
+program you want to debug, including any libraries it requires.
 @code{gdbserver} does not need your program's symbol table, so you can
 strip the program if necessary to save space.  @value{GDBN} on the host
 system does all the symbol handling.
@@ -12997,11 +13007,13 @@ conflicts with another service, @code{gdbserver} prints an error message
 and exits.}  You must use the same port number with the host @value{GDBN}
 @code{target remote} command.
 
+@subsubsection Attaching to a Running Program
+
 On some targets, @code{gdbserver} can also attach to running programs.
 This is accomplished via the @code{--attach} argument.  The syntax is:
 
 @smallexample
-target> gdbserver @var{comm} --attach @var{pid}
+target> gdbserver --attach @var{comm} @var{pid}
 @end smallexample
 
 @var{pid} is the process ID of a currently running process.  It isn't necessary
@@ -13013,18 +13025,56 @@ You can debug processes by name instead of process ID if your target has the
 @code{pidof} utility:
 
 @smallexample
-target> gdbserver @var{comm} --attach `pidof @var{program}`
+target> gdbserver --attach @var{comm} `pidof @var{program}`
 @end smallexample
 
 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.
 
-@item On the host machine,
-first make sure you have the necessary symbol files.  Load symbols for
+@subsubsection Multi-Process Mode for @code{gdbserver}
+@cindex gdbserver, multiple processes
+@cindex multiple processes with 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 @code{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}).
+
+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 @code{target extended-remote} and start
+the program you want to debug.
+
+@code{gdbserver} does not automatically exit in multi-process mode.
+You can terminate it by using @code{monitor exit}
+(@pxref{Monitor Commands for gdbserver}).
+
+@subsubsection Other Command-Line Arguments for @code{gdbserver}
+
+You can include @option{--debug} on the @code{gdbserver} command line.
+@code{gdbserver} will display extra status information about the debugging
+process.  This option is intended for @code{gdbserver} development and
+for bug reports to the developers.
+
+@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-system-root}).
+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
@@ -13038,19 +13088,17 @@ 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}.  You don't need to use the @code{load}
+@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 table
-
 @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}.
-Here are the available commands; they are only of interest when
-debugging @value{GDBN} or @code{gdbserver}.
+Here are the available commands.
 
 @table @code
 @item monitor help
@@ -13065,6 +13113,13 @@ Disable or enable general debugging messages.
 Disable or enable specific debugging messages associated with the remote
 protocol (@pxref{Remote Protocol}).
 
+@item monitor exit
+Tell gdbserver to exit immediately.  This command should be followed by
+@code{disconnect} to close the debugging session.  @code{gdbserver} will
+detach from any attached processes and kill any processes it created.
+Use @code{monitor exit} to terminate @code{gdbserver} at the end
+of a multi-process mode debug session.
+
 @end table
 
 @node Remote Configuration
@@ -13159,6 +13214,15 @@ responses.
 @itemx set remote hardware-breakpoint-limit @var{limit}
 Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
 watchpoints.  A limit of -1, the default, is treated as unlimited.
+
+@item set remote exec-file @var{filename}
+@itemx show remote exec-file
+@anchor{set remote exec-file}
+@cindex executable file, for remote target
+Select the file used for @code{run} with @code{target
+extended-remote}.  This should be set to a filename valid on the
+target system.  If it is not set, the target will use a default
+filename (e.g.@: the last program run).
 @end table
 
 @cindex remote packets, enabling and disabling
@@ -13205,10 +13269,18 @@ are:
 @tab @code{qSymbol}
 @tab Detecting multiple threads
 
+@item @code{attach}
+@tab @code{vAttach}
+@tab @code{attach}
+
 @item @code{verbose-resume}
 @tab @code{vCont}
 @tab Stepping or resuming multiple threads
 
+@item @code{run}
+@tab @code{vRun}
+@tab @code{run}
+
 @item @code{software-breakpoint}
 @tab @code{Z0}
 @tab @code{break}
@@ -23298,6 +23370,7 @@ Here are the packet descriptions.
 
 @item !
 @cindex @samp{!} packet
+@anchor{extended mode}
 Enable extended mode.  In extended mode, the remote server is made
 persistent.  The @samp{R} packet is used to restart the program being
 debugged.
@@ -23563,7 +23636,7 @@ Don't use this packet; use the @samp{R} packet instead.
 @item R @var{XX}
 @cindex @samp{R} packet
 Restart the program being debugged.  @var{XX}, while needed, is ignored.
-This packet is only available in extended mode.
+This packet is only available in extended mode (@pxref{extended mode}).
 
 The @samp{R} packet has no reply.
 
@@ -23606,6 +23679,22 @@ thread is dead
 Packets starting with @samp{v} are identified by a multi-letter name,
 up to the first @samp{;} or @samp{?} (or the end of the packet).
 
+@item vAttach;@var{pid}
+@cindex @samp{vAttach} packet
+Attach to a new process with the specified process ID.  @var{pid} is a
+hexadecimal integer identifying the process.  If the stub is currently
+controlling a process, it is killed.  The attached process is stopped.
+
+This packet is only available in extended mode (@pxref{extended mode}).
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item @r{Any stop packet}
+for success (@pxref{Stop Reply Packets})
+@end table
+
 @item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
 @cindex @samp{vCont} packet
 Resume the inferior, specifying different actions for each thread.
@@ -23702,6 +23791,24 @@ The stub is permitted to delay or batch the effects of a group of
 regions of flash memory are unpredictable until the @samp{vFlashDone}
 request is completed.
 
+@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
+@cindex @samp{vRun} packet
+Run the program @var{filename}, passing it each @var{argument} on its
+command line.  The file and arguments are hex-encoded strings.  If
+@var{filename} is an empty string, the stub may use a default program
+(e.g.@: the last program run).  The program is created in the stopped
+state.  If the stub is currently controlling a process, it is killed.
+
+This packet is only available in extended mode (@pxref{extended mode}).
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item @r{Any stop packet}
+for success (@pxref{Stop Reply Packets})
+@end table
+
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
 @cindex @samp{X} packet