[v2] Clarify "maint set target-non-stop" in GDB manual (Re: [PATCH v3 00/11] Windows non-stop mode)
Commit Message
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(-)
base-commit: bc145a24033381e93bae0ee24add664386c66433
Comments
> Date: Thu, 30 Apr 2026 17:18:48 +0100
> Cc: ssbssa@yahoo.de, gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
>
> Here's take 2:
Thanks, this LGTM.
On 2026-04-30 17:27, Eli Zaretskii wrote:
>> Date: Thu, 30 Apr 2026 17:18:48 +0100
>> Cc: ssbssa@yahoo.de, gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>> Here's take 2:
>
> Thanks, this LGTM.
>
Thanks, now merged.
@@ -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