[PATCH] gdb/python: Add gdb.InferiorThread.details attribute

[PATCH] gdb/python: Add gdb.InferiorThread.details attribute

[Andrew Burgess via Gdb-patches]

This adds a new read-only attribute gdb.InferiorThread.details, this
attribute contains a string, the results of target_extra_thread_info
for the thread, or None, if target_extra_thread_info returns nullptr.

As the string returned by target_extra_thread_info is unstructured,
this attribute is only really useful for echoing straight through to
the user, but, if a user wants to write a command that displays the
same, or a similar 'Thread Id' to the one seen in 'info threads', then
they need access to this string.

Given that the string produced by target_extra_thread_info varies by
target, there's only minimal testing of this attribute, I check that
the attribute can be accessed, and that the return value is either
None, or a string.
---
 gdb/NEWS                                  |  5 +++++
 gdb/doc/python.texi                       |  7 +++++++
 gdb/python/py-infthread.c                 | 21 +++++++++++++++++++++
 gdb/testsuite/gdb.python/py-infthread.exp |  5 +++++
 4 files changed, 38 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 9da74e71796..10b5489622c 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -185,6 +185,11 @@ GNU/Linux/LoongArch    loongarch*-*-linux*
      set styling').  When false, which is the default if the argument
      is not given, then no styling is applied to the returned string.
 
+  ** New read-only attribute gdb.InferiorThread.details, which is
+     either a string, containing additional, target specific thread
+     state information, or None, if there is no such additional
+     information.
+
 * New features in the GDB remote stub, GDBserver
 
   ** GDBserver is now supported on OpenRISC GNU/Linux.
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index c1a3f5f2a7e..ac4ebbeaeae 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -3574,6 +3574,13 @@
 a @code{gdb.Inferior} object.  This attribute is not writable.
 @end defvar
 
+@defvar InferiorThread.details
+A string containing target specific, thread state information.  The
+format of this string varies by target.  If there is no additional
+state information for this thread, then this attribute contains
+@code{None}.
+@end defvar
+
 A @code{gdb.InferiorThread} object has the following methods:
 
 @defun InferiorThread.is_valid ()
diff --git a/gdb/python/py-infthread.c b/gdb/python/py-infthread.c
index e568d8d916e..efd536688c1 100644
--- a/gdb/python/py-infthread.c
+++ b/gdb/python/py-infthread.c
@@ -76,6 +76,24 @@ thpy_get_name (PyObject *self, void *ignore)
   return PyString_FromString (name);
 }
 
