[PATCH v2] 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 16:09, Eli Zaretskii wrote:
>> Date: Thu, 30 Apr 2026 15:15:42 +0100
>> From: Pedro Alves <pedro@palves.net>
>> 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 <pedro@palves.net>
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