Mirror of the gdb-patches mailing list
 help / color / mirror / Atom feed
* [RFC] MI non-stop and multiprocess docs.
@ 2008-11-04 19:15 Vladimir Prus
  2008-11-04 21:22 ` Eli Zaretskii
  2008-11-08 12:05 ` Eli Zaretskii
  0 siblings, 2 replies; 10+ messages in thread
From: Vladimir Prus @ 2008-11-04 19:15 UTC (permalink / raw)
  To: gdb-patches


The attached patch adds quite a pile of new MI documentation:

- General design notes are added, in particular noting how commands that run
  target are special
- The new way to specify thread and frame for a command is explained, together
  with notes why the older way is not good.
- I explicitly written down what fields GDB may report for a frame
- The previously posted and discussed docs for fixed/floating varobjs are
  revised per comments and incorporated. See:

	http://thread.gmane.org/gmane.comp.gdb.patches/40085

- Various random changes from non-stop work are added.
- Documentation for the MI multiprocess extensions is also added. The patches are
  not in, yet, but the spec they are based on was discussed on gdb-devel long time
  ago and the behaviour is agreed upon -- and I wanted to post docs first so that
  if anybody wants to look at the patches, he can have the up-to-date docs.

Comments?

- Volodya


---
 gdb/doc/gdb.texinfo |  377 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 359 insertions(+), 18 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index ca8759d..5f5b348 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,188 @@ may repeat one or more times.
 @end menu
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI General Design
+@section @sc{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
+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
+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 frontend needs to know if 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
+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,
+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 is 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.
+
+@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.
+
+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
+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 CLI @samp{thread} command via
+frontend, it is desirable to change 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.
+
+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
+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
+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
+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 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 if @value{GDBN} can accept a command while target is running,
+many commands that access a target do not work when a 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
+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
+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.
+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.
+
+@end itemize
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Command Syntax
 @section @sc{gdb/mi} Command Syntax
 
@@ -19145,6 +19328,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 +19421,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 +19453,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 +19489,38 @@ that thread.
 
 @end table
 
+@node GDB/MI Frame Information
+@subsection @sc{gdb/mi} Frame Information
+
+Response from many MI commands include 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.
+
+@end table
 
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -20174,14 +20407,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 +20440,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 +20482,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 +20527,17 @@ 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, 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.
 
 @subsubheading @value{GDBN} Command
 
@@ -20351,7 +20609,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 +20618,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 +21265,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 +21373,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 that thread/frame.
+
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
 
@@ -21151,7 +21454,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 +21464,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 +21490,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="N",type="@var{type}",thread-id="M"
 @end smallexample
 
 
@@ -21464,6 +21769,11 @@ 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 +22832,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 +22880,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 +23433,33 @@ 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,
+not only the presently debugged ones.  Using the @samp{--available} option
+together with @var{group} is not allowed.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-list-thread-groups
+^done,threads=[],groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
+@end smallexample
 
 @subheading The @code{-interpreter-exec} Command
 @findex -interpreter-exec
-- 
1.5.3.5


^ permalink raw reply	[flat|nested] 10+ messages in thread
end of thread, other threads:[~2008-11-13 14:48 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2008-11-04 19:15 [RFC] MI non-stop and multiprocess docs Vladimir Prus
2008-11-04 21:22 ` Eli Zaretskii
2008-11-08 12:05 ` Eli Zaretskii
2008-11-12 20:37   ` Vladimir Prus
2008-11-12 20:44     ` Eli Zaretskii
2008-11-12 20:47       ` Vladimir Prus
2008-11-13  4:15         ` Eli Zaretskii
2008-11-13  5:31           ` Vladimir Prus
2008-11-13 13:42             ` Eli Zaretskii
2008-11-13 19:27               ` Vladimir Prus

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox