[remote] RFC: Replace qPart with qXfer

[Daniel Jacobowitz <drow at false dot org>]

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:OFFSET:DATA...'
     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