diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index e902177..a29c0d4 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -18863,7 +18863,7 @@ The important examples of notifications are: @itemize @bullet @item -Exec notifications. These are used to report changes in +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 @@ -18872,16 +18872,16 @@ 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 +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 +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, +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. @@ -18909,15 +18909,15 @@ to what thread and frame are the current ones. In the case of MI, the concept of selected thread and frame is less useful. First, a frontend can easily remember this information -itself. Second, a graphical frontend can have more than one window, each -one used for debugging a different thread, and the frontend might -want to access additional threads for internal purposes. -This increases the risk that by relying on implicitly selected thread, the -frontend may be operating on a wrong one. Therefore, it is -preferrable that each MI command explicitly specify which thread and -frame to operate on. To make it possible, each MI command accepts the -@samp{--thread} and @samp{--frame} options, the value to each is -@value{GDBN} identifier for thread and frame to operate on. +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 @@ -18932,7 +18932,7 @@ 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 +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} @@ -18951,41 +18951,35 @@ right, so it is suggested to just always pass the @samp{--thread} and On some targets, @value{GDBN} is capable of processing MI commands even while the target is running. This is called @dfn{asynchronous -command execution}. The frontend may specify a preferrence for -asynchronous execution using the @code{-gdb-set target-async 1} -command, which should be emitted before either running the executable -or attaching to the target. After the frontend has started the -executable or attached to the target, it can find if asynchronous -execution is enabled using the @code{-list-target-features} command. +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, +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 +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or modify breakpoints, may work or not work, depending on the target. Note that even commands that operate on global state (like global variables, or breakpoints), still access the target in the context of -a specific thread, so frontend should try perform such operations on a -stopped thread. +a specific thread, so frontend should try to find a stopped thread and +perform the operation on that thread (using the @samp{--thread} option). -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. +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. @@ -19005,9 +18999,9 @@ 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 +@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 +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 @@ -21399,12 +21393,11 @@ object will report the value of @code{state} in the top-level object will report the value of @code{state} in the current frame. If an expression specified when creating a fixed variable object -refers to a local variable, the variable object becomes bound to the -frame the local variable belongs to. For multithreaded programs, the -variable object also becomes bound to the thread. When such variable -object is updated, @value{GDBN} makes sure that the thread/frame -combination the variable object is bound to still exists, and -re-evaluates the variable object in context of that thread/frame. +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: @@ -23443,8 +23436,8 @@ while the target is running. 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, +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.