Multi-target: NEWS and user manual

This commit documents the new multi-target features in both NEWS and user manual. gdb/ChangeLog: 2020-01-10 Pedro Alves <palves@redhat.com> * NEWS: Mention multi-target debugging, "info connections", and "add-inferior -no-connection". gdb/doc/ChangeLog: 2020-01-10 Pedro Alves <palves@redhat.com> * gdb.texinfo (Starting): Say "current inferior not connected" instead of "GDB not connected". (Inferiors and Programs): Rename node to ... (Inferiors Connections and Programs): ... this. Update all references. Talk about multiple target connections. Update "info inferiors" info to mention the connections column. Describe "info connections". Document "add-inferior -no-connection". * guile.texi, python.texi: Update cross references.
2020-01-10 20:06:15 +00:00 · 2020-01-10 20:06:15 +00:00 · 65c574f6dd
parent 2f4fcf0039
commit 65c574f6dd
6 changed files with 148 additions and 44 deletions
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@ -1,3 +1,8 @@
+2020-01-10  Pedro Alves  <palves@redhat.com>
+
+	* NEWS: Mention multi-target debugging, "info connections", and
+	"add-inferior -no-connection".
+
 2020-01-10  Pedro Alves  <palves@redhat.com>

 	* infrun.c: Include "target-connection.h".
--- a/gdb/NEWS
+++ b/gdb/NEWS
@ -77,6 +77,21 @@
  This feature is still in testing, so it is disabled by default.  You
  can turn it on using 'maint set worker-threads unlimited'.

+* Multi-target debugging support
+
+  GDB now supports debugging multiple target connections
+  simultaneously.  For example, you can now have each inferior
+  connected to different remote servers running in different machines,
+  or have one inferior debugging a local native process, an inferior
+  debugging a core dump, etc.
+
+  This support is experimental and comes with some limitations -- you
+  can only resume multiple targets simultaneously if all targets
+  support non-stop mode, and all remote stubs or servers must support
+  the same set of remote protocol features exactly.  See also "info
+  connections" and "add-inferior -no-connection" below, and "maint set
+  target-non-stop" in the user manual.
+
 * Python API

  ** The gdb.Value type has a new method 'format_string' which returns a
@ -243,6 +258,9 @@ show debug remote-packet-max-chars
  "set debug remote".
  The default is 512 bytes.

+info connections
+  Lists the target connections currently in use.
+
 * Changed commands

 help
@ -287,6 +305,17 @@ show print raw-frame-arguments
  old commands are now deprecated and may be removed in a future
  release.

+add-inferior [-no-connection]
+  The add-inferior command now supports a "-no-connection" flag that
+  makes the new inferior start with no target connection associated.
+  By default, the new inferior inherits the target connection of the
+  current inferior.  See also "info connections".
+
+info inferior
+  This command's output now includes a new "Connection" column
+  indicating which target connection an inferior is bound to.  See
+  "info connections" above.
+
 maint test-options require-delimiter
 maint test-options unknown-is-error
 maint test-options unknown-is-operand
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@ -1,3 +1,14 @@
+2020-01-10  Pedro Alves  <palves@redhat.com>
+
+	* gdb.texinfo (Starting): Say "current inferior not connected"
+	instead of "GDB not connected".
+	(Inferiors and Programs): Rename node to ...
+	(Inferiors Connections and Programs): ... this.  Update all
+	references.  Talk about multiple target connections.  Update "info
+	inferiors" info to mention the connections column.  Describe "info
+	connections".  Document "add-inferior -no-connection".
+	* guile.texi, python.texi: Update cross references.
+
 2020-01-01  Joel Brobecker  <brobecker@adacore.com>

 	* gdb.texinfo, refcard.tex: Update copyright year range.
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@ -2250,8 +2250,8 @@ kill a child process.
 * Input/Output::                Your program's input and output
 * Attach::                      Debugging an already-running process
 * Kill Process::                Killing the child process
