Re: [PATCH 03/12] Document "E.MESSAGE" RSP errors

[Pedro Alves <pedro@palves.net>]

On 2024-04-22 09:50, Andrew Burgess wrote:

>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index 57260a5b2fa..d6184d52841 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -42557,6 +42557,10 @@ 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.
>>  
>> +@item @samp{E.@var{message}}
>> +An error has occurred; @var{message} is the textual error message,
>> +encoded in @sc{ascii}.
> 
> I think we should document here that the 'qRcmd' and 'm' packets don't
> accept this reply format.
> 
> Alexandra Hájková has a patch series which has not been posted yet which
> will extend these packets in a backward compatible way so that E.message
> can be used, but until that arrives we should probably document this
> limitation.

Done, see updated patch below.  (See the bottom of the new commit log.)

Not sure when we'd want to make GDB print the error for the 'm' packet,
though.  Currently it just returns TARGET_XFER_E_IO up to the caller.

I noticed a few packets were documenting an "E.errtext" response,
which I now removed in this version.  Then "E.errtext" seemed more
descriptive than "E.message", so I switched to that too.


From 36ef5ca67f515039bfa68d2fb2515f181629a24f Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Thu, 18 Apr 2024 20:22:36 +0100
Subject: [PATCH] Document "E.MESSAGE" RSP errors

For many years, GDB has accepted a "E.MESSAGE" error response, in
addition to "E NN".  For many packets, GDB strips the "E." before
giving the error message to the user.  For others, GDB does not strip
the "E.", but still understands that it is an error, as it starts with
"E", and either prints the whole string, or ignores it and just
mentions an error occured (same as for "E NN").

This has been the case for as long as I remember.  Now that I check, I
see that it's been there since 2006 (commit a76d924dffcb, also here:
https://sourceware.org/pipermail/gdb-patches/2006-September/047286.html).
All along, I actually thought it was documented.  Turns out it wasn't.

This commit documents it, in the new "Standard Replies" section, near
where we document "E NN".

The original version of this 3-patch documentation series was a single
CodeSourcery patch that documented the textual error as
"E.NAME.MESSAGE", with MESSAGE being 8-bit binary encoded.  But I
think the ship has sailed for that.  GDBserver has been sending error
messages with more than one "." for a long while, and with no binary
encoding.  Still, I've preserved the "Co-Authored-By" list of the
original larger patch.

The 'qRcmd' and 'm' commands are exceptions and do not accept this
reply format.  The top of the "Standard Replies" section already says:

  "All commands support these, except as noted in the individual
  command descriptions."

So this adds a note to the description of 'qRcmd' and 'm', explicitly
stating that they do not support this error reply format.

Change-Id: Ie4fee3d00d82ede39e439bf162e8cb7485532fd8
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 | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9781ce76226..f55ada29e9c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -42559,6 +42559,11 @@ 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.
 
+@anchor{textual error reply}
+@item @samp{E.@var{errtext}}
+An error has occurred; @var{errtext} is the textual error message,
+encoded in @sc{ascii}.
+
 @end table
 
 @node Packets
@@ -42885,6 +42890,10 @@ The reply may contain fewer addressable memory units than requested if the
 server was able to read only part of the region of memory.
 @end table
 
+Unlike most packets, this packet does not support
+@samp{E.@var{errtext}}-style textual error replies (@pxref{textual
+error reply}).
+
 @item M @var{addr},@var{length}:@var{XX@dots{}}
 @cindex @samp{M} packet
 Write @var{length} addressable memory units starting at address @var{addr}
@@ -44399,6 +44408,10 @@ A command response with no output.
 A command response with the hex encoded output string @var{OUTPUT}.
 @end table
 
+Unlike most packets, this packet does not support
+@samp{E.@var{errtext}}-style textual error replies (@pxref{textual
+error reply}).
+
 (Note that the @code{qRcmd} packet's name is separated from the
 command by a @samp{,}, not a @samp{:}, contrary to the naming
 conventions above.  Please don't use this packet as a model for new
@@ -45455,8 +45468,6 @@ Reply:
 @table @samp
 @item OK
 Branch tracing has been enabled.
-@item E.errtext
-A badly formed request or an error was encountered.
 @end table
 
 @item Qbtrace:pt
@@ -45466,8 +45477,6 @@ Reply:
 @table @samp
 @item OK
 Branch tracing has been enabled.
-@item E.errtext
-A badly formed request or an error was encountered.
 @end table
 
 @item Qbtrace:off
@@ -45477,8 +45486,6 @@ Reply:
 @table @samp
 @item OK
 Branch tracing has been disabled.
-@item E.errtext
-A badly formed request or an error was encountered.
 @end table
 
 @item Qbtrace-conf:bts:size=@var{value}
@@ -45489,8 +45496,6 @@ Reply:
 @table @samp
 @item OK
 The ring buffer size has been set.
-@item E.errtext
-A badly formed request or an error was encountered.
 @end table
 
 @item Qbtrace-conf:pt:size=@var{value}
@@ -45501,8 +45506,6 @@ Reply:
 @table @samp
 @item OK
 The ring buffer size has been set.
-@item E.errtext
-A badly formed request or an error was encountered.
 @end table
 
 @end table

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