Re: Self-describing targets - a more concrete proposal

[Eli Zaretskii <eliz at gnu dot org>]

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

> 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?

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

> 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?

>    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?

Other than that, looks fine to me.