Re: Self-describing targets - a more concrete proposal

["Jim Blandy" <jimb at red-bean dot com>]

On 3/29/06, Eli Zaretskii <eliz@gnu.org> wrote:
> > Date: Wed, 29 Mar 2006 11:16:25 -0500
> > From: Daniel Jacobowitz <drow@false.org>
> >
> > I would appreciate comments on the sample and documentation
>
> Comments on the documentation are below.  Note that I needed to guess
> what was in the Texinfo source, since you posted the Info output, so I
> could have guessed wrong, and my comments might thus be off the target.

Thanks very much.  We wanted to get comments on the actual design
itself, so we posted legible text instead of a texinfo patch.  When it
comes down to posting the final patch, we'll certainly include the
patch to gdb.texinfo in the usual way.

> > GDB retrieves a target's self-description via the remote protocol using
> > a `qPart' request (*note the `qPart' request: qPart request.) of the form:
>
> This cross-reference looks awkward.  I'm guessing that Jim used a
> 2-argument form of a @pxref here.  But the second arg is redundant
> here because it is a substring of the 1st.  Am I missing some valid
> reason for using the second argument?

It does look awkward.  I wanted to use @code for qPart.  But I'm not
sure it's worth it; I've simplified it and it seems okay.

> >      qPart:features:read:ANNEX:OFFSET,LENGTH
> >    where ANNEX is the string `target.xml'.  The OFFSET and LENGTH
>
> The last line should have a @noindent before it.

Done.

> > parameters are the offset into the description and the number of bytes
> > to transfer, as for other `qPart' requests.
> >
> >    The `target.xml' annex contains an XML document describing the
> > target's features; its form is described in *Note Self-Description
> > Format::.
>
> There's something I don't understand here: is "target.xml" a literal
> fixed string that will _always_ appear in the above packet?  If it is,
> why do we need to mention its name?

We talk about GDB retrieving other annexes (annices?) later; that
request is used for all of them.  I'll try to rephrase this.

> >    To reduce protocol overhead, a target may supply a special annex
> > named `CHECKSUMS' that provides 160-bit SHA1 checksum values for the
> > annexes it has available.  The `CHECKSUMS' annex contains a series of
> > newline-terminated lines, each of which contains a 40-digit hexidecimal
> > checksum, two spaces, and the name of an annex with the given checksum.
> > Here is an example `CHECKSUM' annex:
> >      68c94ffc34f8ad2d7bfae3f5a6b996409211c1b1  target.xml
> >      0e8e850b0580fbaaa0872326cb1b8ad6adda9b0d  mmu.xml
> >      00f22e5f971ccec05c2acce98caf8cff4343c8cf  fpu.xml
>
> Shouldn't we document how to generate a checksum for a file?

SHA-1 is the name of the specific hash function that must be used. 
I'll clear this up.

> Other than that, looks fine to me.

As always, thanks for the review!