+/* Return a string containing target specific additional information about
+   the state of the thread, or None, if there is no such additional
+   information.  */
+
+static PyObject *
+thpy_get_details (PyObject *self, void *ignore)
+{
+  thread_object *thread_obj = (thread_object *) self;
+
+  THPY_REQUIRE_VALID (thread_obj);
+
+  const char *extra_info = target_extra_thread_info (thread_obj->thread);
+  if (extra_info == nullptr)
+    Py_RETURN_NONE;
+
+  return PyString_FromString (extra_info);
+}
+
 static int
 thpy_set_name (PyObject *self, PyObject *newvalue, void *ignore)
 {
@@ -347,6 +365,9 @@ static gdb_PyGetSetDef thread_object_getset[] =
 {
   { "name", thpy_get_name, thpy_set_name,
     "The name of the thread, as set by the user or the OS.", NULL },
+  { "details", thpy_get_details, NULL,
+    "A target specific string containing extra thread state details.",
+    NULL },
   { "num", thpy_get_num, NULL,
     "Per-inferior number of the thread, as assigned by GDB.", NULL },
   { "global_num", thpy_get_global_num, NULL,
diff --git a/gdb/testsuite/gdb.python/py-infthread.exp b/gdb/testsuite/gdb.python/py-infthread.exp
index 5cbbe43c44c..a7754198e60 100644
--- a/gdb/testsuite/gdb.python/py-infthread.exp
+++ b/gdb/testsuite/gdb.python/py-infthread.exp
@@ -77,6 +77,11 @@ gdb_py_test_silent_cmd "python gdb.selected_thread().name = None" \
 gdb_test "python print (gdb.selected_thread().name == name)" "True" \
     "check name of current thread again"
 
+gdb_test_no_output "python details = gdb.selected_thread().details" \
+    "record the thread details string"
+gdb_test "python print(details is None or isinstance(details, str))" "True" \
+    "check that the details has an acceptable type"
+
 gdb_test "python print ('result = %s' % t0.is_stopped ())" " = True" "test InferiorThread.is_stopped"
 gdb_test "python print ('result = %s' % t0.is_running ())" " = False" "test InferiorThread.is_running"
 gdb_test "python print ('result = %s' % t0.is_exited ())" " = False" "test InferiorThread.is_exited"
-- 
2.25.4

Re: [PATCH] gdb/python: Add gdb.InferiorThread.details attribute

[Tom Tromey]

>>>>> "Andrew" == Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org> writes:

Andrew> As the string returned by target_extra_thread_info is unstructured,
Andrew> this attribute is only really useful for echoing straight through to
Andrew> the user, but, if a user wants to write a command that displays the
Andrew> same, or a similar 'Thread Id' to the one seen in 'info threads', then
Andrew> they need access to this string.

It may be good to give a bit more information about this in the
documentation.  Like, describing what this is used for and maybe how it
would appear on a Linux system.

Andrew> +  const char *extra_info = target_extra_thread_info (thread_obj->thread);

If this can ever throw, it will break things here.

Tom

[PATCHv2] gdb/python: Add gdb.InferiorThread.details attribute

[Andrew Burgess via Gdb-patches]

* Tom Tromey <tom@tromey.com> [2022-02-25 12:33:42 -0700]:

> >>>>> "Andrew" == Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org> writes:
> 
> Andrew> As the string returned by target_extra_thread_info is unstructured,
> Andrew> this attribute is only really useful for echoing straight through to
> Andrew> the user, but, if a user wants to write a command that displays the
> Andrew> same, or a similar 'Thread Id' to the one seen in 'info threads', then
> Andrew> they need access to this string.
> 
> It may be good to give a bit more information about this in the
> documentation.  Like, describing what this is used for and maybe how it
> would appear on a Linux system.
> 
> Andrew> +  const char *extra_info = target_extra_thread_info (thread_obj->thread);
> 
> If this can ever throw, it will break things here.

Thanks for the feedback.  In v2:

  - Improved the docs to given an example of what the string might
    contain, and where GDB currently displays the string, and

  - Use try/catch and GDB_PY_HANDLE_EXCEPTION in py-infthread.c in
    to handle any exceptions thrown from GDB core.

Thanks,
Andrew

---

gdb/python: Add gdb.InferiorThread.details attribute

This adds a new read-only attribute gdb.InferiorThread.details, this
attribute contains a string, the results of target_extra_thread_info
for the thread, or None, if target_extra_thread_info returns nullptr.

As the string returned by target_extra_thread_info is unstructured,
this attribute is only really useful for echoing straight through to
the user, but, if a user wants to write a command that displays the
same, or a similar 'Thread Id' to the one seen in 'info threads', then
they need access to this string.

Given that the string produced by target_extra_thread_info varies by
target, there's only minimal testing of this attribute, I check that
the attribute can be accessed, and that the return value is either
None, or a string.
---
 gdb/NEWS                                  |  5 ++++
 gdb/doc/gdb.texinfo                       |  2 ++
 gdb/doc/python.texi                       | 17 +++++++++++++
 gdb/python/py-infthread.c                 | 29 +++++++++++++++++++++++
 gdb/testsuite/gdb.python/py-infthread.exp |  5 ++++
 5 files changed, 58 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 41ea84e6063..dc2cac1871b 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -201,6 +201,11 @@ GNU/Linux/LoongArch    loongarch*-*-linux*
      set styling').  When false, which is the default if the argument
      is not given, then no styling is applied to the returned string.
 
+  ** New read-only attribute gdb.InferiorThread.details, which is
+     either a string, containing additional, target specific thread
+     state information, or None, if there is no such additional
+     information.
+
 * New features in the GDB remote stub, GDBserver
 
   ** GDBserver is now supported on OpenRISC GNU/Linux.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 504eb663c14..f7f5f7a6158 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3629,6 +3629,7 @@
 @end smallexample
 
 @table @code
+@anchor{info_threads}
 @kindex info threads
 @item info threads @r{[}@var{thread-id-list}@r{]}
 
@@ -42719,6 +42720,7 @@
 
 @xref{Tracepoint Packets}.
 
+@anchor{qThreadExtraInfo}
 @item qThreadExtraInfo,@var{thread-id}
 @cindex thread attributes info, remote request
 @cindex @samp{qThreadExtraInfo} packet
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index c1a3f5f2a7e..e59897dc3f7 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -3574,6 +3574,23 @@
 a @code{gdb.Inferior} object.  This attribute is not writable.
 @end defvar
 
+@defvar InferiorThread.details
+A string containing target specific, thread state information.  The
+format of this string varies by target.  If there is no additional
+state information for this thread, then this attribute contains
+@code{None}.
+
+For example, on a @sc{gnu}/Linux system, a thread that is in the
+process of exiting will return the string @samp{Exiting}.  For remote
+targets the @code{details} string will be obtained with the
+@samp{qThreadExtraInfo} remote packet, if the target supports it
+(@pxref{qThreadExtraInfo,,@samp{qThreadExtraInfo}}).
+
+@value{GDBN} displays the @code{details} string as part of the
+@samp{Target Id} column, in the @code{info threads} output
+(@pxref{info_threads,,@samp{info threads}}).
+@end defvar
+
 A @code{gdb.InferiorThread} object has the following methods:
 
 @defun InferiorThread.is_valid ()
diff --git a/gdb/python/py-infthread.c b/gdb/python/py-infthread.c
index e568d8d916e..66c3efdf6cc 100644
--- a/gdb/python/py-infthread.c
+++ b/gdb/python/py-infthread.c
@@ -76,6 +76,32 @@ thpy_get_name (PyObject *self, void *ignore)
   return PyString_FromString (name);
 }
 
+/* Return a string containing target specific additional information about
+   the state of the thread, or None, if there is no such additional
+   information.  */
+
+static PyObject *
+thpy_get_details (PyObject *self, void *ignore)
+{
+  thread_object *thread_obj = (thread_object *) self;
+
+  THPY_REQUIRE_VALID (thread_obj);
+
+  const char *extra_info;
+  try
+    {
+      extra_info = target_extra_thread_info (thread_obj->thread);
+    }
+  catch (const gdb_exception &except)
+    {
+      GDB_PY_HANDLE_EXCEPTION (except);
+    }
+  if (extra_info == nullptr)
+    Py_RETURN_NONE;
+
+  return PyString_FromString (extra_info);
+}
+
 static int
 thpy_set_name (PyObject *self, PyObject *newvalue, void *ignore)
 {
@@ -347,6 +373,9 @@ static gdb_PyGetSetDef thread_object_getset[] =
 {
   { "name", thpy_get_name, thpy_set_name,
     "The name of the thread, as set by the user or the OS.", NULL },
+  { "details", thpy_get_details, NULL,
+    "A target specific string containing extra thread state details.",
+    NULL },
   { "num", thpy_get_num, NULL,
     "Per-inferior number of the thread, as assigned by GDB.", NULL },
   { "global_num", thpy_get_global_num, NULL,
diff --git a/gdb/testsuite/gdb.python/py-infthread.exp b/gdb/testsuite/gdb.python/py-infthread.exp
index 5cbbe43c44c..a7754198e60 100644
--- a/gdb/testsuite/gdb.python/py-infthread.exp
+++ b/gdb/testsuite/gdb.python/py-infthread.exp
@@ -77,6 +77,11 @@ gdb_py_test_silent_cmd "python gdb.selected_thread().name = None" \
 gdb_test "python print (gdb.selected_thread().name == name)" "True" \
     "check name of current thread again"
 
+gdb_test_no_output "python details = gdb.selected_thread().details" \
+    "record the thread details string"
+gdb_test "python print(details is None or isinstance(details, str))" "True" \
+    "check that the details has an acceptable type"
+
 gdb_test "python print ('result = %s' % t0.is_stopped ())" " = True" "test InferiorThread.is_stopped"
 gdb_test "python print ('result = %s' % t0.is_running ())" " = False" "test InferiorThread.is_running"
 gdb_test "python print ('result = %s' % t0.is_exited ())" " = False" "test InferiorThread.is_exited"
-- 
2.25.4

Re: [PATCHv2] gdb/python: Add gdb.InferiorThread.details attribute

[Eli Zaretskii via Gdb-patches]

> Date: Mon, 28 Feb 2022 11:30:29 +0000
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
> Cc: gdb-patches@sourceware.org
> 
> +@defvar InferiorThread.details
> +A string containing target specific, thread state information.  The
                                      ^
Please remove that stray comma.

The documentation parts are okay with the above fixed, thanks.

Re: [PATCHv2] gdb/python: Add gdb.InferiorThread.details attribute

[Simon Marchi via Gdb-patches]

On 2022-02-28 06:30, Andrew Burgess via Gdb-patches wrote:
> * Tom Tromey <tom@tromey.com> [2022-02-25 12:33:42 -0700]:
> 
>>>>>>> "Andrew" == Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org> writes:
>>
>> Andrew> As the string returned by target_extra_thread_info is unstructured,
>> Andrew> this attribute is only really useful for echoing straight through to
>> Andrew> the user, but, if a user wants to write a command that displays the
>> Andrew> same, or a similar 'Thread Id' to the one seen in 'info threads', then
>> Andrew> they need access to this string.
>>
>> It may be good to give a bit more information about this in the
>> documentation.  Like, describing what this is used for and maybe how it
>> would appear on a Linux system.
>>
>> Andrew> +  const char *extra_info = target_extra_thread_info (thread_obj->thread);
>>
>> If this can ever throw, it will break things here.
> 
> Thanks for the feedback.  In v2:
> 
>   - Improved the docs to given an example of what the string might
>     contain, and where GDB currently displays the string, and
> 
>   - Use try/catch and GDB_PY_HANDLE_EXCEPTION in py-infthread.c in
>     to handle any exceptions thrown from GDB core.
> 
> Thanks,
> Andrew
> 
> ---
> 
> gdb/python: Add gdb.InferiorThread.details attribute
> 
> This adds a new read-only attribute gdb.InferiorThread.details, this
> attribute contains a string, the results of target_extra_thread_info
> for the thread, or None, if target_extra_thread_info returns nullptr.
> 
> As the string returned by target_extra_thread_info is unstructured,
> this attribute is only really useful for echoing straight through to
> the user, but, if a user wants to write a command that displays the
> same, or a similar 'Thread Id' to the one seen in 'info threads', then
> they need access to this string.
> 
> Given that the string produced by target_extra_thread_info varies by
> target, there's only minimal testing of this attribute, I check that
> the attribute can be accessed, and that the return value is either
> None, or a string.

This LGTM, thanks.

Simon