Clarify "maint set target-non-stop" in GDB manual (Re: [PATCH v3 00/11] Windows non-stop mode)
Commit Message
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(-)
base-commit: bc145a24033381e93bae0ee24add664386c66433
Comments
> 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"?
> +@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.
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.
@@ -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