Re: [PATCH 02/12] Centralize documentation of error and empty RSP responses

[Pedro Alves <pedro@palves.net>]

On 2024-04-19 16:36, Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Cc: Jim Blandy <jimb@codesourcery.com>,
>>  Mike Wrighton <mike_wrighton@mentor.com>,
>>  Nathan Sidwell <nathan@codesourcery.com>,
>>  Hafiz Abid Qadeer <abidh@codesourcery.com>
>> Date: Fri, 19 Apr 2024 16:13:32 +0100
>>
>>  gdb/doc/gdb.texinfo | 244 +++++++-------------------------------------
>>  1 file changed, 36 insertions(+), 208 deletions(-)
> 
> Thanks.
> 
>> +See @ref{Standard Replies} for standard error responses, and how to
> 
> Please use @xref here instead of "See @ref", as that's what @xref is
> for.  Also, some old versions of makeinfo insist on a period or comma
> after the closing brace (with the single exception of @pxref), so
> please add it.

Fixed.

> 
>> +@node Standard Replies
>> +@section Standard Replies
> 
> This section should have an index entry.  I suggest
> 
>   @cindex standard responses for remote packets
>   @cindex remote packets, standard replies
> 

Thanks, added.

>> +@cindex empty response, for unsupported packets
>> +@cindex unsupported packets, empty response for
>> +For any @var{command} not supported by the stub, an empty response
>                 ^^^^^^^
> "command", not "packet"?

Yes.  The protocol is described like this:

 The host (@value{GDBN}) sends @var{command}s, and the target (the debugging stub incorporated in your program) sends a @var{response}. 

 ... and ...

 All @value{GDBN} commands and responses (other than acknowledgments
 and notifications, see @ref{Notification Packets}) are sent as a
 @var{packet}.  


So both command and response are packets.  But not all packets are commands.

