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

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

[Alex Bennée via Gdb-patches]

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/doc/gdb.texinfo | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 8bff27c940d..f5b6fdd8691 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -39273,9 +39273,9 @@ 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
+@anchor{? packet} Is a query 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:
-- 
2.20.1

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

[Luis Machado via Gdb-patches]

On 12/7/20 10:53 AM, Alex Bennée via Gdb-patches wrote:
> 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/doc/gdb.texinfo | 6 +++---
>   1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 8bff27c940d..f5b6fdd8691 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -39273,9 +39273,9 @@ 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
> +@anchor{? packet} Is a query sent when connection is first established
> +to query the reason the target halted. The reply is the same as for

More like "to query the status of the target". To see if it is running, 
stopped etc...

With that clarification, I think this looks good. Others may have more 
feedback.

It is important to mention this is a very old packet with a historically 
vague description, but I think it is safe to say GDB doesn't have a 
reason to send it more than once per remote session.

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

[Eli Zaretskii via Gdb-patches]

> Date: Mon,  7 Dec 2020 13:53:19 +0000
> From: Alex Bennée via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Alex Bennée <alex.bennee@linaro.org>
> 
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -39273,9 +39273,9 @@ 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
> +@anchor{? packet} Is a query 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}.

Minor comments:

  . please make the @anchor be a separate line, as it was before
  . the first sentence ("Is a query sent...") sounds awkward, suggest
    to reword "This is sent when connection is first ..."
  . please make sure to leave 2 spaces between sentences, per our
    conventions
  . please provide a suitable log message and ChangeLog change

Thanks.