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 Saturday 08 November 2008 15:04:31 Eli Zaretskii wrote:

> 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. It is not some optional "best practices" document -- if read failed
to read what notifications are, or does not know how MI manages contexts,
he cannot create a working frontend.

> > +parts --- commands sent to @value{GDBN}, responses to those commands
> 
> 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?
(It appears that there's no universal opinion on this matter, so this is necessary
a GDB-local guideline).


> >                                  Status notifications are used to
> 
> Wouldn't it be better to make "Status notifications" a separate @item
> in this list?

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.

> >                                                       Therefore, it is
> > +preferrable that each MI command explicitly specify which thread and
>    ^^^^^^^^^^^
> "preferable".  Also, perhaps rephrase as "Therefore, we recommend that
> each MI command ...".  This removes passive tense from the sentence,
> which makes the sentence more concise and clear.

I think it's not strong enough. How about:

	Therefore, each MI command should explicitly specify which thread and

(And then, I'd have to adjust the last sentence of the next paragraph to remove
weak "suggested", and say that omitting --thread and --frame is allowed only for 
backward compatibility)

> > +On some targets, @value{GDBN} is capable of processing MI commands
> > +even while the target is running.  This is called asynchronous command
> > +execution.
> 
> 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.

> > +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. The point here is that even some
command appears to access only global state -- for example a global
variable, or a breakpoint list, the access is still is done in context
of a specific thread, and will fail, on may targets, if that thread is running....

> 
> >                    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.

> > +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.
> 
> I fail to understand why these two paragraphs are useful, nor why they
> are in this particular place.  If the first sentence of the first
> paragraph is related to the second paragraph, let's put them together,
> and let's also make the first sentence less general ("this
> documentation", as written, seems to refer to the entire manual).
> 
> As for the second sentence of the first paragraph, I completely fail
> to grasp the significance of what you are saying, or to parse the
> "does not try to simulate asynchronous execution of commands that
> fail" part.  Can you help me understand what you are trying to say
> here?

Earlier we've said that GDB commands *may* fail is executed in context of a
running thread. The immediate question is whether GDB/MI documentation has
more accurate information what commands will fail in what cases. This
paragraph states that such information is highly dependent on the target,
and GDB/MI cannot promise anything. It further tries to state that if target
cannot perform some operation in the context of a running thread, GDB will
not try to simulate that, for example, by stopping thread, doing the operation,
and resuming thread.

> 
> > +In future, support for debugging several hardware systems, each with
>    ^^^^^^^^^
> "In the future"
> 
> > +several cores, each with different processes, is likely.
> 
> "is likely" is too far from its subject, which makes this sentence
> awkward to read.  Suggest to rearrange this sentence:
> 
>   In the future, it is likely that @value{GDBN} will support debugging
>   of several hardware systems, each one having several cores with
>   several different processes running on each core.
> 
> Btw, talking about "the future" in a manual is problematic, because
> "the future" turns out to be present at some point, and then the text
> sounds obsolete for no good reason.  How about replacing "in the
> future" with "on some platforms" (and getting rid of "will" and the
> future tense)?

Ok, did so.

> 
> > +                    Every command that accepts the @samp{--thread}
> > +does not care of the thread's position in the target hierarchy and
> 
> What is "the thread's position in the target hierarchy"? what
> hierarchy is being referenced here?

I've ended up rewriting entire section about thread groups -- I could
not find a way to address your comments with local edits.

> > +@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.
> 
> Do we have the description of what exactly is a thread group id,
> anywhere in the manual?  If so, please add here an xref to that
> place.  If we don't have such a description, we should add one.
 
Well, we don't have description for thread id, either -- it's just
a string.

> >  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, may
> 
> A @pxref to the node that describes the all-stop mode would be useful
> here.

Done.

> > +resume only one thread, or all threads, depending on the value of the
> > +@samp{scheduler-mode} variable.
> 
> You mean scheduler-locking, not scheduler-mode, right?  If so, please
> add a reference to the node that describes it.

It's the same node as for All-Stop Mode, so it's already referred to.

> > +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.
> 
> What is the meaning of a local variable _belonging_ to a frame?  Do
> you mean the frame in whose scope it exists at the time of specifying
> the expression for a fixed variable?

Yes. Or, rather, my model is that local variables do not exist independently,
but rather we have a set of stack frames, and each stack frame has a number
of local variables. So a single local variable at compilation time may correspond
to multiple local variable, in different threads/frames, at runtime.

> 
> >                                       For multithreaded programs, the
> > +variable object also becomes bound to the thread.
> 
> Again, what thread is that? how is it determined?

It might be best to reword the last two sentences thusly:

	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.

> > +@smallexample
> > +(gdb)
> 
> This should be @value{GDBP}, I think.

OOC, what practical differences or benefits that will have?

> 
> > +-list-thread-groups
> > +^done,threads=[],groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
> 
> The command description says it will report thread groups, but the
> output shown in the example also includes "threads=[]".  What is that
> part?

I've revised this.


Thanks for feedback. I attach both the revised version of the patch, and the delta
relatively to the previous version.

Thanks,
Volodya


diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5f5b348..8b3c95c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18846,16 +18846,17 @@ may repeat one or more times.
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI General Design
 @section @sc{gdb/mi} General Design
+@cindex GDB/MI General Design
 
