From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 11095 invoked by alias); 4 Nov 2008 19:15:40 -0000 Received: (qmail 10685 invoked by uid 22791); 4 Nov 2008 19:15:37 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Tue, 04 Nov 2008 19:14:49 +0000 Received: (qmail 12998 invoked from network); 4 Nov 2008 19:14:45 -0000 Received: from unknown (HELO localhost) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 4 Nov 2008 19:14:45 -0000 From: Vladimir Prus Date: Tue, 04 Nov 2008 19:15:00 -0000 Subject: [RFC] MI non-stop and multiprocess docs. To: gdb-patches@sources.redhat.com X-TUID: cf3978e711d75311 X-Length: 23823 X-UID: 349 MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200811042214.51102.vladimir@codesourcery.com> Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-11/txt/msg00044.txt.bz2 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