From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id z+UoKwiB82kriQYAWB0awg (envelope-from ) for ; Thu, 30 Apr 2026 12:19:20 -0400 Received: by simark.ca (Postfix, from userid 112) id 9E49B1E067; Thu, 30 Apr 2026 12:19:20 -0400 (EDT) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-25) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-2.3 required=5.0 tests=ARC_SIGNED,ARC_VALID,BAYES_00, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,RCVD_IN_MSPIKE_H2, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED autolearn=ham autolearn_force=no version=4.0.1 Received: from vm01.sourceware.org (vm01.sourceware.org [38.145.34.32]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 625801E067 for ; Thu, 30 Apr 2026 12:19:19 -0400 (EDT) Received: from vm01.sourceware.org (localhost [127.0.0.1]) by sourceware.org (Postfix) with ESMTP id DC3BC43B552A for ; Thu, 30 Apr 2026 16:19:18 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org DC3BC43B552A Received: from mail-wm1-f41.google.com (mail-wm1-f41.google.com [209.85.128.41]) by sourceware.org (Postfix) with ESMTPS id 4F6594BA79AE for ; Thu, 30 Apr 2026 16:18:52 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 4F6594BA79AE 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 4F6594BA79AE Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=209.85.128.41 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1777565932; cv=none; b=aQSpGx/c+LBdza3jFM/rj0U8LvZ+g/wATvOdcyM/TWkloNXJ2lN9fsxs3LDGjrzdygz9dbWmAo1ChK2nWgd8jgRAYWvqzpIme8H8dwOR8zFVGwsfrsbeX5Pfv/lj7FCnumUABYzBdu8468gmY1LDOEDU5esh1fXBHWLqW7f3pmk= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1777565932; c=relaxed/simple; bh=2XxzEH0TMyc/qZmoiKh5VrI+Cy5JP7QhPiazIw9TZ2g=; h=Message-ID:Date:MIME-Version:Subject:To:From; b=ZzWYnZh1sY25rqHmVGk5Swmeex00F/a74nJgG9NOOyZms4upnumxl6a/d+9cfu0yGU42O+m87VPVFCfjJNsUZ9UACanq8qc/t4KQI4EBbUE4pN7ngMNsh4fyRlHNQ6qtDho3gisQ0poVVHyiz0kgGAN6UOG/pm5grMgzCdmm9zw= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 4F6594BA79AE Received: by mail-wm1-f41.google.com with SMTP id 5b1f17b1804b1-48a3e9862f0so7528845e9.1 for ; Thu, 30 Apr 2026 09:18:52 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1777565931; x=1778170731; h=content-transfer-encoding:in-reply-to:content-language:from :references:cc:to:subject:user-agent:mime-version:date:message-id :x-gm-gg:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=eiOUHQFs7woRRMKT/9SbGkynaBuk1WCdIJt32+Mz5aY=; b=NEXcGFnInzFRTFXCKW/CzF4DpROJTq5Yrn694afRAtTanaslvVwXfhUnXyUJIh467q i74PJF1xwNqq6CKtKbcpgR7uL6Fs29IdvovlOkc2EZrtEuPnm98ZtPjIfUDv5lA1Hqav qixpQavDCmWt9qlACDNN5EcO0VrGnBSupw3FxAlMY/o0UtLiyAp6xII9J/3o9DmsmCZ2 16qj1ZzcoVjwGVAnIAn/74cXDkoipkiXjYyxs0YtKeWva17DxNlJ3hdxjhmcB5dpltkn Zel1ku2NIVDbcbmJ8Bg7eMNb+5ujHSYbMkSlTx7Yeq4P+AAbQxk85ycxdNIaiNPCCGLj urZA== X-Forwarded-Encrypted: i=1; AFNElJ+90ezPI3FCSunJrlc8y952+sukeov6V68/42kRTzyESr/ZCri1+kic9oBga4rCpEy3ssKMUxQPSXNO3A==@sourceware.org X-Gm-Message-State: AOJu0Yzmg8yFMU5EjR+qPD+9zUiORaxBBzQE2LokZlOK30UJ8E8fzfAF n912IZ9RhIesP0tbQ8IsoL4snLEzHnn6B8Qqz9q8sZTEuJbXJMRVIDEJ X-Gm-Gg: AeBDietY8yJp/hlgNxpHmdPMFJ2tKWdIOlPQYV8hm+l8i/qJykDad/16ldDD/Sph+9I 7RXzZ1zJBIVf5vjeXw3M36ph1XwlOdxAZL+9Cjj7cvx0rWb+9hMd3xCG9kF8BjMjO2e8+S3RsnE lt9kDELLw67jMJdUa+NL9vdddrVAKu6C9Z8I7y+O3s/G4CN4QbSMhu/aPnMIeYhblLY+v5HW2mW 0ZhCKK3dccmxQSRIDM2jyzk4shye0U6mesfg1+bTzB/Te7xbjG9BDo2UdVD4RoDlcA3yqUj4sXM 2ApUkddFr1xY9I2Vyrq4gbSFMXZoc28syq6cMehpTVSwf/XEd8ILkIdHa7z3zIvQYiCm1T6+eFJ C1g0mxUhEo59lGX5RlHHM3xf5xDUyk7C3I87chzyGKxTsIaAUapuutwSMSIek2rSvCDPPWjrIzK OuWYgQmNRBPXket/Ffj6nfRSePZoCQPI2QiQGi4pxXJJgdAElsiOfAQSnZi4A/uBJMwhLQozK/2 ggtw8140l2Fz7k= X-Received: by 2002:a05:600c:3e8e:b0:48a:5339:a46 with SMTP id 5b1f17b1804b1-48a86069e04mr47387365e9.9.1777565930880; Thu, 30 Apr 2026 09:18:50 -0700 (PDT) Received: from ?IPV6:2001:8a0:facb:a800:7184:b702:c4f3:bfd3? ([2001:8a0:facb:a800:7184:b702:c4f3:bfd3]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48a81ed659dsm75594615e9.2.2026.04.30.09.18.49 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 30 Apr 2026 09:18:50 -0700 (PDT) Message-ID: <2bcd4287-db4a-4781-8f00-69aa331af97a@palves.net> Date: Thu, 30 Apr 2026 17:18:48 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: [PATCH v2] Clarify "maint set target-non-stop" in GDB manual (Re: [PATCH v3 00/11] Windows non-stop mode) To: Eli Zaretskii Cc: ssbssa@yahoo.de, gdb-patches@sourceware.org References: <20260429201507.480870-1-pedro@palves.net> <86a4ul3sbb.fsf@gnu.org> <601b9ddc-382c-42ce-82c0-c01d3266021a@palves.net> <86wlxo3dkf.fsf@gnu.org> <9164005f-57fe-4027-8cf8-d7bd396a9812@palves.net> <86o6j032p0.fsf@gnu.org> From: Pedro Alves Content-Language: en-US In-Reply-To: <86o6j032p0.fsf@gnu.org> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit 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~public-inbox=simark.ca@sourceware.org On 2026-04-30 16:09, Eli Zaretskii wrote: >> Date: Thu, 30 Apr 2026 15:15:42 +0100 >> From: Pedro Alves >> Cc: ssbssa@yahoo.de, gdb-patches@sourceware.org >> >>> OK, I can take a look at this. >> >> How about this below? >> >> Note I added a note saying that this isn't useful to users, but note that the maint commands appendix already starts with: >> >> "In addition to commands intended for GDB users, GDB includes a number of commands intended for GDB developers, that are not documented elsewhere in this manual. > > Thanks. > >> +The following @code{set non-stop off} combinations are valid: > > Shouldn't it also say something about "set non-stop on"? It does, just below: +The following @code{set non-stop off} combinations are valid: +@table @code +@item @code{set non-stop off}, target operating in all-stop mode ... +@item @code{set non-stop off}, target operating in non-stop mode ... +@end table +@code{set non-stop on} requires the target operating in non-stop mode; +it is not compatible with the target operating in all-stop mode. I thought it was clear, but apparently not. I've now converted this to a 4-entry table. I hope it's clearer this way. > >> +@table @code >> +@item @code{set non-stop off}, target operating in all-stop mode >> +When a @value{GDBN} target is operating in all-stop mode, then when >> +a thread hits a breakpoint, finishes a step, etc., the target stops >> +all threads, and reports the event to the infrun module in the core of >> +@value{GDBN}. If infrun decides the stop is not to be seen by the >> +user, infrun re-resumes all threads again. In other words, all >> +threads stop and are re-resumed for every debug event, even for debug >> +events that are internal and do not cause a user-visible stop. >> + >> +@item @code{set non-stop off}, target operating in non-stop mode >> +When a @value{GDBN} target is operating in non-stop mode in >> +combination with @code{set non-stop} set to @code{off}, it is said >> +that @value{GDBN} is operating in ``all-stop on top of non-stop''. In >> +this scenario, when a thread hits a breakpoint, finishes a step, etc., >> +the target does not immediately stop all other threads. If, while >> +processing the event, infrun decides the stop should be reported to >> +the user, it then explicitly stops all threads, just before presenting >> +the stop to the user; otherwise, infrun re-resumes the stopped thread. >> +@end table > > The second @item says "...in combination with @code{set non-stop} set > to @code{off}", which is a Good Thing, but the first @item doesn't say > the same about the "on" setting. I suggest to make the style more > consistent. Done. > > Also, what about the description of "set non-stop", the user-level > command? It currently doesn't even say what is the default. In > addition, the fact that its description says "Enable selection of > non-stop mode" is confusing, because it makes it sound like there's > some other command to actually "select" the non-stop mode. The text > which attempts to explain the "enable" part, viz.: > > Note these commands only reflect whether non-stop mode is enabled, > not whether the currently-executing program is being run in non-stop > mode. In particular, the 'set non-stop' preference is only consulted > when GDB starts or connects to the target program, and it is generally > not possible to switch modes once debugging has started. Furthermore, > since not all targets support non-stop mode, even when you have enabled > non-stop mode, GDB may still fall back to all-stop operation by default. > > doesn't really justify the "enable" part. It won't surprise anyone > that "set non-stop on" will only work if the target doesn't support > it, and the fact that this command only affects the next inferior to > be started is just a factoid to be mentioned, but it again doesn't > justify the "enable" confusion, IMO. > The "To enter non-stop mode" part is also unnecessary, the pagination suggestion breaking non-stop was something that was needed early on. Here's take 2: >From 6a34cd5c0720a103b6a005d5abfcc52b91e15759 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Thu, 30 Apr 2026 13:12:10 +0100 Subject: [PATCH] Clarify "set non-stop" and "maint set target-non-stop" in GDB manual This provides the following improvements to the GDB user manual, where we document "set non-stop" and "maint set target-non-stop": - In the "set non-stop" section: - Names "all-stop" earlier. - Says what mode is the default. - Removes old pagination suggestion. - Clarifies text. - In the "maint set target-non-stop" section: - Clarifies "maint set target-non-stop" vs "set non-stop" . - Corrects the "auto" description to current reality. - Gives a couple examples of what "GDB targets" are. - Documents the "all-stop on top of non-stop" term. Change-Id: Ia720e5091dd57321fb19e6a306678b834ab822df commit-id:dbc519ee --- gdb/doc/gdb.texinfo | 71 +++++++++++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 22 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 82306072e8c..ab0216ff477 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -7528,6 +7528,10 @@ multiple processes. @c This section is really only a place-holder, and needs to be expanded @c with more details. +By default, when a thread stops to report a debugging event, +@value{GDBN} stops all other threads as well. This is called +@dfn{all-stop} mode. + For some multi-threaded targets, @value{GDBN} supports an optional mode of operation in which you can examine stopped program threads in the debugger while other threads continue to execute freely. This @@ -7546,34 +7550,22 @@ one thread while allowing others to run freely, stepping one thread while holding all others stopped, or stepping several threads independently and simultaneously. -To enter non-stop mode, use this sequence of commands before you run -or attach to your program: - -@smallexample -# If using the CLI, pagination breaks non-stop. -set pagination off - -# Finally, turn it on! -set non-stop on -@end smallexample - You can use these commands to manipulate the non-stop mode setting: @table @code @kindex set non-stop @item set non-stop on -Enable selection of non-stop mode. +Enable non-stop mode. @item set non-stop off -Disable selection of non-stop mode. +Disable non-stop mode. Also known as enabling all-stop mode. This is +the default. @kindex show non-stop @item show non-stop Show the current non-stop enablement setting. @end table -Note these commands only reflect whether non-stop mode is enabled, -not whether the currently-executing program is being run in non-stop mode. -In particular, the @code{set non-stop} preference is only consulted when -@value{GDBN} starts or connects to the target program, and it is generally +Note the @code{set non-stop} preference is only consulted when +@value{GDBN} starts or connects to the target program, and it is not possible to switch modes once debugging has started. Furthermore, since not all targets support non-stop mode, even when you have enabled non-stop mode, @value{GDBN} may still fall back to all-stop operation by @@ -42907,15 +42899,22 @@ to more easily debug problems occurring only in synchronous mode. @item maint set target-non-stop @itemx maint show target-non-stop -This controls whether @value{GDBN} targets always operate in non-stop -mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop -Mode}). The default is @code{auto}, meaning non-stop mode is enabled -if supported by the target. +This controls whether @value{GDBN} targets (e.g., the native target, +or a remote target) operate in non-stop mode even if @code{set +non-stop} is @code{off} (@pxref{Non-Stop Mode}). The default is +@code{auto}. + +This affects @value{GDBN} internal operation and is largely invisible +to users. Normally users should not need to change this setting, but +it can be changed to more easily debug problems occurring only in a +specific mode. @table @code @item maint set target-non-stop auto This is the default mode. @value{GDBN} controls the target in -non-stop mode if the target supports it. +non-stop mode if @code{set non-stop} is @code{on}, or the target tells +infrun that it wants to operate in non-stop mode even with @code{set +non-stop} is set to @code{off}. @item maint set target-non-stop on @value{GDBN} controls the target in non-stop mode even if the target @@ -42926,6 +42925,34 @@ does not indicate support. target supports it. @end table +Here is how @code{set non-stop} and @code{maint set target-non-stop} +settings combine: + +@table @code +@item @code{set non-stop off}, target operating in all-stop mode +When a thread hits a breakpoint, finishes a step, etc., the target +stops all threads, and reports the event to the infrun module in the +core of @value{GDBN}. If infrun decides the stop is not to be seen by +the user, infrun re-resumes all threads again. In other words, all +threads stop and are re-resumed for every debug event, even for debug +events that are internal and do not cause a user-visible stop. + +@item @code{set non-stop off}, target operating in non-stop mode +When a thread hits a breakpoint, finishes a step, etc., the target +does not immediately stop all other threads. If, while processing the +event, infrun decides the stop should be reported to the user, it then +explicitly stops all threads, just before presenting the stop to the +user; otherwise, infrun re-resumes the stopped thread. This scenario +is also called ``all-stop on top of non-stop''. + +@item @code{set non-stop on}, target operating in all-stop mode +This combination is invalid. + +@item @code{set non-stop on}, target operating in non-stop mode +When a thread hits a breakpoint, finishes a step, etc., neither the +target, nor infrun stop any other thread. +@end table + @kindex maint set tui-resize-message @kindex maint show tui-resize-message @item maint set tui-resize-message base-commit: bc145a24033381e93bae0ee24add664386c66433 -- 2.53.0