-Interaction of a GDB/MI frontend with @value{GDBN} involves three
-parts --- commands sent to @value{GDBN}, responses to those commands
+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, response contains the
-requested information.  For the commands that resume target, the
-response only indicates if the target was successfully resumed.
-Notifications is the mechanism to report changes in the state of the
-target, or in GDB state, that cannot conveniently be associated with
+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:
@@ -18863,24 +18864,24 @@ The important examples of notifications are:
 
 @item 
 Exec notifications. These are used to report changes in
-target state -- when a target is resumed, or stopped.  It would not
+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 frontend needs to know if the resuming
+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
-diagnostic 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 GDB or target state beyond their official purpose. For example,
+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.
@@ -18888,32 +18889,33 @@ orthogonal frontend design.
 @end itemize
 
 There's no guarantee that whenever an MI command reports an error,
-@value{GDBN} or the target is in any specific state, and especially,
+@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, frontend is recommended, whenever an MI command
-results in error, to refresh all information shown in the user
-interface.
+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 specific thread and frame.  Often, even when
-accessing global data, target requires that a thread be specified.  The
-CLI interface maintains 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 GDB with a single terminal,
-so no confusion as to what thread and frame are current is possible.
+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,
-and user may work with different threads in each one, and the frontend
-might want to access other threads for internal purposes.  This
-increases the risk that by relying on implicitly selected thread, the
+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
+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.
 
@@ -18922,22 +18924,22 @@ 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 CLI @samp{thread} command via
-frontend, it is desirable to change frontend's selected thread to the
+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 selected frame at the moment.
+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 amount of command that has
+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 equal to the
+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 GDB, and one of the commands changes the
+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
@@ -18948,26 +18950,26 @@ right, so it is suggested to just always pass the @samp{--thread} and
 @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 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.  When 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 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.
 
 Even if @value{GDBN} can accept a command while target is running,
-many commands that access a target do not work when a target is
+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 context of that thread may not work, or may work only on
+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 target.  Note
+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
@@ -18987,41 +18989,39 @@ find the state of each thread.
 
 @subsection Thread groups
 @value{GDBN} may be used to debug several processes at the same time.
-In future, support for debugging several hardware systems, each with
-several cores, each with different processes, is likely. This section
-describes the MI mechanism to support such debugging scenarios, called
-@emph{thread groups}.  The primary design goal of this mechanism was
-to be minimally intrusive on existing frontends. The key aspects are:
-
-@itemize @bullet
-
-@item 
-Regardless of the structure of the target, MI has a global
-list of threads.  Every command that accepts the @samp{--thread}
-does not care of the thread's position in the target hierarchy and
-does not require any options to specify the process to operate on.
-
-@item
-To help frontend user to understand the target hierarchy,
-threads can be grouped in thread groups.  The 
-@code{-list-thread-groups} command lists all the thread groups current
-being debugged, and allows to navigate a specific thread group.
-
-@item 
-It is possible to list the thread groups available on the target
-but not debugged yet with the @samp{-list-thread-groups --available}
-command.  What thread groups are available depends on the target, for
-example it might be processes.
-
-@item 
-It is possible to attach to thread group reported by 
-@samp{-list-thread-groups} by passing thread group id to the
-@code{-target-attach} command.
-
-@item 
-The @code{-exec-continue} and @code{-exec-interrupt} commands
-accept the @samp{--thread-group} option, to continue or interrupt the
-entire thread group.
+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.
 
 @end itemize
 
@@ -19492,7 +19492,7 @@ that thread.
 @node GDB/MI Frame Information
 @subsection @sc{gdb/mi} Frame Information
 
-Response from many MI commands include an information about stack
+Response from many MI commands includes an information about stack
 frame.  This information is a tuple that may have the following
 fields:
 
@@ -19518,7 +19518,7 @@ may be absent.
 
 @item from
 The name of the binary file (either executable or shared library) the
-corresponds to the frame's code address.
+corresponds to the frame's code address.  This field may be absent.
 
 @end table
 
@@ -20531,13 +20531,16 @@ other cases.
 @end smallexample
 
 Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits.  In all-stop mode, may
-resume only one thread, or all threads, depending on the value of the
-@samp{scheduler-mode} variable.  In non-stop mode, if the @samp{--all}
-is not specified, only the context thread 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.
+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
 
@@ -21403,7 +21406,7 @@ 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 that thread/frame.
+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:
@@ -21494,7 +21497,7 @@ 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}",thread-id="M"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
 @end smallexample
 
 
@@ -21773,8 +21776,6 @@ 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
 
 @smallexample
@@ -23442,23 +23443,30 @@ while the target is running.
 -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.
+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,
-not only the presently debugged ones.  Using the @samp{--available} option
-together with @var{group} is not allowed.
+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
-(gdb)
+@value{GDBP}
 -list-thread-groups
-^done,threads=[],groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
+^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
commit 645d1220594e00632ff85980bc5249a3f8c3e631
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..e902177 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,186 @@ 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, 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.
+
+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}.  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 perform such operations on a
+stopped thread.
+
+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.
+
+@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 +19326,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 +19419,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 +19451,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 +19487,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 +20405,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 +20438,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 +20480,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 +20525,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 +20610,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 +20619,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 +21266,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 +21374,38 @@ 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 
+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.
+
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
 
@@ -21151,7 +21455,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 +21465,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 +21491,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 +21770,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 +22831,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 +22879,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 +23432,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]