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

[David Taylor <dtaylor at emc dot com>]

> From: Eli Zaretskii <eliz at gnu dot org>
> Date: Thu, 26 May 2016 22:31:40 +0300
> 
> > From: David Taylor <dtaylor@emc.com>
> > cc: dtaylor@emc.com
> > Date: Thu, 26 May 2016 14:10:37 -0400
> > 
> > +2016-05-26  David Taylor  <dtaylor@emc.com>
> > +
> > +	* gdb.texinfo (General Query Packets): Document treatment of short
> > +	qXfer responses and EOF indication.
> > +
> >  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..c674c7a 100644
> > --- a/gdb/doc/gdb.texinfo
> > +++ b/gdb/doc/gdb.texinfo
> > @@ -37251,6 +37251,11 @@ starting at @var{offset} bytes into the data.  The content and
> >  encoding of @var{annex} is specific to @var{object}; it can supply
> >  additional details about what data to access.
> >  
> > +The target is permitted to return a short response.  The response is
> > +considered to cover the range @var{offset} (inclusive) to @var{offset}
> > ++ @var{response length} (exclusive).  End of file is indicated by a
> > +zero length response.
> > +
> >  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.
> 
> Thanks.  However, I have difficulty understanding what this text is
> trying to convey.  Problematic words are "permitted" and "short" --
> they don't seem to be related to anything around this text, and are
> not explained by the text itself.  I also don't see why EOF is
> important here, or even related.
> 
> Could you perhaps explain in your own words what is this about, and
> what the text lacks without this paragraph?  I might then propose a
> more clear wording.
> 
> Thanks.

The qXfer:object:read packet contains an offset and a length.  It says
for <object>, starting at offset <offset>, send me <length> characters.

When 'reading' object <object>, GDB starts at offset 0 and sends
qXfer:<object>:read packets with progressively higher offsets until it
gets everything.

If it was a file, then a read of less than the requested amount (aka a
short read) would be interpreted as having reached the end of the file.

These objects aren't really files.  And returning less than requested
does not mean that the end of the object has been reached.

GDB's next 'read' from 'object' will be at offset

    <offset> + <returned amount>

NOT at

    <offset> + <requested amount>

The fact that sending back less than requested is okay (i.e., does not
say to GDB -- hey, that's it, there is no more) and that the next
request starts where the last response ended (i.e., offset + returned
amount) rather than where the last request ended (i.e., offset +
requested amount) makes life easier on the remote stub implementer.

Hope that clarifies somewhat.  Now, can we come up with better wording?

David