-
-* Inferiors and Programs::      Debugging multiple inferiors and programs
+* Inferiors Connections and Programs:: Debugging multiple inferiors
+					 connections and programs
 * Threads::                     Debugging programs with multiple threads
 * Forks::                       Debugging forks
 * Checkpoint/Restart::          Setting a @emph{bookmark} to return to later
@ -2506,27 +2506,28 @@ $@file{.zshenv} for the Z shell, or the file specified in the
@itemx set auto-connect-native-target off
@itemx show auto-connect-native-target

-By default, if not connected to any target yet (e.g., with
-@code{target remote}), the @code{run} command starts your program as a
-native process under @value{GDBN}, on your local machine.  If you're
-sure you don't want to debug programs on your local machine, you can
-tell @value{GDBN} to not connect to the native target automatically
-with the @code{set auto-connect-native-target off} command.
+By default, if the current inferior is not connected to any target yet
+(e.g., with @code{target remote}), the @code{run} command starts your
+program as a native process under @value{GDBN}, on your local machine.
+If you're sure you don't want to debug programs on your local machine,
+you can tell @value{GDBN} to not connect to the native target
+automatically with the @code{set auto-connect-native-target off}
+command.

-If @code{on}, which is the default, and if @value{GDBN} is not
+If @code{on}, which is the default, and if the current inferior is not
 connected to a target already, the @code{run} command automaticaly
 connects to the native target, if one is available.

-If @code{off}, and if @value{GDBN} is not connected to a target
-already, the @code{run} command fails with an error:
+If @code{off}, and if the current inferior is not connected to a
+target already, the @code{run} command fails with an error:

@smallexample
 (@value{GDBP}) run
 Don't know how to run.  Try "help target".
@end smallexample

-If @value{GDBN} is already connected to a target, @value{GDBN} always
-uses it with the @code{run} command.
+If the current inferior is already connected to a target, @value{GDBN}
+always uses it with the @code{run} command.

 In any case, you can explicitly connect to the native target with the
@code{target native} command.  For example,
@ -2956,15 +2957,17 @@ next type @code{run}, @value{GDBN} notices that the file has changed, and
 reads the symbol table again (while trying to preserve your current
 breakpoint settings).

-@node Inferiors and Programs
-@section Debugging Multiple Inferiors and Programs
+@node Inferiors Connections and Programs
+@section Debugging Multiple Inferiors Connections and Programs

@value{GDBN} lets you run and debug multiple programs in a single
 session.  In addition, @value{GDBN} on some systems may let you run
 several programs simultaneously (otherwise you have to exit from one
-before starting another).  In the most general case, you can have
-multiple threads of execution in each of multiple processes, launched
-from multiple executables.
+before starting another).  On some systems @value{GDBN} may even let
+you debug several programs simultaneously on different remote systems.
+In the most general case, you can have multiple threads of execution
+in each of multiple processes, launched from multiple executables,
+running on different machines.

@cindex inferior
@value{GDBN} represents the state of each program execution with an
@ -2998,6 +3001,11 @@ the inferior number assigned by @value{GDBN}
@item
 the target system's inferior identifier

+@item
+the target connection the inferior is bound to, including the unique
+connection number assigned by @value{GDBN}, and the protocol used by
+the connection.
+
@item
 the name of the executable the inferior is running.

@ -3013,9 +3021,51 @@ For example,

@smallexample
 (@value{GDBP}) info inferiors