> 
>> +(@samp{$#00}) should be returned.
> 
> I don't understand what you mean by $#00, and why that is considered
> and "empty response".  I'm probably missing something.

"$#00" is the raw sequence of characters that is sent over the wire for a
packet with an empty payload.  It comes from this:

 A @var{packet} is introduced with the character
 @samp{$}, the actual @var{packet-data}, and the terminating character
 @samp{#} followed by a two-digit @var{checksum}:

 @smallexample
 @code{$}@var{packet-data}@code{#}@var{checksum}
 @end smallexample
 @noindent

When packet-data, which is the payload, is empty, you end up with "$#00".

Note I just moved that sentence, it was already described that way.  But we
can certainly improve it.  I propose adding "raw character sequence" (see below).

> 
> Also, "should be returned" doesn't really fit the purpose of this
> section, which AFAIU is to describe the standard responses.  So
> something like below would be IMO more appropriate:
> 
>   An empty response means this packet is not supported by the stub.
> 

Makes sense.  Like so?

+@cindex empty response, for unsupported packets
+@cindex unsupported packets, empty response for
+An empty response (raw character sequence @samp{$#00}) means the
+@var{command} is not supported by the stub.  This way it is possible
+to extend the protocol.  A newer @value{GDBN} can tell if a command is
+supported based on that response (but see also @ref{qSupported}).

Here is the full updated patch.

From c3e60049bd08c97f8b665af4d5861154aac3975a Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Thu, 18 Apr 2024 20:22:36 +0100
Subject: [PATCH] Centralize documentation of error and empty RSP responses

Currently, for each packet, we document the "E NN" response (error),
and the empty response (unsupported).  This patch centralizes that in
a new "Standard Replies" section.

In the "Packets", "General Query Packets", "Tracepoint Packets"
sections, Remove explicit mention of empty and error replies, except
when they provide detail not covered in Standard Replies.

Note this hunk:

 -@item E @var{NN}
 -@var{NN} is errno

and this one:

 -@item E00
 -The request was malformed, or @var{annex} was invalid.
 -
 -@item E @var{nn}
 -The offset was invalid, or there was an error encountered reading the data.
 -The @var{nn} part is a hex-encoded @code{errno} value.

were really documenting things that don't really work that way.

The first is the documentation of the "m" packet.  GDB does _not_
interpret the NN as an errno.  It can't, in fact, because the
remote/target errno numbers have nothing to do with GDB/host errno
numbers in a cross debugging scenario.

The second hunk above is from the documentation of qXfer.  Again, GDB
does not give any interpretation to the NN error code at all.  Nor
does GDBserver.  And again, an errno number can't be interpreted in a
cross debugging scenario.

Change-Id: I973695c80809cdb5a5e8d5be8b78ba4d1ecdb513
Co-Authored-By: Jim Blandy <jimb@codesourcery.com>
Co-Authored-By: Mike Wrighton <mike_wrighton@mentor.com>
Co-Authored-By: Nathan Sidwell <nathan@codesourcery.com>
Co-Authored-By: Hafiz Abid Qadeer <abidh@codesourcery.com>
---
 gdb/doc/gdb.texinfo | 246 +++++++-------------------------------------
 1 file changed, 38 insertions(+), 208 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 6fa32d1bd01..9781ce76226 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -40242,8 +40242,6 @@ The @var{gdb_jump_pad_head} is updated head of jumppad.  Both of
 @var{target_address} and @var{gdb_jump_pad_head} are 8-byte long.
 The @var{fjump} contains a sequence of instructions jump to jumppad entry.
 The @var{fjump_size}, 4-byte long, is the size of @var{fjump}.
-@item E @var{NN}
-for an error
 
 @end table
 
@@ -40262,8 +40260,6 @@ Asks in-process agent to probe the marker at @var{address}.
 
 Replies:
 @table @samp
-@item E @var{NN}
-for an error
 @end table
 @item unprobe_marker_at:@var{address}
 Asks in-process agent to unprobe the marker at @var{address}.
@@ -42368,6 +42364,7 @@ Show the current setting of the target wait timeout.
 
 @menu
 * Overview::
+* Standard Replies::
 * Packets::
 * Stop Reply Packets::
 * General Query Packets::
@@ -42508,14 +42505,8 @@ seven repeats (@samp{$}) can be expanded using a repeat count of only
 five (@samp{"}).  For example, @samp{00000000} can be encoded as
 @samp{0*"00}.
 
-The error response returned for some packets includes a two character
-error number.  That number is not well defined.
-
-@cindex empty response, for unsupported packets
-For any @var{command} not supported by the stub, an empty response
-(@samp{$#00}) should be returned.  That way it is possible to extend the
-protocol.  A newer @value{GDBN} can tell if a packet is supported based
-on that response.
+@xref{Standard Replies} for standard error responses, and how to
+respond indicating a command is not supported.
 
 In describing packets (commands and responses), each description has a
 template showing the overall syntax, followed by an explanation of the
@@ -42543,6 +42534,33 @@ the @samp{s} (step) command.  Stubs that support multi-threading
 targets should support the @samp{vCont} command.  All other commands
 are optional.
 
+@node Standard Replies
+@section Standard Replies
+@cindex standard responses for remote packets
+@cindex remote packets, standard replies
+
+The remote protocol specifies a few standard replies.  All commands
+support these, except as noted in the individual command descriptions.
+
+@table @asis
+
+@item empty response
+
+@cindex empty response, for unsupported packets
+@cindex unsupported packets, empty response for
+An empty response (raw character sequence @samp{$#00}) means the
+@var{command} is not supported by the stub.  This way it is possible
+to extend the protocol.  A newer @value{GDBN} can tell if a command is
+supported based on that response (but see also @ref{qSupported}).
+
+@item @samp{E @var{xx}}
+An error has occurred; @var{xx} is a two-digit hexadecimal error
+number.  In almost all cases, the protocol does not specify the
+meaning of the error numbers; @value{GDBN} usually ignores the
+numbers, or displays them to the user without further interpretation.
+
+@end table
+
 @node Packets
 @section Packets
 
@@ -42630,8 +42648,6 @@ Reply:
 @table @samp
 @item OK
 The arguments were set.
-@item E @var{NN}
-An error occurred.
 @end table
 
 @item b @var{baud}
@@ -42720,8 +42736,6 @@ Reply:
 @table @samp
 @item OK
 for success
-@item E @var{NN}
-for an error
 @end table
 
 @item F @var{RC},@var{EE},@var{CF};@var{XX}
@@ -42768,8 +42782,6 @@ are available, and both have zero value:
 <- @code{xxxxxxxx00000000xxxxxxxx00000000}
 @end smallexample
 
-@item E @var{NN}
-for an error.
 @end table
 
 @item G @var{XX@dots{}}
@@ -42781,8 +42793,6 @@ Reply:
 @table @samp
 @item OK
 for success
-@item E @var{NN}
-for an error
 @end table
 
 @item H @var{op} @var{thread-id}
@@ -42799,8 +42809,6 @@ Reply:
 @table @samp
 @item OK
 for success
-@item E @var{NN}
-for an error
 @end table
 
 @c FIXME: JTC:
@@ -42875,8 +42883,6 @@ Reply:
 Memory contents; each byte is transmitted as a two-digit hexadecimal number.
 The reply may contain fewer addressable memory units than requested if the
 server was able to read only part of the region of memory.
-@item E @var{NN}
-@var{NN} is errno
 @end table
 
 @item M @var{addr},@var{length}:@var{XX@dots{}}
@@ -42888,10 +42894,8 @@ byte is transmitted as a two-digit hexadecimal number.
 Reply:
 @table @samp
 @item OK
-for success
-@item E @var{NN}
-for an error (this includes the case where only part of the data was
-written).
+All the data was written successfully.  (If only part of the data was
+written, this command returns an error.)
 @end table
 
 @item p @var{n}
@@ -42904,10 +42908,6 @@ Reply:
 @table @samp
 @item @var{XX@dots{}}
 the register's value
-@item E @var{NN}
-for an error
-@item @w{}
-Indicating an unrecognized @var{query}.
 @end table
 
 @item P @var{n@dots{}}=@var{r@dots{}}
@@ -42921,8 +42921,6 @@ Reply:
 @table @samp
 @item OK
 for success
-@item E @var{NN}
-for an error
 @end table
 
 @item q @var{name} @var{params}@dots{}
@@ -42982,8 +42980,6 @@ Reply:
 @table @samp
 @item OK
 thread is still alive
-@item E @var{NN}
-thread is dead
 @end table
 
 @item v
@@ -43011,8 +43007,6 @@ This packet is only available in extended mode (@pxref{extended mode}).
 
 Reply:
 @table @samp
-@item E @var{nn}
-for an error
 @item @r{Any stop packet}
 for success in all-stop mode (@pxref{Stop Reply Packets})
 @item OK
@@ -43101,8 +43095,6 @@ Reply:
 @item vCont@r{[};@var{action}@dots{}@r{]}
 The @samp{vCont} packet is supported.  Each @var{action} is a supported
 command in the @samp{vCont} packet.
-@item @w{}
-The @samp{vCont} packet is not supported.
 @end table
 
 @anchor{vCtrlC packet}
@@ -43117,8 +43109,6 @@ variant.
 
 Reply:
 @table @samp
-@item E @var{nn}
-for an error
 @item OK
 for success
 @end table
@@ -43143,8 +43133,6 @@ Reply:
 @table @samp
 @item OK
 for success
-@item E @var{NN}
-for an error
 @end table
 
 @item vFlashWrite:@var{addr}:@var{XX@dots{}}
@@ -43167,8 +43155,6 @@ Reply:
 for success
 @item E.memtype
 for vFlashWrite addressing non-flash memory
-@item E @var{NN}
-for an error
 @end table
 
 @item vFlashDone
@@ -43190,8 +43176,6 @@ supported; see @ref{multiprocess extensions}.
 
 Reply:
 @table @samp
-@item E @var{nn}
-for an error
 @item OK
 for success
 @end table
@@ -43223,8 +43207,6 @@ This packet is only available in extended mode (@pxref{extended mode}).
 
 Reply:
 @table @samp
-@item E @var{nn}
-for an error
 @item @r{Any stop packet}
 for success (@pxref{Stop Reply Packets})
 @end table
@@ -43245,8 +43227,6 @@ Reply:
 @table @samp
 @item OK
 for success
-@item E @var{NN}
-for an error
 @end table
 
 @item z @var{type},@var{addr},@var{kind}
@@ -43327,10 +43307,6 @@ Reply:
 @table @samp
 @item OK
 success
-@item @w{}
-not supported
-@item E @var{NN}
-for an error
 @end table
 
 @item z1,@var{addr},@var{kind}
@@ -43352,10 +43328,6 @@ Reply:
 @table @samp
 @item OK
 success
-@item @w{}
-not supported
-@item E @var{NN}
-for an error
 @end table
 
 @item z2,@var{addr},@var{kind}
@@ -43369,10 +43341,6 @@ Reply:
 @table @samp
 @item OK
 success
-@item @w{}
-not supported
-@item E @var{NN}
-for an error
 @end table
 
 @item z3,@var{addr},@var{kind}
@@ -43386,10 +43354,6 @@ Reply:
 @table @samp
 @item OK
 success
-@item @w{}
-not supported
-@item E @var{NN}
-for an error
 @end table
 
 @item z4,@var{addr},@var{kind}
@@ -43403,10 +43367,6 @@ Reply:
 @table @samp
 @item OK
 success
-@item @w{}
-not supported
-@item E @var{NN}
-for an error
 @end table
 
 @end table
@@ -43776,8 +43736,6 @@ detect trailing zeros.
 
 Reply:
 @table @samp
-@item E @var{NN}
-An error (such as memory fault)
 @item C @var{crc32}
 The specified memory region's checksum is @var{crc32}.
 @end table
@@ -43800,13 +43758,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QDisableRandomization} is not supported
-by the stub.
 @end table
 
 This packet is not probed by default; the remote stub must request it,
@@ -43835,9 +43786,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
 @end table
 
 This packet is not probed by default; the remote stub must request it,
@@ -44027,12 +43975,6 @@ Reply:
 @item @var{XX}@dots{}
 Hex encoded (big endian) bytes representing the address of the thread
 local storage requested.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
 @end table
 
 @item qGetTIBAddr:@var{thread-id}
@@ -44047,13 +43989,6 @@ Reply:
 @item @var{XX}@dots{}
 Hex encoded (big endian) bytes representing the linear address of the
 thread information block.
-
-@item E @var{nn}
-An error occurred.  This means that either the thread was not found, or the
-address could not be retrieved.
-
-@item @w{}
-An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
 @end table
 
 @item qL @var{startflag} @var{threadcount} @var{nextthread}
@@ -44093,20 +44028,15 @@ is architecture-specific.
 @var{type} is the type of tag the request wants to fetch.  The type is a signed
 integer.
 
+@value{GDBN} will only send this packet if the stub has advertised
+support for memory tagging via @samp{qSupported}.
+
 Reply:
 @table @samp
 @item @var{mxx}@dots{}
 Hex encoded sequence of uninterpreted bytes, @var{xx}@dots{}, representing the
 tags found in the requested memory range.
 
-@item E @var{nn}
-An error occurred.  This means that fetching of memory tags failed for some
-reason.
-
-@item @w{}
-An empty reply indicates that @samp{qMemTags} is not supported by the stub,
-although this should not happen given @value{GDBN} will only send this packet
-if the stub has advertised support for memory tagging via @samp{qSupported}.
 @end table
 
 @cindex check if a given address is in a memory tagged region
@@ -44171,20 +44101,14 @@ integer.
 interpreted by the target.  Each pair of hex digits is interpreted as a
 single byte.
 
+@value{GDBN} will only send this packet if the stub has advertised
+support for memory tagging via @samp{qSupported}.
+
 Reply:
 @table @samp
 @item OK
 The request was successful and the memory tag granules were modified
 accordingly.
-
-@item E @var{nn}
-An error occurred.  This means that modifying the memory tag granules failed
-for some reason.
-
-@item @w{}
-An empty reply indicates that @samp{QMemTags} is not supported by the stub,
-although this should not happen given @value{GDBN} will only send this packet
-if the stub has advertised support for memory tagging via @samp{qSupported}.
 @end table
 
 @item qOffsets
@@ -44241,13 +44165,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QNonStop} is not supported by
-the stub.
 @end table
 
 This packet is not probed by default; the remote stub must request it,
@@ -44284,13 +44201,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  @var{nn} are hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QCatchSyscalls} is not supported by
-the stub.
 @end table
 
 Use of this packet is controlled by the @code{set remote catch-syscalls}
@@ -44316,13 +44226,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QPassSignals} is not supported by
-the stub.
 @end table
 
 Use of this packet is controlled by the @code{set remote pass-signals}
@@ -44358,13 +44261,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QProgramSignals} is not supported
-by the stub.
 @end table
 
 Use of this packet is controlled by the @code{set remote program-signals}
@@ -44398,13 +44294,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QThreadEvents} is not supported by
-the stub.
 @end table
 
 Use of this packet is controlled by the @code{set remote thread-events}
@@ -44487,13 +44376,6 @@ Reply:
 @table @samp
 @item OK
 The request succeeded.
-
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-
-@item @w{}
-An empty reply indicates that @samp{QThreadOptions} is not supported by
-the stub.
 @end table
 
 Use of this packet is controlled by the @code{set remote thread-options}
@@ -44515,11 +44397,6 @@ Reply:
 A command response with no output.
 @item @var{OUTPUT}
 A command response with the hex encoded output string @var{OUTPUT}.
-@item E @var{NN}
-Indicate a badly formed request.  The error number @var{NN} is given as
-hex digits.
-@item @w{}
-An empty reply indicates that @samp{qRcmd} is not recognized.
 @end table
 
 (Note that the @code{qRcmd} packet's name is separated from the
@@ -44544,10 +44421,6 @@ Reply:
 The pattern was not found.
 @item 1,address
 The pattern was found at @var{address}.
-@item E @var{NN}
-A badly formed request or an error was encountered while searching memory.
-@item @w{}
-An empty reply indicates that @samp{qSearch:memory} is not recognized.
 @end table
 
 @item QStartNoAckMode
@@ -44563,8 +44436,6 @@ The stub has switched to no-acknowledgment mode.
 @value{GDBN} acknowledges this response,
 but neither the stub nor @value{GDBN} shall send or expect further
 @samp{+}/@samp{-} acknowledgments in the current connection.
-@item @w{}
-An empty reply indicates that the stub does not support no-acknowledgment mode.
 @end table
 
 @item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
@@ -44593,9 +44464,6 @@ Reply:
 The stub supports or does not support each returned @var{stubfeature},
 depending on the form of each @var{stubfeature} (see below for the
 possible forms).
-@item @w{}
-An empty reply indicates that @samp{qSupported} is not recognized,
-or that no features needed to be reported to @value{GDBN}.
 @end table
 
 The allowed forms for each feature (either a @var{gdbfeature} in the
@@ -45316,17 +45184,6 @@ have fewer bytes than the @var{length} in the request.
 @item l
 The @var{offset} in the request is at the end of the data.
 There is no more data to be read.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered reading the data.
-The @var{nn} part is a hex-encoded @code{errno} value.
-
-@item @w{}
-An empty reply indicates the @var{object} string was not recognized by
-the stub, or that the object does not support reading.
 @end table
 
 Here are the specific requests of this form defined so far.  All the
@@ -45545,17 +45402,6 @@ Reply:
 @item @var{nn}
 @var{nn} (hex encoded) is the number of bytes written.
 This may be fewer bytes than supplied in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered writing the data.
-The @var{nn} part is a hex-encoded @code{errno} value.
-
-@item @w{}
-An empty reply indicates the @var{object} string was not
-recognized by the stub, or that the object does not support writing.
 @end table
 
 Here are the specific requests of this form defined so far.  All the
@@ -45600,8 +45446,6 @@ Reply:
 The remote server attached to an existing process.
 @item 0
 The remote server created a new process.
-@item E @var{NN}
-A badly formed request or an error was encountered.
 @end table
 
 @item Qbtrace:bts
@@ -45805,8 +45649,6 @@ Replies:
 The packet was understood and carried out.
 @item qRelocInsn
 @xref{Tracepoint Packets,,Relocate instruction reply packet}.
-@item  @w{}
-The packet was not recognized.
 @end table
 
 @item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
@@ -45871,8 +45713,6 @@ Replies:
 The packet was understood and carried out.
 @item qRelocInsn
 @xref{Tracepoint Packets,,Relocate instruction reply packet}.
-@item  @w{}
-The packet was not recognized.
 @end table
 
 @item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes}
@@ -45989,8 +45829,6 @@ of 1 means that a fast tracepoint may be placed on any instruction
 regardless of size.
 @item E
 An error has occurred.
-@item @w{}
-An empty reply indicates that the request is not supported by the stub.
 @end table
 
 @item QTStart
@@ -46199,11 +46037,6 @@ A single marker
 a comma-separated list of markers
 @item l
 (lower case letter @samp{L}) denotes end of list.
-@item E @var{nn}
-An error occurred.  The error number @var{nn} is given as hex digits.
-@item @w{}
-An empty reply indicates that the request is not supported by the
-stub.
 @end table
 
 The @var{address} is encoded in hex;
@@ -46292,9 +46125,6 @@ Replies:
 @item qRelocInsn:@var{adjusted_size}
 Informs the stub the relocation is complete.  The @var{adjusted_size} is
 the length in bytes of resulting relocated instruction sequence.
-@item E @var{NN}
-A badly formed request was detected, or an error was encountered while
-relocating the instruction.
 @end table
 
 @node Host I/O Packets

base-commit: 0e6747d2a638693ad2f20e7929c8364913c87279
prerequisite-patch-id: 69a7241ff790954e07942cd212971bcfaa8f3a08
-- 
2.43.2