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