[PATCH 25/25] Document remote clone events, and QThreadOptions packet

[Pedro Alves <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 | 130 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 146 insertions(+), 3 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 2e842cb00f9..f7aeb8882cd 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -44,6 +44,10 @@ show print nibbles
   This controls whether the 'print/t' command will display binary values
   in groups of four bits, known as "nibbles".  The default is 'off'.
 
+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
@@ -113,6 +117,21 @@ GNU/Linux/LoongArch (gdbserver)	loongarch*-*-linux*
 
   ** GDBserver is now supported on LoongArch GNU/Linux.
 
+* New remote packets
+
+clone stop reason
+  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 775c4b1347b..d0266256874 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23906,6 +23906,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.
@@ -41687,6 +41691,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.  Refer to @ref{thread-id syntax}
+for the format of the @var{thread-id} field.  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
@@ -41725,9 +41740,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
@@ -42452,6 +42468,10 @@ 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 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
@@ -42468,6 +42488,98 @@ 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 rightmost options 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
+Without exit events, if the single-stepped thread exits (e.g., it
+executes a thread exit system call), @value{GDBN} would wait forever
+not knowing that it should no longer expect a stop for that same
+thread, blocking other threads from progressing.
+
+@item
+Without clone events (on systems where threads are spawned via a clone
+system call), if the single-stepped thread spawns a new clone child
+(i.e., it executes a clone system call), and:
+
+@itemize @minus
+@item
+the breakpoint is stepped-over in-line, the spawned thread incorrectly
+runs free while the breakpoint being stepped over is not inserted,
+thus the spawned thread may potentially run past the breakpoint
+without stopping for it.  By enabling @code{GDB_TO_CLONE}, the new
+cloned thread is halted before it executes any instruction;
+
+@item
+if alternativelly displaced (out-of-line) stepping is used, the
+spawned thread starts running at the out-of-line PC, leading to
+undefined behavior, usually crashes or data corruption.  By enabling
+@code{GDB_TO_CLONE}, the new cloned thread is halted before it
+executes any instruction, and @value{GDBN} adjusts its PC before
+resuming its execution.
+@end itemize
+
+@end itemize
+
+On targets that support fork, vfork, and/or clone events (e.g.,
+GNU/Linux systems), fork, vfork, and clone children threads inherit
+their parent's thread options.  Otherwise, 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
@@ -42913,6 +43025,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{-}
@@ -43134,6 +43251,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