RFC: Replace qPart with qXfer

I mentioned a few times on the lists that I planned to
replace the qPart
packet with an improved version, lately called qXfer.  Here
are the reasons:

  - qPart starts with "qP", another remote query
packet.  At least one stub
    (RedBoot) mistakenly responds to unknown packets
starting with qP as
    if they were corrupt qP packets, and there's no
realistic way to tell
    which is which.

  - The qPart packet is somewhat inefficient on an eight-bit
clean link,
    and the consensus on this list was that requiring an
eight-bit clean
    link for new remote protocol features is reasonable. 
The new packet
    is modelled after 'X' instead of 'm'/'M'.

  - The qPart packet has a built-in wasted round trip to
read a whole
    object.  The only way to indicate EOF is by itself, in a
reply
    with no data.  The new packet allows both data and an
EOF marker
    in the same packet.

The documentation for the new qXfer packets is below.  It is
extremely
similar to the qPart packets it replaces, but with those
differences above. 
The patches I've tested to make the switch also add
qXfer:auxv:read to
qSupported, so that we only query stubs which advertise the
feature.

As far as compatibility, I don't believe anything besides
gdbserver ever
implemented qPart:auxv:read.  CodeSourcery has at least two
different stubs
which implement other qPart packets, submission forthcoming,
but we can
update those stubs relatively easily.

Does anyone have any comments on this proposed change?  If
not, I plan to go
ahead with it in a week or two - probably two, since the GCC
Summit is next
week.  I already have it implemented and tested.


`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
     Read uninterpreted bytes from the target's special
data area
     identified by the keyword OBJECT.  Request LENGTH bytes
starting
     at OFFSET bytes into the data.  The content and
encoding of ANNEX
     is specific to the object; it can supply additional
details about
     what data to access.

     Here are the specific requests of this form defined so
far.  All
     `qXfer:OBJECT:read:...' requests use the same reply
formats,
     listed below.

    `qXfer:auxv:read::OFFSET,LENGTH'
          Access the target's "auxiliary
vector".  *Note auxiliary
          vector: OS Information, and see *Note
read-aux-vector-packet:
          Remote configuration.  Note ANNEX must be empty.

          This packet is not probed by default; the remote
stub must
          request it, by suppling an appropriate
`qSupported' response
          (*note qSupported:.

     Reply:
    `m DATA'
          Data DATA (*note Binary Data:: has been read from
the target.
          There may be more data at a higher address
(although it is
          permitted to return `m' even for the last valid
block of
          data, as long as at least one byte of data was
read).  DATA
          may have fewer bytes than the LENGTH in the
request.

    `l DATA'
          Data DATA (*note Binary Data:: has been read from
the target.
          There is no more data to be read.  DATA may have
fewer bytes
          than the LENGTH in the request.

    `l'
          The OFFSET in the request is at the end of the
data.  There
          is no more data to be read.

    `E00'
          The request was malformed, or ANNEX was invalid.

    `E NN'
          The offset was invalid, or there was an error
encountered
          reading the data.  NN is a hex-encoded `errno'
value.

    `'
          An empty reply indicates the OBJECT string was not
recognized
          by the stub, or that the object does not support
reading.

`qXfer:OBJECT:write:ANNEX:OFFSETATA...'
     Write uninterpreted bytes into the target's special
data area
     identified by the keyword OBJECT, starting at OFFSET
bytes into
     the data.  `DATA...' is the binary-encoded data (*note
Binary
     Data: to be
written.  The content and encoding of ANNEX is
     specific to the object; it can supply additional
details about
     what data to access.

     No requests of this form are presently in use.  This
specification
     serves as a placeholder to document the common format
that new
     specific request specifications ought to use.

     Reply:
    `NN'
          NN (hex encoded) is the number of bytes written. 
This may be
          fewer bytes than supplied in the request.

    `E00'
          The request was malformed, or ANNEX was invalid.

    `E NN'
          The offset was invalid, or there was an error
encountered
          writing the data.  NN is a hex-encoded `errno'
value.

    `'
          An empty reply indicates the OBJECT string was not
recognized
          by the stub, or that the object does not support
writing.

`qXfer:OBJECT:OPERATION:...'
     Requests of this form may be added in the future.  When
a stub does
     not recognize the OBJECT keyword, or its support for
OBJECT does
     not recognize the OPERATION keyword, the stub must
respond with an
     empty packet.



-- 
Daniel Jacobowitz
CodeSourcery

> Date: Wed, 21 Jun 2006 23:17:31 -0400
> From: Daniel Jacobowitz <drowfalse.org>
> 
> Does anyone have any comments on this proposed change?

I saw some irregularities and tried to guess what was wrong
in the
Texinfo sources; hopefully this will be useful.

