This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[PATCH 2/2] doc: Improve documentation about MI thread output
- From: Simon Marchi <simon dot marchi at ericsson dot com>
- To: <gdb-patches at sourceware dot org>
- Cc: Simon Marchi <simon dot marchi at ericsson dot com>
- Date: Wed, 12 Apr 2017 14:06:10 -0400
- Subject: [PATCH 2/2] doc: Improve documentation about MI thread output
- Authentication-results: sourceware.org; auth=none
- Authentication-results: sourceware.org; dkim=none (message not signed) header.d=none;sourceware.org; dmarc=none action=none header.from=ericsson.com;
- References: <20170412180610.2565-1-simon.marchi@ericsson.com>
- Spamdiagnosticmetadata: NSPM
- Spamdiagnosticoutput: 1:99
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/gdb.texinfo | 71 ++++++++++++++++++++---------------------------------
1 file changed, 26 insertions(+), 45 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9e872763b2..b7a5d1bea7 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,17 @@ 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 threads
+A list of threads. The format of the elements of the list is described in
+@ref{GDB/MI Thread Information}.
-@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 current-thread-id
+The global id of the current selected thread. This field is only present if
+there is a selected thread and no @var{thread-id} argument was passed to the
+command..
@end table
--
2.11.0