Re: Flash support part 3: documentation

[Eli Zaretskii <eliz at gnu dot org>]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Fri, 21 Jul 2006 16:04:01 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > >              @value{GDBN} groups flash memory programming operations
> > > +together, and sends a @samp{vFlashDone} request after each group; the
> > > +to delay erase operation until the @samp{vFlashDone} packet is received.
> >
> >    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Something is wrong here.
> 
> Yes, this is the revised wording:
> 
>  @value{GDBN} groups flash memory programming operations
> together, and sends a @samp{vFlashDone} request after each group; the
> stub is allowed to delay erase operation until the @samp{vFlashDone}
> packet is received.

This replacement is fine with me.

> > >                                  The set of @samp{vFlashWrite} packets
> > > +preceding a @samp{vFlashDone} packet must not overlap
> >
> > It is not clear what does ``must not overlap'' mean here.  Taken
> > verbatim, the sentence seems to say that the _packets_ must not
> > overlap, but is that really what you want to say?
> 
> No, I meant something more to this:
> 
> The memory ranges specified by
> @samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
> not overlap, and must appear in order of increasing addresses.

Yes, I guessed something like that.  This wording is okay.

> > >                                  Writes may fall outside the regions
> > > +given by the previously transmitted @samp{vFlashErase} packets, but
> > > +the results are unpredictable if a given area of flash is rewritten
> > > +without being erased.
> >
> > I'd rephrase this as follows:
> >
> >   If the series of packets write data outside the region erased by the
> >   preceding @samp{vFlashErase} packets, the results are unpredictable.
> 
> I think this is slightly different. For example, target might have some extra 
> fast method to erase entire flash, that gdb does not know about, but that 
> user can invoke in some. Then, it's ok to send vFlashWrite without any 
> vFlashErase packets at all. So the constraint is that area of flash is in 
> erased state when vFlashWrite arrives, but not that vFlashErase was seen.

In that case, how about the following?

   If the series of packets write data outside the region that was
   erased either by the preceding @samp{vFlashErase} packets or by
   some other target-specific method, the results are unpredictable.

> > > +@var{annex} must be empty.
> >
> > There's no @var{annex} in the @item that gives the packet's syntax.
> 
> I must admit that I've copied this sentence from description of 
> qXfer:auxv:read. While you're right that @var{annex} is not present in 
> description of qXfer:memory-map:read, it's present in description of generic 
> syntax of qXfer packet. The point of this sentence is to emphasise that annex
> part of generic qXfer packet should be empty for memory map.

Then just say something like "the annex part of generic qXfer packet
should be empty for memory map", and add a cross-reference to where
qXfer is described.  But do not use @var{annex}.

> > > +@example
> >
> > Please use @smallexample everywhere.
> 
> What is the difference between them?

@smallexample uses a slightly smaller font, and thus can squeeze more
text into each line without overflowing the page margins (in the
printed version).

> Do you mean that smallexample should be used everywhere in gdb docs?

Yes.

> I attach the revised patch, is it better now?

Yes, thanks.