-  Num  Description       Executable
-  2    process 2307      hello
-* 1    process 3401      goodbye
+  Num  Description       Connection                      Executable
+* 1    process 3401      1 (native)                      goodbye
+  2    process 2307      2 (extended-remote host:10000)  hello
+@end smallexample
+
+To find out what open target connections exist at any moment, use
+@w{@code{info connections}}:
+
+@table @code
+@kindex info connections [ @var{id}@dots{} ]
+@item info connections
+Print a list of all open target connections currently being managed by
+@value{GDBN}.  By default all connections are printed, but the
+argument @var{id}@dots{} -- a space separated list of connections
+numbers -- can be used to limit the display to just the requested
+connections.
+
+@value{GDBN} displays for each connection (in this order):
+
+@enumerate
+@item
+the connection number assigned by @value{GDBN}.
+
+@item
+the protocol used by the connection.
+
+@item
+a textual description of the protocol used by the connection.
+
+@end enumerate
+
+@noindent
+An asterisk @samp{*} preceding the connection number indicates the
+connection of the current inferior.
+
+For example,
+@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info connections
+  Num  What                        Description
+* 1    extended-remote host:10000  Extended remote serial target in gdb-specific protocol
+  2    native                      Native process
+  3    core                        Local core dump file
@end smallexample

 To switch focus between inferiors, use the @code{inferior} command:
@ -3044,13 +3094,22 @@ remove inferiors from the debugging session use the

@table @code
@kindex add-inferior
-@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
+@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ]
 Adds @var{n} inferiors to be run using @var{executable} as the
 executable; @var{n} defaults to 1.  If no executable is specified,
 the inferiors begins empty, with no program.  You can still assign or
 change the program assigned to the inferior at any time by using the
@code{file} command with the executable name as its argument.

+By default, the new inferior begins connected to the same target
+connection as the current inferior.  For example, if the current
+inferior was connected to @code{gdbserver} with @code{target remote},
+then the new inferior will be connected to the same @code{gdbserver}
+instance.  The @samp{-no-connection} option starts the new inferior
+with no connection yet.  You can then for example use the @code{target
+remote} command to connect to some other @code{gdbserver} instance,
+use @code{run} to spawn a local program, etc.
+
@kindex clone-inferior
@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
 Adds @var{n} inferiors ready to execute the same program as inferior
@ -3060,15 +3119,15 @@ want to run another instance of the inferior you are debugging.

@smallexample
 (@value{GDBP}) info inferiors
-  Num  Description       Executable
-* 1    process 29964     helloworld
+  Num  Description       Connection   Executable
+* 1    process 29964     1 (native)   helloworld
 (@value{GDBP}) clone-inferior
 Added inferior 2.
 1 inferiors added.
 (@value{GDBP}) info inferiors
-  Num  Description       Executable
-  2    <null>            helloworld
-* 1    process 29964     helloworld
+  Num  Description       Connection   Executable
+* 1    process 29964     1 (native)   helloworld
+  2    <null>            1 (native)   helloworld
@end smallexample

 You can now simply switch focus to inferior 2 and run it.
@ -3721,14 +3780,14 @@ If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
 will retain control of all forked processes (including nested forks).
 You can list the forked processes under the control of @value{GDBN} by
 using the @w{@code{info inferiors}} command, and switch from one fork
-to another by using the @code{inferior} command (@pxref{Inferiors and
-Programs, ,Debugging Multiple Inferiors and Programs}).
+to another by using the @code{inferior} command (@pxref{Inferiors Connections and
+Programs, ,Debugging Multiple Inferiors Connections and Programs}).

 To quit debugging one of the forked processes, you can either detach
 from it by using the @w{@code{detach inferiors}} command (allowing it
 to run independently), or kill it using the @w{@code{kill inferiors}}
-command.  @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
-and Programs}.
+command.  @xref{Inferiors Connections and Programs, ,Debugging
+Multiple Inferiors Connections and Programs}.

 If you ask to debug a child process and a @code{vfork} is followed by an
@code{exec}, @value{GDBN} executes the new target up to the first
@ -11911,8 +11970,8 @@ gdbserver that supports the @code{qGetTIBAddr} request.
 This variable contains the address of the thread information block.

@item $_inferior
-The number of the current inferior.  @xref{Inferiors and
-Programs, ,Debugging Multiple Inferiors and Programs}.
+The number of the current inferior.  @xref{Inferiors Connections and
+Programs, ,Debugging Multiple Inferiors Connections and Programs}.

@item $_thread
 The thread number of the current thread.  @xref{thread numbers}.
