From patchwork Mon Nov 13 15:04:26 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pedro Alves X-Patchwork-Id: 79769 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id A445D394D827 for ; Mon, 13 Nov 2023 15:09:06 +0000 (GMT) X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org Received: from mail-wr1-f45.google.com (mail-wr1-f45.google.com [209.85.221.45]) by sourceware.org (Postfix) with ESMTPS id 826AE3858039 for ; Mon, 13 Nov 2023 15:06:11 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 826AE3858039 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=palves.net Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 826AE3858039 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=209.85.221.45 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699887973; cv=none; b=V7qJHkHfyh4Z3d5oq2nhBCCakRXNNuub+ReRzyX/TbPbdUownwu+DJrFqP0yYPN+pVJsKCJ5YsDkm9v+34H717lDGkRoO6kyc3WLxLVRv0BtiQN2u4CQkCuVGoz082r5tnDbYmPYwJjDaE5SnECMnVhSE6Vu/p9/fgpSRC/uzlk= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699887973; c=relaxed/simple; bh=uv+li5nY8KwKIdwHl5epiXVgFm+kgOPL7sE7Up+6PyY=; h=From:To:Subject:Date:Message-Id:MIME-Version; b=tfBc1hBHoUjWxN+GXvqic4DvDTxTAP2S4K/MsR1liV7XcgVh0bCwsWDrRJT3st6WopXhzre8Z6xH/tjolwrahKRQsSodj2e9JdLuCo6ehscs5WHBiBXEuxDyBxEm6IRV8caa8gNc5XLq5lOqfHCo64Jv3J1nw+xeLZKflOI2R7A= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-wr1-f45.google.com with SMTP id ffacd0b85a97d-32fb190bf9bso3281135f8f.1 for ; Mon, 13 Nov 2023 07:06:11 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1699887970; x=1700492770; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=/jrj4yXC02xJsZG6VAkK0Bf8FmZk9sglYjEyy6nhCBA=; b=VIAOeSzagp6uDpMgGO5sASsJxhrUG6DINXs6vBWacWl1QkHRaOHhlpUtiw0R4KJjGd /0Z+jcvxsRAacON7/QtAkP0Jj8OL5i5+8X9qdclKlYAubHD7JcLakezVmRyeHpiJ4wOx M8VHiBi34gJrruW/TMMivtPaJ72+Vdtu7jLOquVTyljoOVb7UBN5yqkuVMynReeV4NZJ 8QSNGwUEzKm0ldDKsWGfnOBrStl5QEM/kXHd3aDm4BMJ18+X+hm9Up3BvOUltnIeKwDJ PRx5IH3fD4JKVgJPCpm3KPIk9eNz71jdW95ZgxCRC8i1lTr0IIjVbq+miUNqDNydu6HB 2RFA== X-Gm-Message-State: AOJu0YzvyOc0CbLWH9C8mTA2wS4WA58xHV/qu8Y/GktAXvj0YJakS50Q bQMmoidp1HpfL89thuAIlHrF/Kq7ITQ= X-Google-Smtp-Source: AGHT+IGqnysBN5k+RtyY8i9bt+lCaaFLnJkuqYsFu+nU+gIDGkoTDeX9gm8o1AxNKLTa1h13FWPTRQ== X-Received: by 2002:a05:6000:1e18:b0:32f:7502:fba9 with SMTP id bj24-20020a0560001e1800b0032f7502fba9mr11783737wrb.1.1699887969822; Mon, 13 Nov 2023 07:06:09 -0800 (PST) Received: from localhost ([2001:8a0:f91e:1a00:8060:1e54:fb28:9635]) by smtp.gmail.com with UTF8SMTPSA id t16-20020adfe450000000b0032dbf6bf7a2sm5600701wrm.97.2023.11.13.07.06.09 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 13 Nov 2023 07:06:09 -0800 (PST) From: Pedro Alves To: gdb-patches@sourceware.org Cc: Eli Zaretskii Subject: [FYI/pushed v4 24/25] Document remote clone events, and QThreadOptions packet Date: Mon, 13 Nov 2023 15:04:26 +0000 Message-Id: <20231113150427.477431-25-pedro@palves.net> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231113150427.477431-1-pedro@palves.net> References: <20231113150427.477431-1-pedro@palves.net> MIME-Version: 1.0 X-Spam-Status: No, score=-10.2 required=5.0 tests=BAYES_00, FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_PASS, 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 X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org 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 | 128 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 145 insertions(+), 3 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index f2861b1ace1..682def44ce0 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -29,6 +29,26 @@ disassemble maintenance info linux-lwps List all LWPs under control of the linux-nat target. +set remote thread-options-packet +show remote thread-options-packet + Set/show the use of the thread options packet. + +* 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 14 * GDB now supports the AArch64 Scalable Matrix Extension 2 (SME2), which diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 79b7431dd78..e4c00143fd1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -24356,6 +24356,10 @@ future connections is shown. The available settings 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. @@ -43280,6 +43284,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 @@ -43318,9 +43333,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 @@ -44045,6 +44061,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 @@ -44061,6 +44082,95 @@ 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 value is +an error. Zero is a valid value. + +@var{options} is an hexadecimal integer specifying the enabled thread +options, and is the bitwise @code{OR} of the following values. All +values are given in hexadecimal representation. + +@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 @@ -44506,6 +44616,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{-} @@ -44727,6 +44842,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.