Re: [PATCH 28/31] Document remote clone events, and QThreadOptions packet

[Pedro Alves <pedro@palves.net>]

On 2023-06-05 16:53, Andrew Burgess wrote:
> Pedro Alves <pedro@palves.net> writes:
> 
>> 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.
>>
>> Approved-By: Eli Zaretskii <eliz@gnu.org>
>> Change-Id: Ic1c8de1fefba95729bbd242969284265de42427e
>> ---
>>  gdb/NEWS            |  20 +++++++
>>  gdb/doc/gdb.texinfo | 127 ++++++++++++++++++++++++++++++++++++++++++--
>>  2 files changed, 144 insertions(+), 3 deletions(-)
>>
>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index 0aa153b83da..b1d3dd7e7d9 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>> @@ -160,6 +160,10 @@ set style tui-current-position [on|off]
>>    Whether to style the source and assembly code highlighted by the
>>    TUI's current position indicator.  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
>>  
>>  document user-defined
>> @@ -285,6 +289,22 @@ GNU/Linux/CSKY (gdbserver) csky*-*linux*
>>  
>>  GDB now supports floating-point 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_THREAD_OPTION_CLONE, to enable
>> +  clone event reporting, and GDB_THREAD_OPTION_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 5e75f32e0cd..ef62fac366f 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -24079,6 +24079,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.
>> @@ -42110,6 +42114,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
>> @@ -42148,9 +42163,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
>> @@ -42875,6 +42891,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
>> @@ -42891,6 +42912,94 @@ 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.
> 
> I think it is implied, but would be must better explicitly stated, that
> it is valid to send 0 in order to clear all options.
> 

I did the following tweak, put here because that's where I felt the text
could be ambiguous otherwise (as in: 'is "no options" the same as zero?' kind
of ambiguous):

@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{thread-id} apply to all threads.  Specifying no options value is
+an error.  Zero is a valid value.