>           Access the target's "auxiliary
vector".  *Note auxiliary
>           vector: OS Information, and see *Note
read-aux-vector-packet:
                                        ^^^
This "see" is redundant.  I suspect you used
"see ref"; if so, just
drop the "see" part.

>     `m DATA'
>           Data DATA (*note Binary Data:: has been read
from the target.
                                        ^^^
A missing right paren after pxref.

>     `l DATA'
>           Data DATA (*note Binary Data:: has been read
from the target.

Same here.

On Thu, Jun 22, 2006 at 10:54:42PM +0300, Eli Zaretskii
wrote:
> > Date: Wed, 21 Jun 2006 23:17:31 -0400
> > From: Daniel Jacobowitz <drowfalse.org>
> > 
> > Does anyone have any comments on this proposed
change?
> 
> I saw some irregularities and tried to guess what was
wrong in the
> Texinfo sources; hopefully this will be useful.

Thanks!

> >           Access the target's "auxiliary
vector".  *Note auxiliary
> >           vector: OS Information, and see *Note
read-aux-vector-packet:
>                                         ^^^
> This "see" is redundant.  I suspect you
used "see ref"; if so, just
> drop the "see" part.

(This was just moved from the qPart description.)

Confused.  The example in the Texinfo manual suggests
"see ref", and
says that you shouldn't just drop it, because e.g.
"in *Note" is
considered awkward.

http://www.gnu.org/software/t
exinfo/manual/texinfo/html_node/ref.html#index-ref-374

> >     `m DATA'
> >           Data DATA (*note Binary Data:: has been
read from the target.
>                                         ^^^
> A missing right paren after pxref.
> 
> >     `l DATA'
> >           Data DATA (*note Binary Data:: has been
read from the target.
> 
> Same here.

Right on both counts.  Fixed, thank you much.

-- 
Daniel Jacobowitz
CodeSourcery

> Date: Fri, 23 Jun 2006 13:14:19 -0400
> From: Daniel Jacobowitz <drowfalse.org>
> 
> > >           Access the target's
"auxiliary vector".  *Note auxiliary
> > >           vector: OS Information, and see
*Note read-aux-vector-packet:
> >                                         ^^^
> > This "see" is redundant.  I suspect
you used "see ref"; if so, just
> > drop the "see" part.
> 
> [...]
> 
> Confused.  The example in the Texinfo manual suggests
"see ref", and
> says that you shouldn't just drop it, because e.g.
"in *Note" is
> considered awkward.

The first example in the "ref" node indeed might
sound as if it says
that, but the truth is that ref exists precisely
_because_ you might
sometimes want to omit the "see" part, because
the sentence structure
requires that.

You shouldn't read that section of the Texinfo manual too
literally,
all it wants to say is that you should think about how the
sentence
will sound in both Info and printed versions, and apply your
best
judgement as to what would be best.

Karl, is it possible to reword that section along these
lines
(provided that you agree with my reasoning, of course)?

In the case in point, I think that "*Note FOO, and
*Note BAR" sounds
better than with the extra "see".  You don't
have the "in" in your
sentence, so the situation is different from what the manual
describes.  In the printed version, removing
"see" will produce this:

  See Section X.YZ [OS Information], page 123, and Section
A.BC
  [read-aux-vector], page 456.

which is okay, I think.

On Fri, Jun 23, 2006 at 09:06:30PM +0300, Eli Zaretskii
wrote:
> In the case in point, I think that "*Note FOO,
and *Note BAR" sounds
> better than with the extra "see".  You
don't have the "in" in your
> sentence, so the situation is different from what the
manual
> describes.  In the printed version, removing
"see" will produce this:
> 
>   See Section X.YZ [OS Information], page 123, and
Section A.BC
>   [read-aux-vector], page 456.
> 
> which is okay, I think.

Gotcha.  Thanks.

-- 
Daniel Jacobowitz
CodeSourcery

    Karl, is it possible to reword that section along these
lines
    (provided that you agree with my reasoning, of course)?

I do definitely agree.  I've always found that section in
the manual a
bit confusing myself, but I've also always gotten bogged
down when
trying to rewrite it.  Could you possibly take a crack at
writing a
first draft of a patch?

      See Section X.YZ [OS Information], page 123, and
Section A.BC
      [read-aux-vector], page 456.

    which is okay, I think.

Yes, I again agree, that reads best.

Thanks,
Karl

> Date: Sat, 24 Jun 2006 16:58:52 -0500
> From: karlfreefriends.org (Karl Berry)
> Cc: gdbsourceware.org
> 
> I do definitely agree.  I've always found that section
in the manual a
> bit confusing myself, but I've also always gotten
bogged down when
> trying to rewrite it.  Could you possibly take a crack
at writing a
> first draft of a patch?

I will try.