Re: RFC: Add named errors and messages to remote protocol

[Jim Blandy <jimb at codesourcery dot com>]

Daniel Jacobowitz <drow@false.org> writes:
> On Mon, Jun 18, 2007 at 05:11:16PM -0700, Jim Blandy wrote:
>> 
>> Here's a patch we've just started using internally at CodeSourcery
>> which implements something that's been discussed on and off for years:
>> extending the remote protocol to support named errors, and to provide
>> error messages along with errors.
>> 
>> This is a pretty rough patch.  Probably all the sites in remote.c that
>> check for errors should call error_from_remote.  But hopefully the
>> basic idea is clear enough to critique.
>
> This is a remote protocol change; I believe the custom is to post just
> the documentation or a description on gdb@ first in case anyone has
> comments.

Okay.  Here's the new node to be added to the remote protocol section
of the manual.  It goes before the packet descriptions, which are then
simplified by removing the descriptions of the standard replies.  The
description of the notation we use to describe packet formats also
gets moved above this.


@node Standard Replies
@section Standard Replies

The remote protocol specifies a few standard replies.  All commands
support these, except as noted in the individual command descriptions.

@table @samp

@item
@cindex empty response, for unsupported packets
@cindex unsupported packets, empty response for
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.

A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
@samp{c}, and @samp{s} @var{command}s.  All other @var{command}s are
optional.
on that response (but see also @ref{qSupported}).

@item 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; GDB usually ignores the numbers, or
displays them to the user without further interpretation.

@item E.@var{name}@r{[}.@var{message}@r{]}
An error has occurred; @var{name} is the name of the error.  The name
may contain letters, numbers, and @samp{-} characters.  If present,
@var{message} is an error message, encoded using the escaped eight-bit
conventions for binary data described above.

Except as noted, named errors may only be returned to commands
documented to expect them; this ensures that older stubs can interact
with newer versions of @value{GDBN}, even when interpretations for
named errors have been added to the protocol.

The protocol uses the following error names:

@table @samp

@item fatal
A fatal error has occurred; the stub will be unable to interact
further with @value{GDBN}.  Fatal errors should always include a
message explaining their cause.

Any command may return this error.

@item memtype
The memory addressed is of the wrong type for the given command.  For
example, a @samp{vFlashWrite} command applied to non-flash memory
elicits an @samp{E.memtype} error response.

@end table
@end table