This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [RFC] MI non-stop and multiprocess docs.


On Wednesday 12 November 2008 22:09:14 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Wed, 12 Nov 2008 20:20:33 +0300
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > Finally, this chapter seems to be not on design of MI, but more about
> > > advice to frontend implementors.  So I think it should be renamed
> > > accordingly, and some introductory text added to its beginning saying
> > > this is the intent of the chapter.
> > 
> > I don't quite agree. These section describes the main building blocks and 
> > concepts of GDB/MI, and is necessary to understand anything in GDB/MI
> > docs.
> 
> Right, but IMO that isn't "MI design", either.

Ok, what title would you suggest?

> > > It is best not to leave spaces around "---", the results look better
> > > in print.
> > 
> > Do you think you can summarize such style requirements for GDB manual somewhere?
> 
> The canonical place for such style conventions is the Texinfo manual.
> It has this advice (in the "Conventions" node):
> 
>    * Use three hyphens in a row, `---', to produce a long dash--like
>      this (called an "em dash"), used for punctuation in sentences.
> 
> Although it doesn't explicitly say to avoid spaces, it does avoid them
> itself.  I will ask the Texinfo maintainer to be more explicit about
> this.

Thanks.

> > I think they are very similar from frontend point of view -- in that frontend
> > does only minimal processing of those notification, and won't break if they
> > are not emitted.
> 
> That's okay, but it looks to me that after listing 3 items, it is best
> to have 3 @items, not 2.

I'm confused. There are 3 @items in that @itemize block. What change do you
want to me do?

> > > Whenever you first introduce a term, give it the @dfn markup, which
> > > will make stand out in the text.  In this case, since this term is
> > > explained elsewhere in the manual, it is also a good idea to add a
> > > @pxref to that other node.
> > 
> > Actually, we don't have a section for CLI async mode, we have a section
> > for CLI non-stop mode.
> 
> Sorry, I don't follow.  I meant the node "Background Execution".

Ah, I've grepped for "Asynchronous" and found none. I've added pxref to this.

> > > > +that even commands that operate on global state (like global
> > > > +variables, or breakpoints), still access the target in the context of
> > > > +a specific thread
> > > 
> > > What do you mean by "global variables" here?  As written, the text
> > > seems to say that global variables and breakpoints are commands, or
> > > maybe global state, which doesn't sound right to me.  "Breakpoints"
> > > could be replaced with "breakpoint commands", but I don't know what
> > > replacement to suggest for "global variables".
> > 
> > global variables, and breakpoints, are examples of the "global state"
> > that GDB commands can operate on.
> 
> What GDB commands operate on global variables?

Say, 'print' and 'set' can operate on global variables.

> > > >                    so frontend should try perform such operations on a
> > > > +stopped thread.
> > > 
> > > I don't see how this conclusion follows from the fact that commands
> > > access the target in the context of some thread.  Why doing that "on a
> > > stopped thread" will solve whatever problem you are trying to explain
> > > here? and what does "operations ON a stopped thread" mean in this
> > > context, anyway?
> > 
> > ... and with the explanation above, if doing operations in context of running
> > thread may fail even if that operation only accesses global state, the frontend
> > better pick a thread that is stopped.
> 
> Do you mean that a frontend should do the equivalent of "thread N"
> where N is an ID of a thread that is stopped, before issuing commands?
> If so, let's say that explicitly.  "Pick a thread that is stopped" is
> not clear enough, at least it confuses me.

I mean that frontend should select a stopped thread, and pass id of that
thread using the --thread option. I've clarified this.

> > > > +@smallexample
> > > > +(gdb)
> > > 
> > > This should be @value{GDBP}, I think.
> > 
> > OOC, what practical differences or benefits that will have?
> 
> I understand that both GDBN and GDBP exist so that a manual could be
> easily produced for a customized version of GDB that calls itself
> "gdbfoo" and prompts with "(gdb-foo)", say.  Anyway, this goes way
> back before I assumed the responsibility on the GDB docs; perhaps Stan
> or other old-timers could add some insights.

OK.

> > Thanks for feedback. I attach both the revised version of the patch, and the delta
> > relatively to the previous version.
> 
> The new version is fine, except that there are still instances of only
> one space after a period that ends a sentence.

I've just went though MI section with a regexp, fixing this issue. I'm attaching
another revision. I believe the remaining two outstanding issues are name of
the section, and that @item question above I did not understand. 

Thanks a lot for review!

- Volodya






diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e902177..a29c0d4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18863,7 +18863,7 @@ The important examples of notifications are:
 @itemize @bullet
 
 @item 
-Exec notifications. These are used to report changes in
+Exec notifications.  These are used to report changes in
 target state---when a target is resumed, or stopped.  It would not
 be feasible to include this information in response of resuming
 commands, because one resume commands can result in multiple events in
@@ -18872,16 +18872,16 @@ happens in the target, while a frontend needs to know whether the resuming
 command itself was successfully executed.
 
 @item 
-Console output, and status notifications. Console output
+Console output, and status notifications.  Console output
 notifications are used to report output of CLI commands, as well as
-diagnostics for other commands. Status notifications are used to
+diagnostics for other commands.  Status notifications are used to
 report the progress of a long-running operation.  Naturally, including
 this information in command response would mean no output is produced
 until the command is finished, which is undesirable.
 
 @item
-General notifications. Commands may have various side effects on
-the @value{GDBN} or target state beyond their official purpose. For example,
+General notifications.  Commands may have various side effects on
+the @value{GDBN} or target state beyond their official purpose.  For example,
 a command may change the selected thread.  Although such changes can
 be included in command response, using notification allows for more
 orthogonal frontend design.
@@ -18909,15 +18909,15 @@ to what thread and frame are the current ones.
 
 In the case of MI, the concept of selected thread and frame is less
 useful.  First, a frontend can easily remember this information
-itself.  Second, a graphical frontend can have more than one window, each
-one used for debugging a different thread, and the frontend might
-want to access additional threads for internal purposes.
-This increases the risk that by relying on implicitly selected thread, the
-frontend may be operating on a wrong one.  Therefore, it is
-preferrable that each MI command explicitly specify which thread and
-frame to operate on.  To make it possible, each MI command accepts the
-@samp{--thread} and @samp{--frame} options, the value to each is
-@value{GDBN} identifier for thread and frame to operate on.
+itself.  Second, a graphical frontend can have more than one window,
+each one used for debugging a different thread, and the frontend might
+want to access additional threads for internal purposes.  This
+increases the risk that by relying on implicitly selected thread, the
+frontend may be operating on a wrong one.  Therefore, each MI command
+should explicitly specify which thread and frame to operate on.  To
+make it possible, each MI command accepts the @samp{--thread} and
+@samp{--frame} options, the value to each is @value{GDBN} identifier
+for thread and frame to operate on.
 
 Usually, each top-level window in a frontend allows the user to select
 a thread and a frame, and remembers the user selection for further
@@ -18932,7 +18932,7 @@ No such notification is available for the selected frame at the moment.
 
 Note that historically, MI shares the selected thread with CLI, so 
 frontends used the @code{-thread-select} to execute commands in the
-right context.  However, getting this to work right is cumbersome. The
+right context.  However, getting this to work right is cumbersome.  The
 simplest way is for frontend to emit @code{-thread-select} command
 before every command.  This doubles the number of commands that need
 to be sent.  The alternative approach is to suppress @code{-thread-select}
@@ -18951,41 +18951,35 @@ right, so it is suggested to just always pass the @samp{--thread} and
 
 On some targets, @value{GDBN} is capable of processing MI commands
 even while the target is running.  This is called @dfn{asynchronous
-command execution}.  The frontend may specify a preferrence for
-asynchronous execution using the @code{-gdb-set target-async 1}
-command, which should be emitted before either running the executable
-or attaching to the target.  After the frontend has started the
-executable or attached to the target, it can find if asynchronous
-execution is enabled using the @code{-list-target-features} command.
+command execution} (@pxref{Background Execution}).  The frontend may
+specify a preferrence for asynchronous execution using the
+@code{-gdb-set target-async 1} command, which should be emitted before
+either running the executable or attaching to the target.  After the
+frontend has started the executable or attached to the target, it can
+find if asynchronous execution is enabled using the
+@code{-list-target-features} command.
 
 Even if @value{GDBN} can accept a command while target is running,
 many commands that access the target do not work when the target is
 running.  Therefore, asynchronous command execution is most useful
-when combined with non-stop mode (@pxref{Non-Stop Mode}). Then,
+when combined with non-stop mode (@pxref{Non-Stop Mode}).  Then,
 it is possible to examine the state of one thread, while other threads
 are running.
 
 When a given thread is running, MI commands that try to access the
 target in the context of that thread may not work, or may work only on
-some targets. In particular, commands that try to operate on thread's
-stack will not work, on any target. Commands that read memory, or
+some targets.  In particular, commands that try to operate on thread's
+stack will not work, on any target.  Commands that read memory, or
 modify breakpoints, may work or not work, depending on the target.  Note
 that even commands that operate on global state (like global
 variables, or breakpoints), still access the target in the context of
-a specific thread, so frontend should try perform such operations on a
-stopped thread.
+a specific thread, so frontend should try to find a stopped thread and
+perform the operation on that thread (using the @samp{--thread} option).
 
-Since the set of allowed commands depends on the target, this
-documention does not list which commands are allowed. Also,
-@value{GDBN} does not try to simulate asynchronous execution of
-commands that fail -- in particular, it does not try to briefly
-interrupt an executing thread to execute a command, and it does not
-try to automatically pick a stopped thread and execute a command in
-the context of that thread.
-
-Two commands that are explicitly required to always work are
-@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, to
-find the state of each thread.
+Which commands will work in the context of a running thread is
+highly target dependent.  However, the two commands
+@code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
+to find the state of a thread, will always work.
 
 @subsection Thread groups
 @value{GDBN} may be used to debug several processes at the same time.
@@ -19005,9 +18999,9 @@ into processes.
 
 To allow the user to discover such grouping, and to support arbitrary
 hierarchy of machines/cores/processes, MI introduces the concept of a
-@dfn{thread group}. Thread group is a collection of threads and other
+@dfn{thread group}.  Thread group is a collection of threads and other
 thread groups. A thread group always has a string identifier, a type,
-and may have additional attributes specific to the type. A new
+and may have additional attributes specific to the type.  A new
 command, @code{-list-thread-groups}, returns the list of top-level
 thread groups, which correspond to processes that @value{GDBN} is
 debugging at the moment.  By passing an identifier of a thread group
@@ -21399,12 +21393,11 @@ object will report the value of @code{state} in the top-level
 object will report the value of @code{state} in the current frame.
 
 If an expression specified when creating a fixed variable object
-refers to a local variable, the variable object becomes bound to the 
-frame the local variable belongs to.  For multithreaded programs, the
-variable object also becomes bound to the thread.  When such variable
-object is updated, @value{GDBN} makes sure that the thread/frame
-combination the variable object is bound to still exists, and
-re-evaluates the variable object in context of that thread/frame.
+refers to a local variable, the variable object becomes bound to the
+thread and frame in which the variable object is created.  When such
+variable object is updated, @value{GDBN} makes sure that the
+thread/frame combination the variable object is bound to still exists,
+and re-evaluates the variable object in context of that thread/frame.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -23443,8 +23436,8 @@ while the target is running.
 
 When used without the @var{group} parameter, lists top-level thread
 groups that are being debugged.  When used with the @var{group}
-parameter, the children of the specified group are listed. The
-children can be either threads, or other groups. At present,
+parameter, the children of the specified group are listed.  The
+children can be either threads, or other groups.  At present,
 @value{GDBN} will not report both threads and groups as children at
 the same time, but it may change in future.
 
commit fe0e89238862814086ccae16cd3c2b22d7f03947
Author: Vladimir Prus <vladimir@codesourcery.com>
Date:   Mon Aug 18 13:18:14 2008 +0400

    MI non-stop and multiprocess docs.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index ca8759d..a29c0d4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18816,6 +18816,7 @@ may repeat one or more times.
 @end ignore
 
 @menu
+* GDB/MI General Design::
 * GDB/MI Command Syntax::
 * GDB/MI Compatibility with CLI::
 * GDB/MI Development and Front Ends::
@@ -18843,6 +18844,180 @@ may repeat one or more times.
 @end menu
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI General Design
+@section @sc{gdb/mi} General Design
+@cindex GDB/MI General Design
+
+Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
+parts---commands sent to @value{GDBN}, responses to those commands
+and notifications.  Each command results in exactly one response,
+indicating either successful completion of the command, or an error.
+For the commands that do not resume the target, the response contains the
+requested information.  For the commands that resume the target, the
+response only indicates whether the target was successfully resumed.
+Notifications is the mechanism for reporting changes in the state of the
+target, or in @value{GDBN} state, that cannot conveniently be associated with
+a command and reported as part of that command response.
+
+The important examples of notifications are:
+@itemize @bullet
+
+@item 
+Exec notifications.  These are used to report changes in
+target state---when a target is resumed, or stopped.  It would not
+be feasible to include this information in response of resuming
+commands, because one resume commands can result in multiple events in
+different threads.  Also, quite some time may pass before any event
+happens in the target, while a frontend needs to know whether the resuming
+command itself was successfully executed.
+
+@item 
+Console output, and status notifications.  Console output
+notifications are used to report output of CLI commands, as well as
+diagnostics for other commands.  Status notifications are used to
+report the progress of a long-running operation.  Naturally, including
+this information in command response would mean no output is produced
+until the command is finished, which is undesirable.
+
+@item
+General notifications.  Commands may have various side effects on
+the @value{GDBN} or target state beyond their official purpose.  For example,
+a command may change the selected thread.  Although such changes can
+be included in command response, using notification allows for more
+orthogonal frontend design.
+
+@end itemize
+
+There's no guarantee that whenever an MI command reports an error,
+@value{GDBN} or the target are in any specific state, and especially,
+the state is not reverted to the state before the MI command was
+processed.  Therefore, whenever an MI command results in an error, 
+we recommend that the frontend refreshes all the information shown in 
+the user interface.
+
+@subsection Context management
+
+In most cases when @value{GDBN} accesses the target, this access is
+done in context of a specific thread and frame (@pxref{Frames}).
+Often, even when accessing global data, the target requires that a thread
+be specified.  The CLI interface maintains the selected thread and frame,
+and supplies them to target on each command.  This is convenient,
+because a command line user would not want to specify that information
+explicitly on each command, and because user interacts with
+@value{GDBN} via a single terminal, so no confusion is possible as 
+to what thread and frame are the current ones.
+
+In the case of MI, the concept of selected thread and frame is less
+useful.  First, a frontend can easily remember this information
+itself.  Second, a graphical frontend can have more than one window,
+each one used for debugging a different thread, and the frontend might
+want to access additional threads for internal purposes.  This
+increases the risk that by relying on implicitly selected thread, the
+frontend may be operating on a wrong one.  Therefore, each MI command
+should explicitly specify which thread and frame to operate on.  To
+make it possible, each MI command accepts the @samp{--thread} and
+@samp{--frame} options, the value to each is @value{GDBN} identifier
+for thread and frame to operate on.
+
+Usually, each top-level window in a frontend allows the user to select
+a thread and a frame, and remembers the user selection for further
+operations.  However, in some cases @value{GDBN} may suggest that the
+current thread be changed.  For example, when stopping on a breakpoint
+it is reasonable to switch to the thread where breakpoint is hit.  For
+another example, if the user issues the CLI @samp{thread} command via
+the frontend, it is desirable to change the frontend's selected thread to the
+one specified by user.  @value{GDBN} communicates the suggestion to
+change current thread using the @samp{=thread-selected} notification.
+No such notification is available for the selected frame at the moment.
+
+Note that historically, MI shares the selected thread with CLI, so 
+frontends used the @code{-thread-select} to execute commands in the
+right context.  However, getting this to work right is cumbersome.  The
+simplest way is for frontend to emit @code{-thread-select} command
+before every command.  This doubles the number of commands that need
+to be sent.  The alternative approach is to suppress @code{-thread-select}
+if the selected thread in @value{GDBN} is supposed to be identical to the
+thread the frontend wants to operate on.  However, getting this
+optimization right can be tricky.  In particular, if the frontend
+sends several commands to @value{GDBN}, and one of the commands changes the
+selected thread, then the behaviour of subsequent commands will
+change.  So, a frontend should either wait for response from such
+problematic commands, or explicitly add @code{-thread-select} for
+all subsequent commands.  No frontend is known to do this exactly
+right, so it is suggested to just always pass the @samp{--thread} and
+@samp{--frame} options.
+
+@subsection Asynchronous command execution and non-stop mode
+
+On some targets, @value{GDBN} is capable of processing MI commands
+even while the target is running.  This is called @dfn{asynchronous
+command execution} (@pxref{Background Execution}).  The frontend may
+specify a preferrence for asynchronous execution using the
+@code{-gdb-set target-async 1} command, which should be emitted before
+either running the executable or attaching to the target.  After the
+frontend has started the executable or attached to the target, it can
+find if asynchronous execution is enabled using the
+@code{-list-target-features} command.
+
+Even if @value{GDBN} can accept a command while target is running,
+many commands that access the target do not work when the target is
+running.  Therefore, asynchronous command execution is most useful
+when combined with non-stop mode (@pxref{Non-Stop Mode}).  Then,
+it is possible to examine the state of one thread, while other threads
+are running.
+
+When a given thread is running, MI commands that try to access the
+target in the context of that thread may not work, or may work only on
+some targets.  In particular, commands that try to operate on thread's
+stack will not work, on any target.  Commands that read memory, or
+modify breakpoints, may work or not work, depending on the target.  Note
+that even commands that operate on global state (like global
+variables, or breakpoints), still access the target in the context of
+a specific thread, so frontend should try to find a stopped thread and
+perform the operation on that thread (using the @samp{--thread} option).
+
+Which commands will work in the context of a running thread is
+highly target dependent.  However, the two commands
+@code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
+to find the state of a thread, will always work.
+
+@subsection Thread groups
+@value{GDBN} may be used to debug several processes at the same time.
+On some platfroms, @value{GDBN} may support debugging of several
+hardware systems, each one having several cores with several different
+processes running on each core.  This section describes the MI
+mechanism to support such debugging scenarios.
+
+The key observation is that regardless of the structure of the 
+target, MI can have a global list of threads, because most commands that 
+accept the @samp{--thread} option do not need to know what process that
+thread belongs to.  Therefore, it is not necessary to introduce
+neither additional @samp{--process} option, nor an notion of the
+current process in the MI interface.  The only strictly new feature
+that is required is the ability to find how the threads are grouped
+into processes.
+
+To allow the user to discover such grouping, and to support arbitrary
+hierarchy of machines/cores/processes, MI introduces the concept of a
+@dfn{thread group}.  Thread group is a collection of threads and other
+thread groups. A thread group always has a string identifier, a type,
+and may have additional attributes specific to the type.  A new
+command, @code{-list-thread-groups}, returns the list of top-level
+thread groups, which correspond to processes that @value{GDBN} is
+debugging at the moment.  By passing an identifier of a thread group
+to the @code{-list-thread-groups} command, it is possible to obtain
+the members of specific thread group.
+
+To allow the user to easily discover processes, and other objects, he
+wishes to debug, a concept of @dfn{available thread group} is
+introduced.  Available thread group is an thread group that
+@value{GDBN} is not debugging, but that can be attached to, using the
+@code{-target-attach} command.  The list of available top-level thread
+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.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Command Syntax
 @section @sc{gdb/mi} Command Syntax
 
@@ -19145,6 +19320,7 @@ follow development on @email{gdb@@sourceware.org} and
 * GDB/MI Result Records::
 * GDB/MI Stream Records::
 * GDB/MI Async Records::
+* GDB/MI Frame Information::
 @end menu
 
 @node GDB/MI Result Records
@@ -19237,7 +19413,7 @@ several times, either for different threads, because it cannot resume
 all threads together, or even for a single thread, if the thread must
 be stepped though some code before letting it run freely.
 
-@item *stopped,reason="@var{reason}"
+@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}"
 The target has stopped.  The @var{reason} field can have one of the
 following values:
 
@@ -19269,10 +19445,27 @@ The inferior exited normally.
 A signal was received by the inferior.
 @end table
 
-@item =thread-created,id="@var{id}"
-@itemx =thread-exited,id="@var{id}"
+The @var{id} field identifies the thread that directly caused the stop
+-- for example by hitting a breakpoint.  Depending on whether all-stop
+mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
+stop all threads, or only the thread that directly triggered the stop.
+If all threads are stopped, the @var{stopped} field will have the
+value of @code{"all"}.  Otherwise, the value of the @var{stopped}
+field will be a list of thread identifiers.  Presently, this list will
+always include a single thread, but frontend should be prepared to see
+several threads in the list.
+
+@item =thread-group-created,id="@var{id}"
+@itemx =thread-group-exited,id="@var{id}"
+A thread thread group either was attached to, or has exited/detached
+from.  The @var{id} field contains the @value{GDBN} identifier of the
+thread group.
+
+@item =thread-created,id="@var{id}",group-id="@var{gid}"
+@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
 A thread either was created, or has exited.  The @var{id} field
-contains the @value{GDBN} identifier of the thread.
+contains the @value{GDBN} identifier of the thread.  The @var{gid}
+field identifies the thread group this thread belongs to.
 
 @item =thread-selected,id="@var{id}"
 Informs that the selected thread was changed as result of the last
@@ -19288,6 +19481,38 @@ that thread.
 
 @end table
 
+@node GDB/MI Frame Information
+@subsection @sc{gdb/mi} Frame Information
+
+Response from many MI commands includes an information about stack
+frame.  This information is a tuple that may have the following
+fields:
+
+@table @code
+@item level
+The level of the stack frame.  The innermost frame has the level of
+zero.  This field is always present.
+
+@item func
+The name of the function corresponding to the frame.  This field may
+be absent if @value{GDBN} is unable to determine the function name.
+
+@item addr
+The code address for the frame.  This field is always present.
+
+@item file
+The name of the source files that correspond to the frame's code
+address.  This field may be absent.
+
+@item line
+The source line corresponding to the frames' code address.  This field
+may be absent.
+
+@item from
+The name of the binary file (either executable or shared library) the
+corresponds to the frame's code address.  This field may be absent.
+
+@end table
 
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -20174,14 +20399,27 @@ about all threads.
 -thread-info
 ^done,threads=[
 @{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
-   frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},
+   frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
 @{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
    frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
-           file="/tmp/a.c",fullname="/tmp/a.c",line="158"@}@}],
+           file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}],
 current-thread-id="1"
 (gdb)
 @end smallexample
 
+The @samp{state} field may have the following values:
+
+@table @code
+@item stopped
+The thread is stopped.  Frame information is available for stopped
+threads.
+
+@item running
+The thread is running.  There's no frame information for running
+threads.
+
+@end table
+
 @subheading The @code{-thread-list-ids} Command
 @findex -thread-list-ids
 
@@ -20194,6 +20432,9 @@ current-thread-id="1"
 Produces a list of the currently known @value{GDBN} thread ids.  At the
 end of the list it also prints the total number of such threads.
 
+This command is retained for historical reasons, the
+@code{-thread-info} command should be used instead.
+
 @subsubheading @value{GDBN} Command
 
 Part of @samp{info threads} supplies the same information.
@@ -20233,6 +20474,9 @@ number-of-threads="3"
 Make @var{threadnum} the current thread.  It prints the number of the new
 current thread, and the topmost frame for that thread.
 
+This command is deprecated in favor of explicitly using the
+@samp{--thread} option to each command.
+
 @subsubheading @value{GDBN} Command
 
 The corresponding @value{GDBN} command is @samp{thread}.
@@ -20275,11 +20519,20 @@ other cases.
 @subsubheading Synopsis
 
 @smallexample
- -exec-continue
+ -exec-continue [--all|--thread-group N]
 @end smallexample
 
 Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits.
+encountered, or until the inferior exits.  In all-stop mode
+(@pxref{All-Stop Mode}), may resume only one thread, or all threads,
+depending on the value of the @samp{scheduler-locking} variable.  In
+non-stop mode (@pxref{Non-Stop Mode}), if the @samp{--all} is not
+specified, only the thread specified with the @samp{--thread} option
+(or current thread, if no @samp{--thread} is provided) is resumed.  If
+@samp{--all} is specified, all threads will be resumed.  The
+@samp{--all} option is ignored in all-stop mode.  If the
+@samp{--thread-group} options is specified, then all threads in that
+thread group are resumed.
 
 @subsubheading @value{GDBN} Command
 
@@ -20351,7 +20604,7 @@ gdb-result-var="$1",return-value="0"
 @subsubheading Synopsis
 
 @smallexample
- -exec-interrupt
+ -exec-interrupt [--all|--thread-group N]
 @end smallexample
 
 Interrupts the background execution of the target.  Note how the token
@@ -20360,6 +20613,16 @@ that has been interrupted.  The token for the interrupt itself only
 appears in the @samp{^done} output.  If the user is trying to
 interrupt a non-running program, an error message will be printed.
 
+Note that when asynchronous execution is enabled, this command is
+asynchronous just like other execution commands.  That is, first the
+@samp{^done} response will be printed, and the target stop will be
+reported after that using the @samp{*stopped} notification.
+
+In non-stop mode, only the context thread is interrupted by default.
+All threads will be interrupted if the @samp{--all} option is
+specified.  If the @samp{--thread-group} option is specified, all
+threads in that group will be interrupted.
+
 @subsubheading @value{GDBN} Command
 
 The corresponding @value{GDBN} command is @samp{interrupt}.
@@ -20997,6 +21260,9 @@ more detail.
 Change the selected frame.  Select a different frame @var{framenum} on
 the stack.
 
+This command in deprecated in favor of passing the @samp{--frame}
+option to every command.
+
 @subsubheading @value{GDBN} Command
 
 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
@@ -21102,6 +21368,37 @@ visible on the screen, or ``closed''.  This is possible using so
 called ``frozen variable objects''.  Such variable objects are never
 implicitly updated.  
 
+Variable objects can be either @dfn{fixed} or @dfn{floating}.  For the
+fixed variable object, the expression is parsed when the variable
+object is created, including associating identifiers to specific
+variables.  The meaning of expression never changes.  For a floating
+variable object the values of variables whose names appear in the
+expressions are re-evaluated every time in the context of the current
+frame.  Consider this example:
+
+@smallexample
+void do_work(...)
+@{
+        struct work_state state;
+
+        if (...)
+           do_work(...);
+@}
+@end smallexample
+
+If a fixed variable object for the @code{state} variable is created in
+this function, and we enter the recursive call, the the variable
+object will report the value of @code{state} in the top-level
+@code{do_work} invocation.  On the other hand, a floating variable
+object will report the value of @code{state} in the current frame.
+
+If an expression specified when creating a fixed variable object
+refers to a local variable, the variable object becomes bound to the
+thread and frame in which the variable object is created.  When such
+variable object is updated, @value{GDBN} makes sure that the
+thread/frame combination the variable object is bound to still exists,
+and re-evaluates the variable object in context of that thread/frame.
+
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
 
@@ -21151,7 +21448,7 @@ how it can be used.
 
 @smallexample
  -var-create @{@var{name} | "-"@}
-    @{@var{frame-addr} | "*"@} @var{expression}
+    @{@var{frame-addr} | "*" | "@@"@} @var{expression}
 @end smallexample
 
 This operation creates a variable object, which allows the monitoring of
@@ -21161,12 +21458,13 @@ register.
 The @var{name} parameter is the string by which the object can be
 referenced.  It must be unique.  If @samp{-} is specified, the varobj
 system will generate a string ``varNNNNNN'' automatically.  It will be
-unique provided that one does not specify @var{name} on that format.
+unique provided that one does not specify @var{name} of that format.
 The command fails if a duplicate name is found.
 
 The frame under which the expression should be evaluated can be
 specified by @var{frame-addr}.  A @samp{*} indicates that the current
-frame should be used.
+frame should be used.  A @samp{@@} indicates that a floating variable
+object must be created.
 
 @var{expression} is any expression valid on the current language set (must not
 begin with a @samp{*}), or one of the following:
@@ -21186,10 +21484,11 @@ begin with a @samp{*}), or one of the following:
 
 This operation returns the name, number of children and the type of the
 object created.  Type is returned as a string as the ones generated by
-the @value{GDBN} CLI:
+the @value{GDBN} CLI.  If a fixed variable object is bound to a
+specific thread, the thread is is also printed:
 
 @smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
 @end smallexample
 
 
@@ -21464,6 +21763,9 @@ as for @code{-var-list-children} (@pxref{-var-list-children}).  It is
 recommended to use the @samp{--all-values} option, to reduce the
 number of MI commands needed on each program stop.
 
+With the @samp{*} parameter, if a variable object is bound to a
+currently running thread, it will not be updated, without any
+diagnostic.
 
 @subsubheading Example
 
@@ -22522,10 +22824,13 @@ Signal handling commands are not implemented.
 @subsubheading Synopsis
 
 @smallexample
- -target-attach @var{pid} | @var{file}
+ -target-attach @var{pid} | @var{gid} | @var{file}
 @end smallexample
 
-Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
+Attach to a process @var{pid} or a file @var{file} outside of
+@value{GDBN}, or a thread group @var{gid}.  If attaching to a thread
+group, the id previously returned by 
+@samp{-list-thread-groups --available} must be used.
 
 @subsubheading @value{GDBN} Command
 
@@ -22567,11 +22872,12 @@ N.A.
 @subsubheading Synopsis
 
 @smallexample
- -target-detach
+ -target-detach [ @var{pid} | @var{gid} ]
 @end smallexample
 
 Detach from the remote target which normally resumes its execution.
-There's no output.
+If either @var{pid} or @var{gid} is specified, detaches from either
+the specified process, or specified thread group.  There's no output.
 
 @subsubheading @value{GDBN} Command
 
@@ -23119,6 +23425,40 @@ while the target is running.
 
 @end table
 
+@subheading The @code{-list-thread-groups} Command
+@findex -list-thread-groups
+
+@subheading Synopsis
+
+@smallexample
+-list-thread-groups [ --available ] [ @var{group} ]
+@end smallexample
+
+When used without the @var{group} parameter, lists top-level thread
+groups that are being debugged.  When used with the @var{group}
+parameter, the children of the specified group are listed.  The
+children can be either threads, or other groups.  At present,
+@value{GDBN} will not report both threads and groups as children at
+the same time, but it may change in future.
+
+With the @samp{--available} option, instead of reporting groups that
+are been debugged, GDB will report all thread groups available on the
+target.  Using the @samp{--available} option together with @var{group}
+is not allowed.
+
+@subheading Example
+
+@smallexample
+@value{GDBP}
+-list-thread-groups
+^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
+-list-thread-groups 17
+^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+   frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
+@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+   frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
+           file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+@end smallexample
 
 @subheading The @code{-interpreter-exec} Command
 @findex -interpreter-exec

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]