On 9/7/19 7:33 AM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Date: Sat, 7 Sep 2019 00:28:07 +0100
>>
>> -
>> -* Inferiors and Programs:: Debugging multiple inferiors and programs
>> +* Inferiors Connections and Programs:: Debugging multiple inferiors connections and programs
>
> The new line is too long, please break it in two.
Ah, I didn't realize that would be valid here. Done.
>
>> +@item
>> +the target connection the inferior is bound to. This includes the
>> +unique connection number assigned by @value{GDBN}, and the name of the
>> +protocol used by the connection.
>
> Having this @item start with a lowercase letter, and then having
> another sentence in it looks awkward, English-wise. How about making
> this a single sentence, as in "... is bound to, including the unique
> connection number ..."?
>
Sounds good. Done.
>> +@enumerate
>> +@item
>> +the connection number assigned by @value{GDBN}
>
> This should end in a period, as the other items do.
Fixed.
>
>> +@item
>> +the connection name, derived from the protocol used by the connection.
>
> "Name" sounds ... inaccurate, when it can be something like
> "extended-remote host:10000", doesn't it? How about "Type"? Or maybe
> call that "Description" and the last field "Details"?
Replied to that in another email.
Tentatively going with "What".
>
>> +There's no explicit way to switch focus between connections. Instead,
>> +you switch focus between inferiors, which implicitly switches the
>> +focus to the selected inferior's connection.
>> +
>> To switch focus between inferiors, use the @code{inferior} command:
>
> What does "focus" mean in this context? Either we should explain that
> here, or have a cross-reference where that is already explained.
The manual talks about "focus of debugging" in a few places.
But, I've realized that this sentence doesn't really help much,
considering we have, just before the example:
An asterisk ‘*’ preceding the connection number indicates the connection of the current inferior.
So there's no need to talk about switching between connections.
I've removed that paragraph.
>
>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index f382e887c0..20aad73aa5 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>
> This part is OK.
>
> Thanks.
>
Here's the updated patch.
From a9df9ed7a8fe45df468516710875428df3a9d74a Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Fri, 17 Sep 2019 03:40:38 +0100
Subject: [PATCH] Multi-target: NEWS and user manual
This commit documents the new multi-target features in both NEWS and
user manual.
gdb/ChangeLog:
yyyy-mm-dd Pedro Alves <palves@redhat.com>
* NEWS: Mention multi-target debugging, "info connections", and
"add-inferior -no-connection".
gdb/doc/ChangeLog:
yyyy-mm-dd 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.
---
gdb/doc/gdb.texinfo | 137 +++++++++++++++++++++++++++++++++++++---------------
gdb/doc/guile.texi | 4 +-
gdb/doc/python.texi | 6 +--
gdb/NEWS | 29 +++++++++++
4 files changed, 132 insertions(+), 44 deletions(-)
@@ -2237,8 +2237,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
@@ -2493,27 +2493,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,
@@ -2943,15 +2944,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
@@ -2985,6 +2988,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.
@@ -3000,9 +3008,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:
@@ -3031,13 +3081,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
@@ -3047,15 +3106,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.
@@ -3708,14 +3767,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
@@ -11866,8 +11925,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}.
@@ -12974,7 +13033,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.
@@ -28256,7 +28315,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.
@@ -35156,7 +35215,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
@@ -45394,11 +45453,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}
+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:
@@ -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
@@ -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.
@@ -4158,7 +4158,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
@@ -4167,7 +4167,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
@@ -46,6 +46,21 @@
The 'outer_function::' prefix is only needed if 'inner_function' is
not visible in the current scope.
+* 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
@@ -147,6 +162,9 @@ show print frame-info
'frame', 'stepi'. The python frame filtering also respect this setting.
The 'backtrace' '-frame-info' option can override this global setting.
+info connections
+ Lists the target connections currently in use.
+
* Changed commands
help
@@ -191,6 +209,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