diff options
| -rw-r--r-- | gdb/NEWS | 29 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 140 | ||||
| -rw-r--r-- | gdb/doc/guile.texi | 4 | ||||
| -rw-r--r-- | gdb/doc/python.texi | 6 |
4 files changed, 135 insertions, 44 deletions
@@ -29,6 +29,21 @@ * The RX port now supports XML target descriptions. +* 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 @@ -130,6 +145,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 @@ -174,6 +192,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 diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 53b7de91e47..37537a1dfe1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -2237,8 +2237,7 @@ 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 +2492,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 +2943,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 @@ -2986,6 +2988,11 @@ the inferior number assigned by @value{GDBN} the target system's inferior identifier @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. + +@item the name of the executable the inferior is running. @end enumerate @@ -3000,11 +3007,57 @@ 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 connection name, derived from 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 @value{GDBN} 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 Name 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 +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: @table @code @@ -3031,13 +3084,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 +3109,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 +3770,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 @@ -11769,8 +11831,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}. @@ -12877,7 +12939,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. @@ -28219,7 +28281,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. @@ -35119,7 +35181,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 @@ -45398,11 +45460,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: diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi index f4c29dc3df8..aa21e79a488 100644 --- 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 diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 832283dede8..2d39d9eb647 100644 --- 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. @@ -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 |