[PATCH] Clarify "maint set target-non-stop" in GDB manual (Re: [PATCH v3 00/11] Windows non-stop mode)

[Pedro Alves <pedro@palves.net>]

On 2026-04-30 13:01, Pedro Alves wrote:
> On 2026-04-30 12:14, Eli Zaretskii wrote:
>>
>> I think we should clarify the text in the manual, and in particular we
>> should not use "operate in non-stop mode" for describing both the
>> user-level "set non-stop on" and the maint command.  I would also
>> welcome some wording in the description of the maint command to
>> clearly indicate that this setting is of no interest to users
>> whatsoever, only to GDB developers who work on this mode.  Explaining
>> "backend" (not currently described anywhere in the manual AFAICT)
>> would also be welcome, as it seems to be relevant for this particular
>> issue, and could be used in the manual to clarify this.
> 
> 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. 

From 897071189f4acf94b6e01e32bc10f2c036181b42 Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Thu, 30 Apr 2026 13:12:10 +0100
Subject: [PATCH] Clarify "maint set target-non-stop" in GDB manual

This provides the following improvements to the GDB user manual, where
we document "maint set target-non-stop":

 - 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 | 43 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 82306072e8c..f6b9436f841 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -42907,15 +42907,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 +42933,32 @@ does not indicate support.
 target supports it.
 @end table
 
+The following @code{set non-stop off} combinations are valid:
+
+@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
+
+@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.
+
 @kindex maint set tui-resize-message
 @kindex maint show tui-resize-message
 @item maint set tui-resize-message

base-commit: bc145a24033381e93bae0ee24add664386c66433
-- 
2.53.0