From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 29E943882055 for ; Mon, 5 Jun 2023 15:53:19 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 29E943882055 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1685980398; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=4KEhKM8irXkKyA3ykoq3+cnyXiLeOx5Ubx1/Nu6Vc+k=; b=ILxbysyRGk2rVHZLTpA3tCiDiRlAbZeJLTF6Rkenq/ePP5cJV4OrLmCCLmFSn+b+uBj+Wy t4wOvUsRvx+D385UuWNK8I2eXZ8IM8/Np7JcNfSxEVhy5lTwPU6B/cPxCtviv1ffGOhWN0 eFS1w4XVnrKE2EJLR0kYhGqfmF8A6l4= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-562-q-9-4khZMtyZJaK6MwJfjA-1; Mon, 05 Jun 2023 11:53:17 -0400 X-MC-Unique: q-9-4khZMtyZJaK6MwJfjA-1 Received: by mail-wm1-f71.google.com with SMTP id 5b1f17b1804b1-3f6038dc351so21212245e9.3 for ; Mon, 05 Jun 2023 08:53:17 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1685980396; x=1688572396; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=4KEhKM8irXkKyA3ykoq3+cnyXiLeOx5Ubx1/Nu6Vc+k=; b=agKX7pp2MtoBA2IwyJzfqnLJicS6ChZ7SwtKm31JVJvfZTw51BfmUFmXBTXrN6Qfkv UtlbDzFO85q9RS9fkJ4iXcPmWbH3ymxyWpAt1lgGRS0IkOBZhFR4BMOn0JAwosNAE56j 5crfRbljWKTbt6vo6p9VQ30muLrUR+CYWWglfOFBIam0Xvjq/6c2iCBUSwc70b7Zqlkr 2XjdbqG1zGFJit2G9BXWErCRNzru/Wm1+5aTmjqvXwSDeXCeCZc1UWlhn7lXWT//jFxR zx+5CdfcY2058rMURFLhvlh+Sw495RWy6X7e289TaHvpmH3zIrmXxQDGALl5uvmG8Pht dwog== X-Gm-Message-State: AC+VfDx9dPOtFYGugJZpULQ6OvdNLc5y08GBj8rmrSpq1MxeFAIngpq0 4+sq8EwkRyD0cbbVbuLdCIeAdevV/lIzUYAeyGx5/G+8oNohpA0y+ZbZIzv43Yv0DHO7wR6JWtO tJ0H59HZvtlIuKu9T/Tp/NHnKMp3rug== X-Received: by 2002:a05:6000:4c6:b0:30a:e165:e68e with SMTP id h6-20020a05600004c600b0030ae165e68emr5040647wri.27.1685980396411; Mon, 05 Jun 2023 08:53:16 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ6730w1NIeWSYzhqXJPuQ5sxQ0or+OBd6bX225T7NUk5qQhhqBYy+Ua70Ykq8M0A/Kk7rLPWw== X-Received: by 2002:a05:6000:4c6:b0:30a:e165:e68e with SMTP id h6-20020a05600004c600b0030ae165e68emr5040634wri.27.1685980396048; Mon, 05 Jun 2023 08:53:16 -0700 (PDT) Received: from localhost (11.72.115.87.dyn.plus.net. [87.115.72.11]) by smtp.gmail.com with ESMTPSA id m4-20020a5d6a04000000b0030aea925fbesm10053558wru.50.2023.06.05.08.53.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 05 Jun 2023 08:53:15 -0700 (PDT) From: Andrew Burgess To: Pedro Alves , gdb-patches@sourceware.org Cc: Eli Zaretskii Subject: Re: [PATCH 28/31] Document remote clone events, and QThreadOptions packet In-Reply-To: <20221212203101.1034916-29-pedro@palves.net> References: <20221212203101.1034916-1-pedro@palves.net> <20221212203101.1034916-29-pedro@palves.net> Date: Mon, 05 Jun 2023 16:53:14 +0100 Message-ID: <87ttvl3nyt.fsf@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-11.7 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_NONE,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Pedro Alves 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 > 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. Thanks, Andrew > + > +@table @code > +@item GDB_THREAD_OPTION_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_THREAD_OPTION_EXIT (0x2) > +Report thread exit events (@pxref{thread exit event}). > +@end table > + > +@noindent > + > +For example, @value{GDBN} enables the @code{GDB_THREAD_OPTION_EXIT} > +and @code{GDB_THREAD_OPTION_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_THREAD_OPTION_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_THREAD_OPTION_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 > @@ -43336,6 +43445,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{-} > @@ -43557,6 +43671,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