From ebe553db6c639d7533650f8482d611109c2f98a9 Mon Sep 17 00:00:00 2001 From: Simon Marchi Date: Fri, 21 Apr 2017 21:50:22 -0400 Subject: [PATCH] doc: Improve documentation about MI thread output I noticed that the documentation on how the info about threads is output in MI is duplicated and not up to date. The duplication is between the "GDB/MI Thread Information" page and the -thread-info result description. I improved the "GDB/MI Thread Information" page a bit and referred to it in the -thread-info doc. This way, the -thread-info doc is more precise (it did not mention the "threads" and "current-thread-id" attributes) and concise. gdb/doc/ChangeLog: * gdb.texinfo (GDB/MI Thread Information): Add missing fields, re-word some things. (GDB/MI Thread Commands): Describe fields found in the output of -thread-info, remove description of fields in the thread output tuple, replace with a cross-reference to "GDB/MI Thread Information". --- gdb/doc/ChangeLog | 9 ++++++ gdb/doc/gdb.texinfo | 74 +++++++++++++++++---------------------------- 2 files changed, 37 insertions(+), 46 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index efce1c0a11..9be035c892 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,12 @@ +2017-04-21 Simon Marchi + + * gdb.texinfo (GDB/MI Thread Information): Add missing + fields, re-word some things. + (GDB/MI Thread Commands): Describe fields found in the output of + -thread-info, remove description of fields in the + thread output tuple, replace with a cross-reference to "GDB/MI + Thread Information". + 2017-04-21 Simon Marchi * gdb.texinfo (GDB/MI Thread Commands): Remove "current" field diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 9e872763b2..f2e615660e 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -26852,24 +26852,36 @@ corresponds to the frame's code address. This field may be absent. @subsection @sc{gdb/mi} Thread Information Whenever @value{GDBN} has to report an information about a thread, it -uses a tuple with the following fields: +uses a tuple with the following fields. The fields are always present unless +stated otherwise. @table @code @item id -The global numeric id assigned to the thread by @value{GDBN}. This field is -always present. +The global numeric id assigned to the thread by @value{GDBN}. @item target-id -Target-specific string identifying the thread. This field is always present. +The target-specific string identifying the thread. @item details Additional information about the thread provided by the target. It is supposed to be human-readable and not interpreted by the frontend. This field is optional. +@item name +The name of the thread. If the user specified a name using the +@code{thread name} command, then this name is given. Otherwise, if +@value{GDBN} can extract the thread name from the target, then that +name is given. If @value{GDBN} cannot find the thread name, then this +field is omitted. + @item state -Either @samp{stopped} or @samp{running}, depending on whether the -thread is presently running. This field is always present. +The execution state of the thread, either @samp{stopped} or @samp{running}, +depending on whether the thread is presently running. + +@item frame +The stack frame currently executing in the thread. This field is only present +if the thread is stopped. Its format is documented in +@ref{GDB/MI Frame Information}. @item core The value of this field is an integer number of the processor core the @@ -28084,48 +28096,18 @@ about all threads. @subsubheading Result -The result is a list of threads. The following attributes are -defined for a given thread: +The result contains the following attributes: @table @samp -@item id -The global identifier that @value{GDBN} uses to refer to the thread. - -@item target-id -The identifier that the target uses to refer to the thread. - -@item details -Extra information about the thread, in a target-specific format. This -field is optional. - -@item name -The name of the thread. If the user specified a name using the -@code{thread name} command, then this name is given. Otherwise, if -@value{GDBN} can extract the thread name from the target, then that -name is given. If @value{GDBN} cannot find the thread name, then this -field is omitted. - -@item frame -The stack frame currently executing in the thread. - -@item state -The thread's state. 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 - -@item core -If @value{GDBN} can find the CPU core on which this thread is running, -then this field is the core identifier. This field is optional. +@item threads +A list of threads. The format of the elements of the list is described in +@ref{GDB/MI Thread Information}. + +@item current-thread-id +The global id of the currently selected thread. This field is omitted if there +is no selected thread (for example, when the selected inferior is not running, +and therefore has no threads) or if a @var{thread-id} argument was passed to +the command. @end table -- 2.34.1