@ -13108,7 +13167,7 @@ character.

@value{GDBN} caches data exchanged between the debugger and a target.
 Each cache is associated with the address space of the inferior.
-@xref{Inferiors and Programs}, about inferior and address space.
+@xref{Inferiors Connections and Programs}, about inferior and address space.
 Such caching generally improves performance in remote debugging
 (@pxref{Remote Debugging}), because it reduces the overhead of the
 remote protocol by bundling memory reads and writes into large chunks.
@ -28524,7 +28583,7 @@ groups can be obtained using @samp{-list-thread-groups --available}.
 In general, the content of a thread group may be only retrieved only
 after attaching to that thread group.

-Thread groups are related to inferiors (@pxref{Inferiors and
+Thread groups are related to inferiors (@pxref{Inferiors Connections and
 Programs}).  Each inferior corresponds to a thread group of a special
 type @samp{process}, and some additional operations are permitted on
 such thread groups.
@ -35903,7 +35962,7 @@ popup menu, but is needless clutter on the command line, and
 -add-inferior
@end smallexample

-Creates a new inferior (@pxref{Inferiors and Programs}).  The created
+Creates a new inferior (@pxref{Inferiors Connections and Programs}).  The created
 inferior is not associated with any executable.  Such association may
 be established with the @samp{-file-exec-and-symbols} command
 (@pxref{GDB/MI File Commands}).  The command response has a single
@ -46189,11 +46248,11 @@ command, otherwise you may get an error that looks something like
@command{gdbserver} can also debug multiple inferiors at once,
 described in
@ifset man
-the @value{GDBN} manual in node @code{Inferiors and Programs}
-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+the @value{GDBN} manual in node @code{Inferiors Connections and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors Connections and Programs'}.
@end ifset
@ifclear man
-@ref{Inferiors and Programs}.
+@ref{Inferiors Connections and Programs}.
@end ifclear
 In such case use the @code{extended-remote} @value{GDBN} command variant:

--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@ -2155,7 +2155,7 @@ A program space, or @dfn{progspace}, represents a symbolic view
 of an address space.
 It consists of all of the objfiles of the program.
@xref{Objfiles In Guile}.
-@xref{Inferiors and Programs, program spaces}, for more details
+@xref{Inferiors Connections and Programs, program spaces}, for more details
 about program spaces.

 Each progspace is represented by an instance of the @code{<gdb:progspace>}
@ -2178,7 +2178,7 @@ if the program it refers to is not loaded in @value{GDBN} any longer.
@deffn {Scheme Procedure} current-progspace
 This function returns the program space of the currently selected inferior.
 There is always a current progspace, this never returns @code{#f}.
-@xref{Inferiors and Programs}.
+@xref{Inferiors Connections and Programs}.
@end deffn

@deffn {Scheme Procedure} progspaces
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@ -2928,7 +2928,7 @@ itself.

@findex gdb.Inferior
 Programs which are being run under @value{GDBN} are called inferiors
-(@pxref{Inferiors and Programs}).  Python scripts can access
+(@pxref{Inferiors Connections and Programs}).  Python scripts can access
 information about and manipulate inferiors controlled by @value{GDBN}
 via objects of the @code{gdb.Inferior} class.

@ -4161,7 +4161,7 @@ A program space, or @dfn{progspace}, represents a symbolic view
 of an address space.
 It consists of all of the objfiles of the program.
@xref{Objfiles In Python}.
-@xref{Inferiors and Programs, program spaces}, for more details
+@xref{Inferiors Connections and Programs, program spaces}, for more details
 about program spaces.

 The following progspace-related functions are available in the
@ -4170,7 +4170,7 @@ The following progspace-related functions are available in the
@findex gdb.current_progspace
@defun gdb.current_progspace ()
 This function returns the program space of the currently selected inferior.
-@xref{Inferiors and Programs}.  This is identical to
+@xref{Inferiors Connections and Programs}.  This is identical to
@code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
 included for historical compatibility.
@end defun