[remote] RFC: Replace qPart with qXfer

[remote] RFC: Replace qPart with qXfer

[Daniel Jacobowitz]

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

Re: [remote] RFC: Replace qPart with qXfer

[Vladimir Prus]

Daniel Jacobowitz wrote:

> `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.

Why do we need OBJECT+ANNEX addressing and opposed to just OBJECT? If
'OBJECT' is just a string, can't we push anything in it, without needed
extra level of addressing?

- Volodya

What's the difference between gdb arm targets?

[Dave Murphy]

Hi,

Is there any significant difference between a gdb targeted for 
arm-linux, arm-eabi and arm-elf? Is it possible to combine all 3 targets 
within one build?

Dave

Re: What's the difference between gdb arm targets?

[Daniel Jacobowitz]

Please don't reply to random messages to post to the list.  In this day
and age, everyone is expected to use a mail reader which supports
threading; you've attached yourself to an unrelated conversation.

On Thu, Jun 22, 2006 at 10:04:47AM +0100, Dave Murphy wrote:
> Hi,
> 
> Is there any significant difference between a gdb targeted for 
> arm-linux, arm-eabi and arm-elf? Is it possible to combine all 3 targets 
> within one build?

The defaults are different.  I believe that as long as you give GDB
an ELF file every time, it will figure out the right behavior.  To
include the Linux support code you need to configure for arm-linux, but
the other two don't have their own support code.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [remote] RFC: Replace qPart with qXfer

[Daniel Jacobowitz]

On Thu, Jun 22, 2006 at 12:41:45PM +0400, Vladimir Prus wrote:
> Daniel Jacobowitz wrote:
> 
> > `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.
> 
> Why do we need OBJECT+ANNEX addressing and opposed to just OBJECT? If
> 'OBJECT' is just a string, can't we push anything in it, without needed
> extra level of addressing?

I inherited this from qPart, but I think it's a good idea - I actually
use it for XML descriptions.

OBJECT is the base of the request.  All "qXfer:OBJECT:read" requests
for a single value of OBJECT are expected to be handled in the same
way.  A stub which supports this OBJECT should return a non-empty
response.  ANNEX is a bit of auxilliary data, in case there's more than
one instance of OBJECT.

For instance:

qXfer:features:read:target.xml:0,100
  Read the overall target description.
qXfer:features:read:CHECKSUMS:0,100
  Read any precomputed SHA-1 checksums for target description files.
qXfer:features:read:foo.xml:0,100
  Read a specific XML file referenced using XInclude.

And then, if one of those is unavailable, it can return either "l" (no
data), or "E00" (annex unknown, or something else wrong with the
packet).

Sure, you could call that "qXfer:features-target.xml:read".  But it's
trickier for the target stub to match it in that case.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [remote] RFC: Replace qPart with qXfer

[Eli Zaretskii]

> Date: Wed, 21 Jun 2006 23:17:31 -0400
> From: Daniel Jacobowitz <drow@false.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.

Re: [remote] RFC: Replace qPart with qXfer

[Daniel Jacobowitz]

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 <drow@false.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/texinfo/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

Re: [remote] RFC: Replace qPart with qXfer

[Eli Zaretskii]

> Date: Fri, 23 Jun 2006 13:14:19 -0400
> From: Daniel Jacobowitz <drow@false.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.

Re: [remote] RFC: Replace qPart with qXfer

[Daniel Jacobowitz]

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

Re: [remote] RFC: Replace qPart with qXfer

[Karl Berry]

    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

Re: [remote] RFC: Replace qPart with qXfer

[Eli Zaretskii]

> Date: Sat, 24 Jun 2006 16:58:52 -0500
> From: karl@freefriends.org (Karl Berry)
> Cc: gdb@sourceware.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.