Re: [PATCH] Document short responses to qXfer:object:read.

Eli Zaretskii
2016-05-27T13:21:39Z

> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <palves@redhat.com>
> Date: Fri, 27 May 2016 09:55:03 +0100
>
> On 05/27/2016 09:35 AM, Eli Zaretskii wrote:
>
> > Finally, it looks to me that we should move the description of the
> > responses to precede the details of the 'read' requests, since the
> > list of those requests is very long, and thus the promised description
> > of the responses "below" is very far away, which IMO gets in the way
> > of reading and comprehending the issue.
>
> Fully agreed.

The patch for that is below; OK?

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 34b9527..3abec90 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2016-05-27 Eli Zaretskii <eliz@gnu.org>
+
+ * gdb.texinfo (General Query Packets): Move the description of the
+ response before the long list of the specific 'read' requests.
+
2016-05-23 Tom Tromey <tom@tromey.com>

* python.texi (Basic Python): Document gdb.breakpoints return.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 8f1ad4e..9310365 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -37251,9 +37251,40 @@
encoding of @var{annex} is specific to @var{object}; it can supply
additional details about what data to access.

+Reply:
+@table @samp
+@item m @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the
+target. There may be more data at a higher address (although
+it is permitted to return @samp{m} even for the last valid
+block of data, as long as at least one byte of data was read).
+It is possible for @var{data} to have fewer bytes than the @var{length} in the
+request.
+
+@item l @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the target.
+There is no more data to be read. It is possible for @var{data} to
+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
@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
-formats, listed below.
+formats, listed above.

@table @samp
@item qXfer:auxv:read::@var{offset},@var{length}
@@ -37458,37 +37489,6 @@

@end table

-Reply:
-@table @samp
-@item m @var{data}
-Data @var{data} (@pxref{Binary Data}) has been read from the
-target. There may be more data at a higher address (although
-it is permitted to return @samp{m} even for the last valid
-block of data, as long as at least one byte of data was read).
-It is possible for @var{data} to have fewer bytes than the @var{length} in the
-request.
-
-@item l @var{data}
-Data @var{data} (@pxref{Binary Data}) has been read from the target.
-There is no more data to be read. It is possible for @var{data} to
-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
-
@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
@cindex write data into object, remote request
@anchor{qXfer write}