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>
Approved-By: Eli Zaretskii <eliz@gnu.org>
This commit is contained in:
Pedro Alves 2024-04-18 20:22:36 +01:00
parent aef11345e4
commit 2e703c09ec

View File

@ -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
@ -44128,14 +44058,6 @@ Address @var{address} is tagged.
@item @samp{00}
Address @var{address} is not tagged.
@item E @var{nn}
An error occurred whose code is @var{nn}. This means that address could not
be checked for some reason.
@item @w{}
An empty reply indicates that @samp{qIsAddressTagged} is not supported by the
stub.
@end table
@item QMemTags:@var{start address},@var{length}:@var{type}:@var{tag bytes}
@ -44171,20 +44093,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 +44157,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 +44193,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 +44218,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 +44253,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 +44286,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 +44368,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 +44389,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 +44413,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 +44428,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 +44456,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 +45176,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 +45394,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 +45438,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 +45641,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 +45705,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 +45821,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 +46029,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 +46117,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