[PATCH v2] [gdb/doc]: clarify the language for the '?' packet

[PATCH v2] [gdb/doc]: clarify the language for the '?' packet

[Alex Bennée]

Both QEMU and kgdb make the assumption that the '?' packet is only
sent during the initial setup of a gdbstub connection. Both use that
knowledge to reset breakpoints and ensure the gdbstub is in a
clean-state on a resumed connection. This can cause confusion for
others implementing clients that speak to gdbstub devices. To avoid
that make the language clearer that this is a start-up query packet
that you only expect to see once.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

gdb/ChangeLog:

2020-12-16  Alex Bennée <alex.bennee@linaro.org>

	* doc/gdb.texinfo: add clarifying language for ? packet

---
v2
  - re-introduce line break
  - re-word first sentance
  - re-establish double spacing for sentence breaks
  - update gdb/ChangeLog
---
 gdb/ChangeLog       | 4 ++++
 gdb/doc/gdb.texinfo | 7 ++++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 5dc879b0443..e4862061691 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,7 @@
+2020-12-16  Alex Bennée <alex.bennee@linaro.org>
+
+	* doc/gdb.texinfo: add clarifying language for ? packet
+
 2020-12-16  Tom Tromey  <tom@tromey.com>
 	    Tom Tromey  <tromey@redhat.com>
 	    Tom de Vries  <tdevries@suse.de>
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5b6ac8549bc..70a8542cfb9 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -39493,9 +39493,10 @@ The remote target both supports and has enabled extended mode.
 @item ?
 @cindex @samp{?} packet
 @anchor{? packet}
-Indicate the reason the target halted.  The reply is the same as for
-step and continue.  This packet has a special interpretation when the
-target is in non-stop mode; see @ref{Remote Non-Stop}.
+This is sent when connection is first established to query the reason
+the target halted.  The reply is the same as for step and continue.
+This packet has a special interpretation when the target is in
+non-stop mode; see @ref{Remote Non-Stop}.
 
 Reply:
 @xref{Stop Reply Packets}, for the reply specifications.
-- 
2.20.1

Re: [PATCH v2] [gdb/doc]: clarify the language for the '?' packet

[Eli Zaretskii]

> Date: Wed, 16 Dec 2020 18:23:32 +0000
> From: Alex Bennée via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Alex Bennée <alex.bennee@linaro.org>
> 
> 2020-12-16  Alex Bennée <alex.bennee@linaro.org>
> 
> 	* doc/gdb.texinfo: add clarifying language for ? packet

Please indicate in what node the change is being made (in parentheses,
as if the node were a function).

> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -39493,9 +39493,10 @@ The remote target both supports and has enabled extended mode.
>  @item ?
>  @cindex @samp{?} packet
>  @anchor{? packet}
> -Indicate the reason the target halted.  The reply is the same as for
> -step and continue.  This packet has a special interpretation when the
> -target is in non-stop mode; see @ref{Remote Non-Stop}.
> +This is sent when connection is first established to query the reason
> +the target halted.  The reply is the same as for step and continue.
> +This packet has a special interpretation when the target is in
> +non-stop mode; see @ref{Remote Non-Stop}.

This is OK, thanks.