From c3b108f782597f25c5212de6ba10c2f4ab1aece4 Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Tue, 2 Dec 2008 08:01:15 +0000 Subject: [PATCH] MI non-stop and multiprocess docs. * gdb.texinfo (GDB/MI): New section 'GDB/MI General Design' (GDB/MI Output Records): New section 'GDB/MI Frame Information' Adjust documentation for *stopped, document =thread-created, =thread-exited, =thread-group-created and =thread-group-exited. (GDB/MI Thread Commands): Document the 'state' field in -thread-info output. (GDB/MI Program Execution): Mention --all and --thread-group options. (GDB/MI Variable Objects): Describe floating and fixed variable objects. (GDB/MI Miscellaneous Commands): Document -list-thread-groups. --- gdb/doc/ChangeLog | 16 ++ gdb/doc/gdb.texinfo | 377 +++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 375 insertions(+), 18 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 2819d883d91..02e4455a596 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,19 @@ +2008-12-02 Vladimir Prus + + MI non-stop and multiprocess docs. + + * gdb.texinfo (GDB/MI): New section 'GDB/MI General Design' + (GDB/MI Output Records): New section 'GDB/MI Frame Information' + Adjust documentation for *stopped, document =thread-created, + =thread-exited, =thread-group-created and =thread-group-exited. + (GDB/MI Thread Commands): Document the 'state' field in + -thread-info output. + (GDB/MI Program Execution): Mention --all and --thread-group + options. + (GDB/MI Variable Objects): Describe floating and fixed variable + objects. + (GDB/MI Miscellaneous Commands): Document -list-thread-groups. + 2008-12-02 Vladimir Prus * gdb.texinfo (Operating System Information): New appendix. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 73e2bb4c070..a6fabe3774f 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -18877,6 +18877,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:: @@ -18903,6 +18904,181 @@ may repeat one or more times. * GDB/MI Miscellaneous Commands:: @end menu +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI General Design +@section @sc{gdb/mi} General Design +@cindex GDB/MI General Design + +Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three +parts---commands sent to @value{GDBN}, responses to those commands +and notifications. Each command results in exactly one response, +indicating either successful completion of the command, or an error. +For the commands that do not resume the target, the response contains the +requested information. For the commands that resume the target, the +response only indicates whether the target was successfully resumed. +Notifications is the mechanism for reporting changes in the state of the +target, or in @value{GDBN} state, that cannot conveniently be associated with +a command and reported as part of that command response. + +The important examples of notifications are: +@itemize @bullet + +@item +Exec notifications. These are used to report changes in +target state---when a target is resumed, or stopped. It would not +be feasible to include this information in response of resuming +commands, because one resume commands can result in multiple events in +different threads. Also, quite some time may pass before any event +happens in the target, while a frontend needs to know whether the resuming +command itself was successfully executed. + +@item +Console output, and status notifications. Console output +notifications are used to report output of CLI commands, as well as +diagnostics for other commands. Status notifications are used to +report the progress of a long-running operation. Naturally, including +this information in command response would mean no output is produced +until the command is finished, which is undesirable. + +@item +General notifications. Commands may have various side effects on +the @value{GDBN} or target state beyond their official purpose. For example, +a command may change the selected thread. Although such changes can +be included in command response, using notification allows for more +orthogonal frontend design. + +@end itemize + +There's no guarantee that whenever an MI command reports an error, +@value{GDBN} or the target are in any specific state, and especially, +the state is not reverted to the state before the MI command was +processed. Therefore, whenever an MI command results in an error, +we recommend that the frontend refreshes all the information shown in +the user interface. + +@subsection Context management + +In most cases when @value{GDBN} accesses the target, this access is +done in context of a specific thread and frame (@pxref{Frames}). +Often, even when accessing global data, the target requires that a thread +be specified. The CLI interface maintains the selected thread and frame, +and supplies them to target on each command. This is convenient, +because a command line user would not want to specify that information +explicitly on each command, and because user interacts with +@value{GDBN} via a single terminal, so no confusion is possible as +to what thread and frame are the current ones. + +In the case of MI, the concept of selected thread and frame is less +useful. First, a frontend can easily remember this information +itself. Second, a graphical frontend can have more than one window, +each one used for debugging a different thread, and the frontend might +want to access additional threads for internal purposes. This +increases the risk that by relying on implicitly selected thread, the +frontend may be operating on a wrong one. Therefore, each MI command +should explicitly specify which thread and frame to operate on. To +make it possible, each MI command accepts the @samp{--thread} and +@samp{--frame} options, the value to each is @value{GDBN} identifier +for thread and frame to operate on. + +Usually, each top-level window in a frontend allows the user to select +a thread and a frame, and remembers the user selection for further +operations. However, in some cases @value{GDBN} may suggest that the +current thread be changed. For example, when stopping on a breakpoint +it is reasonable to switch to the thread where breakpoint is hit. For +another example, if the user issues the CLI @samp{thread} command via +the frontend, it is desirable to change the frontend's selected thread to the +one specified by user. @value{GDBN} communicates the suggestion to +change current thread using the @samp{=thread-selected} notification. +No such notification is available for the selected frame at the moment. + +Note that historically, MI shares the selected thread with CLI, so +frontends used the @code{-thread-select} to execute commands in the +right context. However, getting this to work right is cumbersome. The +simplest way is for frontend to emit @code{-thread-select} command +before every command. This doubles the number of commands that need +to be sent. The alternative approach is to suppress @code{-thread-select} +if the selected thread in @value{GDBN} is supposed to be identical to the +thread the frontend wants to operate on. However, getting this +optimization right can be tricky. In particular, if the frontend +sends several commands to @value{GDBN}, and one of the commands changes the +selected thread, then the behaviour of subsequent commands will +change. So, a frontend should either wait for response from such +problematic commands, or explicitly add @code{-thread-select} for +all subsequent commands. No frontend is known to do this exactly +right, so it is suggested to just always pass the @samp{--thread} and +@samp{--frame} options. + +@subsection Asynchronous command execution and non-stop mode + +On some targets, @value{GDBN} is capable of processing MI commands +even while the target is running. This is called @dfn{asynchronous +command execution} (@pxref{Background Execution}). The frontend may +specify a preferrence for asynchronous execution using the +@code{-gdb-set target-async 1} command, which should be emitted before +either running the executable or attaching to the target. After the +frontend has started the executable or attached to the target, it can +find if asynchronous execution is enabled using the +@code{-list-target-features} command. + +Even if @value{GDBN} can accept a command while target is running, +many commands that access the target do not work when the target is +running. Therefore, asynchronous command execution is most useful +when combined with non-stop mode (@pxref{Non-Stop Mode}). Then, +it is possible to examine the state of one thread, while other threads +are running. + +When a given thread is running, MI commands that try to access the +target in the context of that thread may not work, or may work only on +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or +modify breakpoints, may work or not work, depending on the target. Note +that even commands that operate on global state, such as @code{print}, +@code{set}, and breakpoint commands, still access the target in the +context of a specific thread, so frontend should try to find a +stopped thread and perform the operation on that thread (using the +@samp{--thread} option). + +Which commands will work in the context of a running thread is +highly target dependent. However, the two commands +@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, +to find the state of a thread, will always work. + +@subsection Thread groups +@value{GDBN} may be used to debug several processes at the same time. +On some platfroms, @value{GDBN} may support debugging of several +hardware systems, each one having several cores with several different +processes running on each core. This section describes the MI +mechanism to support such debugging scenarios. + +The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that +accept the @samp{--thread} option do not need to know what process that +thread belongs to. Therefore, it is not necessary to introduce +neither additional @samp{--process} option, nor an notion of the +current process in the MI interface. The only strictly new feature +that is required is the ability to find how the threads are grouped +into processes. + +To allow the user to discover such grouping, and to support arbitrary +hierarchy of machines/cores/processes, MI introduces the concept of a +@dfn{thread group}. Thread group is a collection of threads and other +thread groups. A thread group always has a string identifier, a type, +and may have additional attributes specific to the type. A new +command, @code{-list-thread-groups}, returns the list of top-level +thread groups, which correspond to processes that @value{GDBN} is +debugging at the moment. By passing an identifier of a thread group +to the @code{-list-thread-groups} command, it is possible to obtain +the members of specific thread group. + +To allow the user to easily discover processes, and other objects, he +wishes to debug, a concept of @dfn{available thread group} is +introduced. Available thread group is an thread group that +@value{GDBN} is not debugging, but that can be attached to, using the +@code{-target-attach} command. The list of available top-level thread +groups can be obtained using @samp{-list-thread-groups --available}. +In general, the content of a thread group may be only retrieved only +after attaching to that thread group. + @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Command Syntax @section @sc{gdb/mi} Command Syntax @@ -19206,6 +19382,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 @@ -19298,7 +19475,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: @@ -19330,10 +19507,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 @@ -19349,6 +19543,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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -20235,14 +20461,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 @@ -20255,6 +20494,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. @@ -20294,6 +20536,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}. @@ -20336,11 +20581,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 @@ -20412,7 +20666,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 @@ -20421,6 +20675,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}. @@ -21058,6 +21322,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}, @@ -21163,6 +21430,37 @@ visible on the screen, or ``closed''. This is possible using so called ``frozen variable objects''. Such variable objects are never implicitly updated. +Variable objects can be either @dfn{fixed} or @dfn{floating}. For the +fixed variable object, the expression is parsed when the variable +object is created, including associating identifiers to specific +variables. The meaning of expression never changes. For a floating +variable object the values of variables whose names appear in the +expressions are re-evaluated every time in the context of the current +frame. Consider this example: + +@smallexample +void do_work(...) +@{ + struct work_state state; + + if (...) + do_work(...); +@} +@end smallexample + +If a fixed variable object for the @code{state} variable is created in +this function, and we enter the recursive call, the the variable +object will report the value of @code{state} in the top-level +@code{do_work} invocation. On the other hand, a floating variable +object will report the value of @code{state} in the current frame. + +If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +thread and frame in which the variable object is created. When such +variable object is updated, @value{GDBN} makes sure that the +thread/frame combination the variable object is bound to still exists, +and re-evaluates the variable object in context of that thread/frame. + The following is the complete set of @sc{gdb/mi} operations defined to access this functionality: @@ -21212,7 +21510,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 @@ -21222,12 +21520,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: @@ -21247,10 +21546,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 @@ -21525,6 +21825,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 @@ -22583,10 +22886,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 @@ -22628,11 +22934,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 @@ -23180,6 +23487,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 -- 2.30.2