From: Pedro Alves <pedro@palves.net>
To: gdb-patches@sourceware.org
Subject: [PATCH v2 26/29] Document remote clone events, and QThreadOptions packet
Date: Wed, 13 Jul 2022 23:24:30 +0100 [thread overview]
Message-ID: <20220713222433.374898-27-pedro@palves.net> (raw)
In-Reply-To: <20220713222433.374898-1-pedro@palves.net>
This commit documents in both manual and NEWS:
- the new remote clone event stop reply,
- the new QThreadOptions packet and its current defined options,
- the associated "set/show remote thread-events-packet" command,
- and the associated QThreadOptions qSupported feature.
Change-Id: Ic1c8de1fefba95729bbd242969284265de42427e
---
gdb/NEWS | 19 +++++++
gdb/doc/gdb.texinfo | 126 ++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 142 insertions(+), 3 deletions(-)
diff --git a/gdb/NEWS b/gdb/NEWS
index f0f6990dc59..41d3f4d3f5c 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -88,6 +88,10 @@ show style disassembler symbol
The 'disassembler address' and 'disassembler symbol' styles are
aliases for the 'address' and 'function' styles respectively.
+set remote thread-options-packet
+show remote thread-options-packet
+ Set/show the use of the thread options packet.
+
* Changed commands
maintenance info line-table
@@ -160,6 +164,21 @@ GNU/Linux/LoongArch (gdbserver) loongarch*-*-linux*
** GDBserver is now supported on LoongArch GNU/Linux.
+* New remote packets
+
+New stop reason: clone
+ Indicates that a clone system call was executed.
+
+QThreadOptions
+ Enable/disable optional event reporting, on a per-thread basis.
+ Currently supported options are GDB_TO_CLONE, to enable clone event
+ reporting, and GDB_TO_EXIT to enable thread exit event reporting.
+
+QThreadOptions in qSupported
+ The qSupported packet allows GDB to inform the stub it supports the
+ QThreadOptions packet, and the qSupported response can contain the
+ set of thread options the remote stub supports.
+
*** Changes in GDB 12
* DBX mode is deprecated, and will be removed in GDB 13
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a15ef0ed0db..ed86632830e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23940,6 +23940,10 @@ are:
@tab @code{QThreadEvents}
@tab Tracking thread lifetime.
+@item @code{thread-options}
+@tab @code{QThreadOptions}
+@tab Set thread event reporting options.
+
@item @code{no-resumed-stop-reply}
@tab @code{no resumed thread left stop reply}
@tab Tracking thread lifetime.
@@ -41815,6 +41819,17 @@ appropriate @samp{qSupported} feature (@pxref{qSupported}). The
remote stub must also supply the appropriate @samp{qSupported} feature
indicating support.
+@cindex thread clone events, remote reply
+@anchor{thread clone event}
+@item clone
+The packet indicates that @code{clone} was called, and @var{r} is the
+thread ID of the new child thread, as specified in @ref{thread-id
+syntax}. This packet is only applicable to targets that support clone
+events.
+
+This packet should not be sent by default; @value{GDBN} requests it
+with the @ref{QThreadOptions} packet.
+
@cindex thread create event, remote reply
@anchor{thread create event}
@item create
@@ -41853,9 +41868,10 @@ hex strings.
@item w @var{AA} ; @var{tid}
The thread exited, and @var{AA} is the exit status. This response
-should not be sent by default; @value{GDBN} requests it with the
-@ref{QThreadEvents} packet. See also @ref{thread create event} above.
-@var{AA} is formatted as a big-endian hex string.
+should not be sent by default; @value{GDBN} requests it with either
+the @ref{QThreadEvents} or @ref{QThreadOptions} packets. See also
+@ref{thread create event} above. @var{AA} is formatted as a
+big-endian hex string.
@item N
There are no resumed threads left in the target. In other words, even
@@ -42580,6 +42596,11 @@ same thread. @value{GDBN} does not enable this feature unless the
stub reports that it supports it by including @samp{QThreadEvents+} in
its @samp{qSupported} reply.
+This packet always enables/disables event reporting for all threads of
+all processes under control of the remote stub. For per-thread
+control of optional event reporting, see the @ref{QThreadOptions}
+packet.
+
Reply:
@table @samp
@item OK
@@ -42596,6 +42617,93 @@ the stub.
Use of this packet is controlled by the @code{set remote thread-events}
command (@pxref{Remote Configuration, set remote thread-events}).
+@anchor{QThreadOptions}
+@item QThreadOptions@r{[};@var{options}@r{[}:@var{thread-id}@r{]]}@dots{}
+@cindex thread options, remote request
+@cindex @samp{QThreadOptions} packet
+
+For each inferior thread, the last @var{options} in the list with a
+matching @var{thread-id} are applied. Any options previously set on a
+thread are discarded and replaced by the new options specified.
+Threads that do not match any @var{thread-id} retain their
+previously-set options. Thread IDs are specified using the syntax
+described in @ref{thread-id syntax}. If multiprocess extensions
+(@pxref{multiprocess extensions}) are supported, options can be
+specified to apply to all threads of a process by using the
+@samp{p@var{pid}.-1} form of @var{thread-id}. Options with no
+@var{thread-id} apply to all threads. Specifying no options is an
+error.
+
+@var{options} is the bitwise @code{OR} of the following values. All
+values are given in hexadecimal representation.
+
+@table @code
+@item GDB_TO_CLONE (0x1)
+Report thread clone events (@pxref{thread clone event}). This is only
+meaningful for targets that support clone events (e.g., GNU/Linux
+systems).
+
+@item GDB_TO_EXIT (0x2)
+Report thread exit events (@pxref{thread exit event}).
+@end table
+
+@noindent
+
+For example, @value{GDBN} enables the @code{GDB_TO_EXIT} and
+@code{GDB_TO_CLONE} options when single-stepping a thread past a
+breakpoint, for the following reasons:
+
+@itemize @bullet
+@item
+If the single-stepped thread exits (e.g., it executes a thread exit
+system call), enabling @code{GDB_TO_EXIT} prevents @value{GDBN} from
+waiting forever, not knowing that it should no longer expect a stop for
+that same thread, and blocking other threads from progressing.
+
+@item
+If the single-stepped thread spawns a new clone child (i.e., it
+executes a clone system call), enabling @code{GDB_TO_CLONE} halts the
+cloned thread before it executes any instructions, and thus prevents
+the following problematic situations:
+
+@itemize @minus
+@item
+If the breakpoint is stepped-over in-line, the spawned thread would
+incorrectly run free while the breakpoint being stepped over is not
+inserted, and thus the cloned thread may potentially run past the
+breakpoint without stopping for it;
+
+@item
+If displaced (out-of-line) stepping is used, the cloned thread starts
+running at the out-of-line PC, leading to undefined behavior, usually
+crashing or corrupting data.
+@end itemize
+
+@end itemize
+
+New threads start with thread options cleared.
+
+@value{GDBN} does not enable this feature unless the stub reports that
+it supports it by including
+@samp{QThreadOptions=@var{supported_options}} in its @samp{qSupported}
+reply.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. The error number @var{nn} is given as hex digits.
+
+@item @w{}
+An empty reply indicates that @samp{QThreadOptions} is not supported by
+the stub.
+@end table
+
+Use of this packet is controlled by the @code{set remote thread-options}
+command (@pxref{Remote Configuration, set remote thread-options}).
+
@item qRcmd,@var{command}
@cindex execute remote command, remote request
@cindex @samp{qRcmd} packet
@@ -43041,6 +43149,11 @@ These are the currently defined stub features and their properties:
@tab @samp{-}
@tab No
+@item @samp{QThreadOptions}
+@tab Yes
+@tab @samp{-}
+@tab No
+
@item @samp{no-resumed}
@tab No
@tab @samp{-}
@@ -43262,6 +43375,13 @@ The remote stub reports the supported actions in the reply to
@item QThreadEvents
The remote stub understands the @samp{QThreadEvents} packet.
+@item QThreadOptions=@var{supported_options}
+The remote stub understands the @samp{QThreadOptions} packet.
+@var{supported_options} indicates the set of thread options the remote
+stub supports. @var{supported_options} has the same format as the
+@var{options} parameter of the @code{QThreadOptions} packet, described
+at @ref{QThreadOptions}.
+
@item no-resumed
The remote stub reports the @samp{N} stop reply.
--
2.36.0
next prev parent reply other threads:[~2022-07-13 22:25 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-13 22:24 [PATCH v2 00/29] Step over thread clone and thread exit Pedro Alves
2022-07-13 22:24 ` [PATCH v2 01/29] displaced step: pass down target_waitstatus instead of gdb_signal Pedro Alves
2022-07-20 20:21 ` Simon Marchi
2022-07-13 22:24 ` [PATCH v2 02/29] linux-nat: introduce pending_status_str Pedro Alves
2022-07-20 20:38 ` Simon Marchi
2022-07-13 22:24 ` [PATCH v2 03/29] gdb/linux: Delete all other LWPs immediately on ptrace exec event Pedro Alves
2022-07-21 0:45 ` Simon Marchi
2022-07-13 22:24 ` [PATCH v2 04/29] Step over clone syscall w/ breakpoint, TARGET_WAITKIND_THREAD_CLONED Pedro Alves
2022-07-21 1:35 ` Simon Marchi
2022-10-17 18:54 ` Pedro Alves
2022-10-18 12:40 ` [PATCH] Don't explicitly set clone child ptrace options (was: Re: [PATCH v2 04/29] Step over clone syscall w/ breakpoint, TARGET_WAITKIND_THREAD_CLONED) Pedro Alves
2022-10-28 14:50 ` Simon Marchi
2022-12-12 20:13 ` [PATCH v2 04/29] Step over clone syscall w/ breakpoint, TARGET_WAITKIND_THREAD_CLONED Pedro Alves
2022-07-13 22:24 ` [PATCH v2 05/29] Support clone events in the remote protocol Pedro Alves
2022-07-21 2:25 ` Simon Marchi
2022-12-12 20:14 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 06/29] Avoid duplicate QThreadEvents packets Pedro Alves
2022-07-21 2:30 ` Simon Marchi
2022-12-12 20:14 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 07/29] Thread options & clone events (core + remote) Pedro Alves
2022-07-21 3:14 ` Simon Marchi
2022-10-27 19:55 ` [PATCH] enum_flags to_string (was: Re: [PATCH v2 07/29] Thread options & clone events (core + remote)) Pedro Alves
2022-10-28 10:26 ` [PATCH v2] " Pedro Alves
2022-10-28 11:08 ` [PATCH v3] " Pedro Alves
2022-10-28 15:59 ` Simon Marchi
2022-10-28 18:23 ` Pedro Alves
2022-10-31 12:47 ` Simon Marchi
2022-11-07 17:26 ` [PATCH v5] " Pedro Alves
2022-11-07 18:29 ` Simon Marchi
2022-11-08 14:56 ` Pedro Alves
2022-12-12 20:15 ` [PATCH v2 07/29] Thread options & clone events (core + remote) Pedro Alves
2022-07-13 22:24 ` [PATCH v2 08/29] Thread options & clone events (native Linux) Pedro Alves
2022-07-21 12:38 ` Simon Marchi
2022-12-12 20:16 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 09/29] Thread options & clone events (Linux GDBserver) Pedro Alves
2022-07-21 13:11 ` Simon Marchi
2022-12-12 20:16 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 10/29] gdbserver: Hide and don't detach pending clone children Pedro Alves
2022-07-13 22:24 ` [PATCH v2 11/29] Remove gdb/19675 kfails (displaced stepping + clone) Pedro Alves
2022-07-13 22:24 ` [PATCH v2 12/29] Add test for stepping over clone syscall Pedro Alves
2022-07-13 22:24 ` [PATCH v2 13/29] all-stop/synchronous RSP support thread-exit events Pedro Alves
2022-07-13 22:24 ` [PATCH v2 14/29] gdbserver/linux-low.cc: Ignore event_ptid if TARGET_WAITKIND_IGNORE Pedro Alves
2022-07-13 22:24 ` [PATCH v2 15/29] Introduce GDB_TO_EXIT thread option, fix step-over-thread-exit Pedro Alves
2022-07-13 22:24 ` [PATCH v2 16/29] Implement GDB_TO_EXIT support for Linux GDBserver Pedro Alves
2022-07-13 22:24 ` [PATCH v2 17/29] Implement GDB_TO_EXIT support for native Linux Pedro Alves
2022-07-21 15:26 ` Simon Marchi
2022-12-12 20:17 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 18/29] gdb: clear step over information on thread exit (PR gdb/27338) Pedro Alves
2022-07-21 18:12 ` Simon Marchi
2022-12-12 20:18 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 19/29] stop_all_threads: (re-)enable async before waiting for stops Pedro Alves
2022-07-21 18:21 ` Simon Marchi
2022-12-12 20:18 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 20/29] gdbserver: Queue no-resumed event after thread exit Pedro Alves
2022-07-13 22:24 ` [PATCH v2 21/29] Don't resume new threads if scheduler-locking is in effect Pedro Alves
2022-07-14 5:28 ` Eli Zaretskii
2022-07-21 18:49 ` Simon Marchi
2022-12-12 20:19 ` Pedro Alves
2022-07-13 22:24 ` [PATCH v2 22/29] Report thread exit event for leader if reporting thread exit events Pedro Alves
2022-07-13 22:24 ` [PATCH v2 23/29] Ignore failure to read PC when resuming Pedro Alves
2022-07-13 22:24 ` [PATCH v2 24/29] gdb/testsuite/lib/my-syscalls.S: Refactor new SYSCALL macro Pedro Alves
2022-07-13 22:24 ` [PATCH v2 25/29] Testcases for stepping over thread exit syscall (PR gdb/27338) Pedro Alves
2022-07-13 22:24 ` Pedro Alves [this message]
2022-07-14 5:27 ` [PATCH v2 26/29] Document remote clone events, and QThreadOptions packet Eli Zaretskii
2022-07-13 22:24 ` [PATCH v2 27/29] inferior::clear_thread_list always silent Pedro Alves
2022-07-13 22:24 ` [PATCH v2 28/29] Centralize "[Thread ...exited]" notifications Pedro Alves
2022-07-13 22:24 ` [PATCH v2 29/29] Cancel execution command on thread exit, when stepping, nexting, etc Pedro Alves
2022-07-21 19:28 ` [PATCH v2 00/29] Step over thread clone and thread exit Simon Marchi
2022-10-03 13:46 ` Tom de Vries
2022-10-03 18:37 ` Tom de Vries
2022-12-12 20:20 ` Pedro Alves
2022-12-12 20:19 ` Pedro Alves
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220713222433.374898-27-pedro@palves.net \
--to=pedro@palves.net \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).