Flash support part 3: documentation

Flash support part 3: documentation

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 512 bytes --]


This patch finishes the flash support work by adding documentation for all new
packets, and by describing the format of XML memory map used in the remote 
protocol.

- Volodya

2006-07-20  Vladimir Prus  <vladimir@codesourcery.com>

	* gdb.texinfo (Packets): Document vFlashErase,
	vFlashWrite and vFlashDone packets.
	(General Query Packets): Document qXfer:memory-map:read.
	Add a new feature for qXfer:memory-map:read.
	(Memory map format): New section.
	(Target Commands): Mention that gdb can write flash.

[-- Attachment #2: flash_docs.diff --]
[-- Type: text/x-diff, Size: 5921 bytes --]

=== gdb.texinfo
==================================================================
--- gdb.texinfo	(revision 177)
+++ gdb.texinfo	(revision 293)
@@ -12195,6 +12195,9 @@
 specifies a fixed address.
 @c FIXME! This would be a good place for an xref to the GNU linker doc.
 
+Depending on the remote side capabilities, @value{GDBN} may be able to
+load programs into flash memory.
+
 @code{load} does not repeat if you press @key{RET} again after using it.
 @end table
 
@@ -22497,6 +22500,7 @@
 * Interrupts::
 * Examples::
 * File-I/O remote protocol extension::
+* Memory map format::
 @end menu
 
 @node Overview
@@ -22995,6 +22999,55 @@
 The @samp{vCont} packet is not supported.
 @end table
 
+@item vFlashErase:@var{addr},@var{length}
+@cindex @samp{vFlashErase} packet
+Direct the stub to erase @var{length} bytes of flash starting at
+@var{addr}.  The region may enclose any number of flash blocks, but
+its start and end must fall on block boundaries, as indicated by the
+flash block size appearing in the memory map (@pxref{Memory map
+format}).  @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.
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashWrite:@var{addr}:@var{XX@dots{}}
+@cindex @samp{vFlashWrite} packet
+Direct the stub to write data to flash address @var{addr}.  The data
+is passed binary form using the same encoding as for the @samp{X}
+packet (@pxref{Binary Data}).  The set of @samp{vFlashWrite} packets
+preceding a @samp{vFlashDone} packet must not overlap, and must appear
+in order of increasing addresses.  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.
+
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E.memtype
+for vFlashWrite addressing non-flash memory
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashDone
+@cindex @samp{vFlashDone} packet
+Indicate to the stub that flash programming operation is finished.
+The stub is permitted to delay or batch the effects of a group of
+@samp{vFlashErase} and @samp{vFlashWrite} packets until a
+@samp{vFlashDone} packet is received.  The contents of the affected
+regions of flash memory are unpredictable until the @samp{vFlashDone}
+request is completed.
+
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
 @cindex @samp{X} packet
@@ -23534,6 +23587,11 @@
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:memory-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @end multitable
 
 These are the currently defined stub features, in more detail:
@@ -23652,6 +23710,17 @@
 by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
 @end table
 
+@table @samp
+@item qXfer:memory-map:read::@var{offset},@var{length}
+@anchor{qXfer memory map read}
+Access the target's @dfn{memory-map}.  @xref{Memory map format}. The
+@var{annex} must be empty.
+
+
+This packet is not probed by default; the remote stub must request it,
+by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
 Reply:
 @table @samp
 @item m @var{data}
@@ -25132,6 +25201,84 @@
 <- @code{T02}
 @end smallexample
 
+@node Memory map format
+@section Memory map format
+@cindex Memory map format
+
+To be able to write into flash memory, @value{GDBN} needs to obtain
+memory map from the target.  This section describes the format of the
+memory map.
+
+The memory map is obtained using the @samp{qXfer:memory-map:read}
+(@pxref{qXfer memory map read}) packet and is an XML document that
+lists memory regions. The top-level structure of the document is shown below:
+
+@example
+<?xml version="1.0"?>
+<!DOCTYPE memory-map
+          PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+                 "http://sourceware.org/gdb/gdb-memory-map.dtd">
+<memory-map>
+    region...
+</memory-map>
+@end example
+
+Each region can be either:
+
+@itemize
+
+@item A region of RAM starting at @var{addr} and extending for @var{length}
+bytes from there:
+
+@example
+<memory type="ram" start="addr" length="length"/>
+@end example
+
+
+@item A region of read-only memory:
+
+@example
+<memory type="rom" start="addr" length="length"/>
+@end example
+
+
+@item A region of flash memory, with erasure blocks @var{blocksize}
+bytes in length:
+
+@example
+<memory type="flash" start="addr" length="length">
+  <property name="blocksize">blocksize</property>
+</memory>
+@end example
+
+@end itemize
+
+Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
+by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
+packets to write to addresses in such ranges.
+
+The formal DTD for memory map format is given below:
+
+@example
+<!-- ............................................................... -->
+<!-- Memory Map XML DTD ............................................ -->
+<!-- File: memory-map.dtd .......................................... -->
+<!-- ............................................................... -->
+<!-- memory-map.dtd -->
+<!-- memory-map: Root element with versioning -->
+<!ELEMENT memory-map (memory | property)>
+<!ATTLIST memory-map    version CDATA   #FIXED  "1.0.0">
+<!ELEMENT memory (property)>
+<!-- memory: Specifies a memory region, and its type, or device. -->
+<!ATTLIST memory        type    CDATA   #REQUIRED
+                        start   CDATA   #REQUIRED
+                        length  CDATA   #REQUIRED
+                        device  CDATA   #IMPLIED>
+<!-- property: Generic attribute tag -->
+<!ELEMENT property (#PCDATA | property)*>
+<!ATTLIST property      name    CDATA   #REQUIRED>
+@end example
+
 @include agentexpr.texi
 
 @include gpl.texi

Re: Flash support part 3: documentation

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Thu, 20 Jul 2006 13:43:32 +0400
> 
> This patch finishes the flash support work by adding documentation for all new
> packets, and by describing the format of XML memory map used in the remote 
> protocol.

Thanks.  My comments are below.

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

> +Direct the stub to write data to flash address @var{addr}.  The data
> +is passed binary form using the same encoding as for the @samp{X}
      ^^^^^^^^^^^^^^^^^^
You meant "passed IN binary form", right?

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

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

> +@item E.memtype
> +for vFlashWrite addressing non-flash memory

What is "E.memtype"? is it a literal string?

> +@table @samp
> +@item qXfer:memory-map:read::@var{offset},@var{length}
> +@anchor{qXfer memory map read}
> +Access the target's @dfn{memory-map}.  @xref{Memory map format}. The
                                                                  ^^^
Two spaces here, please.

> +@var{annex} must be empty.

There's no @var{annex} in the @item that gives the packet's syntax.

> +by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
      ^^^^^^^^
A typo.

> +@node Memory map format
> +@section Memory map format
> +@cindex Memory map format

Please start @cindex entries with a lower-case letter.

> +lists memory regions. The top-level structure of the document is shown below:
                       ^^^
Need two spaces here.

> +@example

Please use @smallexample everywhere.

> +@itemize
> +
> +@item A region of RAM starting at @var{addr} and extending for @var{length}

An @item in an @itemize list should be alone on its line; the text
should start on the following line, like this:

  @item
  A region of RAM starting at @var{addr} and extending ...

> +<memory type="ram" start="addr" length="length"/>

Shouldn't this end with "/memory>"?

> +@example
> +<memory type="rom" start="addr" length="length"/>
> +@end example
> +
> +
> +@item A region of flash memory, with erasure blocks @var{blocksize}
> +bytes in length:
> +
> +@example
> +<memory type="flash" start="addr" length="length">
> +  <property name="blocksize">blocksize</property>
> +</memory>
> +@end example

The "addr", "blocksize" and "length" here refer to the values of
@var{addr}, @var{blocksize}, etc., right?  If so, you should use @var
in them.

> +Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
                          ^^^^
Two spaces.

> +@example
> +<!-- ............................................................... -->
> +<!-- Memory Map XML DTD ............................................ -->
> +<!-- File: memory-map.dtd .......................................... -->
> +<!-- ............................................................... -->

Please make these lines shorter: they will overflow the page margins,
even with @smallexample, since TeX doesn't hyphenate inside @example.
In general, anything longer than 64 characters in a @smallexample is
bad.

Re: Flash support part 3: documentation

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 5801 bytes --]

On Thursday 20 July 2006 23:57, Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Thu, 20 Jul 2006 13:43:32 +0400
> >
> > This patch finishes the flash support work by adding documentation for
> > all new packets, and by describing the format of XML memory map used in
> > the remote protocol.
>
> Thanks.  My comments are below.
>
> >              @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.

> > +Direct the stub to write data to flash address @var{addr}.  The data
> > +is passed binary form using the same encoding as for the @samp{X}
>
>       ^^^^^^^^^^^^^^^^^^
> You meant "passed IN binary form", right?

Right.

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

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

> > +@item E.memtype
> > +for vFlashWrite addressing non-flash memory
>
> What is "E.memtype"? is it a literal string?

Yes, it's a literal string, just like "OK" two lines above.

> > +@table @samp
> > +@item qXfer:memory-map:read::@var{offset},@var{length}
> > +@anchor{qXfer memory map read}
> > +Access the target's @dfn{memory-map}.  @xref{Memory map format}. The
>
>                                                                   ^^^
> Two spaces here, please.

Ok.

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

>
> > +by suppling an appropriate @samp{qSupported} response
> > (@pxref{qSupported}).
>
>       ^^^^^^^^
> A typo.
>
> > +@node Memory map format
> > +@section Memory map format
> > +@cindex Memory map format
>
> Please start @cindex entries with a lower-case letter.
>
> > +lists memory regions. The top-level structure of the document is shown
> > below:
>
>                        ^^^
> Need two spaces here.
>
> > +@example
>
> Please use @smallexample everywhere.

What is the difference between them? Do you mean thatsmallexample should be 
used everywhere in gdb docs? 

> > +@itemize
> > +
> > +@item A region of RAM starting at @var{addr} and extending for
> > @var{length}
>
> An @item in an @itemize list should be alone on its line; the text
> should start on the following line, like this:
>
>   @item
>   A region of RAM starting at @var{addr} and extending ...
>
> > +<memory type="ram" start="addr" length="length"/>
>
> Shouldn't this end with "/memory>"?

No, there's "/>" at the end of the element. That's abbreviated XML syntax for 
element without children.

>
> > +@example
> > +<memory type="rom" start="addr" length="length"/>
> > +@end example
> > +
> > +
> > +@item A region of flash memory, with erasure blocks @var{blocksize}
> > +bytes in length:
> > +
> > +@example
> > +<memory type="flash" start="addr" length="length">
> > +  <property name="blocksize">blocksize</property>
> > +</memory>
> > +@end example
>
> The "addr", "blocksize" and "length" here refer to the values of
> @var{addr}, @var{blocksize}, etc., right?  If so, you should use @var
> in them.

Ok.

>
> > +Regions must not overlap. @value{GDBN} assumes that areas of memory not
> > covered
>
>                           ^^^^
> Two spaces.
>
> > +@example
> > +<!-- ............................................................... -->
> > +<!-- Memory Map XML DTD ............................................ -->
> > +<!-- File: memory-map.dtd .......................................... -->
> > +<!-- ............................................................... -->
>
> Please make these lines shorter: they will overflow the page margins,
> even with @smallexample, since TeX doesn't hyphenate inside @example.
> In general, anything longer than 64 characters in a @smallexample is
> bad.

I've trimmed this to 60 characters.

I attach the revised patch, is it better now?

Thanks,
Volodya






[-- Attachment #2: flash_docs.diff --]
[-- Type: text/x-diff, Size: 6030 bytes --]

=== gdb.texinfo
==================================================================
--- gdb.texinfo	(revision 177)
+++ gdb.texinfo	(revision 296)
@@ -12195,6 +12195,9 @@
 specifies a fixed address.
 @c FIXME! This would be a good place for an xref to the GNU linker doc.
 
+Depending on the remote side capabilities, @value{GDBN} may be able to
+load programs into flash memory.
+
 @code{load} does not repeat if you press @key{RET} again after using it.
 @end table
 
@@ -22497,6 +22500,7 @@
 * Interrupts::
 * Examples::
 * File-I/O remote protocol extension::
+* Memory map format::
 @end menu
 
 @node Overview
@@ -22995,6 +22999,56 @@
 The @samp{vCont} packet is not supported.
 @end table
 
+@item vFlashErase:@var{addr},@var{length}
+@cindex @samp{vFlashErase} packet
+Direct the stub to erase @var{length} bytes of flash starting at
+@var{addr}.  The region may enclose any number of flash blocks, but
+its start and end must fall on block boundaries, as indicated by the
+flash block size appearing in the memory map (@pxref{Memory map
+format}).  @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.
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashWrite:@var{addr}:@var{XX@dots{}}
+@cindex @samp{vFlashWrite} packet
+Direct the stub to write data to flash address @var{addr}.  The data
+is passed in binary form using the same encoding as for the @samp{X}
+packet (@pxref{Binary Data}).  The memory ranges specified by
+@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
+not overlap, and must appear in order of increasing addresses.  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.
+
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E.memtype
+for vFlashWrite addressing non-flash memory
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashDone
+@cindex @samp{vFlashDone} packet
+Indicate to the stub that flash programming operation is finished.
+The stub is permitted to delay or batch the effects of a group of
+@samp{vFlashErase} and @samp{vFlashWrite} packets until a
+@samp{vFlashDone} packet is received.  The contents of the affected
+regions of flash memory are unpredictable until the @samp{vFlashDone}
+request is completed.
+
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
 @cindex @samp{X} packet
@@ -23534,6 +23588,11 @@
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:memory-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @end multitable
 
 These are the currently defined stub features, in more detail:
@@ -23652,6 +23711,17 @@
 by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
 @end table
 
+@table @samp
+@item qXfer:memory-map:read::@var{offset},@var{length}
+@anchor{qXfer memory map read}
+Access the target's @dfn{memory-map}.  @xref{Memory map format}.  The
+@var{annex} must be empty.
+
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
 Reply:
 @table @samp
 @item m @var{data}
@@ -25132,6 +25202,88 @@
 <- @code{T02}
 @end smallexample
 
+@node Memory map format
+@section Memory map format
+@cindex memory map format
+
+To be able to write into flash memory, @value{GDBN} needs to obtain
+memory map from the target.  This section describes the format of the
+memory map.
+
+The memory map is obtained using the @samp{qXfer:memory-map:read}
+(@pxref{qXfer memory map read}) packet and is an XML document that
+lists memory regions.  The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE memory-map
+          PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+                 "http://sourceware.org/gdb/gdb-memory-map.dtd">
+<memory-map>
+    region...
+</memory-map>
+@end smallexample
+
+Each region can be either:
+
+@itemize
+
+@item 
+A region of RAM starting at @var{addr} and extending for @var{length}
+bytes from there:
+
+@smallexample
+<memory type="ram" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item 
+A region of read-only memory:
+
+@smallexample
+<memory type="rom" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item 
+A region of flash memory, with erasure blocks @var{blocksize}
+bytes in length:
+
+@smallexample
+<memory type="flash" start="@var{addr}" length="@var{length}">
+  <property name="blocksize">@var{blocksize}</property>
+</memory>
+@end smallexample
+
+@end itemize
+
+Regions must not overlap.  @value{GDBN} assumes that areas of memory not covered
+by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
+packets to write to addresses in such ranges.
+
+The formal DTD for memory map format is given below:
+
+@smallexample
+<!-- ................................................... -->
+<!-- Memory Map XML DTD ................................ -->
+<!-- File: memory-map.dtd .............................. -->
+<!-- .................................... .............. -->
+<!-- memory-map.dtd -->
+<!-- memory-map: Root element with versioning -->
+<!ELEMENT memory-map (memory | property)>
+<!ATTLIST memory-map    version CDATA   #FIXED  "1.0.0">
+<!ELEMENT memory (property)>
+<!-- memory: Specifies a memory region, 
+             and its type, or device. -->
+<!ATTLIST memory        type    CDATA   #REQUIRED
+                        start   CDATA   #REQUIRED
+                        length  CDATA   #REQUIRED
+                        device  CDATA   #IMPLIED>
+<!-- property: Generic attribute tag -->
+<!ELEMENT property (#PCDATA | property)*>
+<!ATTLIST property      name    CDATA   #REQUIRED>
+@end smallexample
+
 @include agentexpr.texi
 
 @include gpl.texi

Re: Flash support part 3: documentation

[Eli Zaretskii]

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

Re: Flash support part 3: documentation

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 2186 bytes --]

On Friday 21 July 2006 19:33, Eli Zaretskii wrote:

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

Strictly speaking, there might be several disjoint regions. How about this:

   If a packet writes to an address that was neither erased by a preceding
   @samp{vFlashErase} packet nor 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}.

Okay.

Here's yet another revision of the patch.

Thanks,
Volodya

[-- Attachment #2: flash_docs.diff --]
[-- Type: text/x-diff, Size: 6446 bytes --]

=== gdb.texinfo
==================================================================
--- gdb.texinfo	(revision 177)
+++ gdb.texinfo	(revision 297)
@@ -12195,6 +12195,9 @@
 specifies a fixed address.
 @c FIXME! This would be a good place for an xref to the GNU linker doc.
 
+Depending on the remote side capabilities, @value{GDBN} may be able to
+load programs into flash memory.
+
 @code{load} does not repeat if you press @key{RET} again after using it.
 @end table
 
@@ -22497,6 +22500,7 @@
 * Interrupts::
 * Examples::
 * File-I/O remote protocol extension::
+* Memory map format::
 @end menu
 
 @node Overview
@@ -22995,6 +22999,56 @@
 The @samp{vCont} packet is not supported.
 @end table
 
+@item vFlashErase:@var{addr},@var{length}
+@cindex @samp{vFlashErase} packet
+Direct the stub to erase @var{length} bytes of flash starting at
+@var{addr}.  The region may enclose any number of flash blocks, but
+its start and end must fall on block boundaries, as indicated by the
+flash block size appearing in the memory map (@pxref{Memory map
+format}).  @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.
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashWrite:@var{addr}:@var{XX@dots{}}
+@cindex @samp{vFlashWrite} packet
+Direct the stub to write data to flash address @var{addr}.  The data
+is passed in binary form using the same encoding as for the @samp{X}
+packet (@pxref{Binary Data}).  The memory ranges specified by
+@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
+not overlap, and must appear in order of increasing addresses.  If a
+packet writes to an address that was neither erased by a preceding
+@samp{vFlashErase} packet nor by some other target-specific method,
+the results are unpredictable.  
+
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E.memtype
+for vFlashWrite addressing non-flash memory
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashDone
+@cindex @samp{vFlashDone} packet
+Indicate to the stub that flash programming operation is finished.
+The stub is permitted to delay or batch the effects of a group of
+@samp{vFlashErase} and @samp{vFlashWrite} packets until a
+@samp{vFlashDone} packet is received.  The contents of the affected
+regions of flash memory are unpredictable until the @samp{vFlashDone}
+request is completed.
+
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
 @cindex @samp{X} packet
@@ -23534,6 +23588,11 @@
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:memory-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @end multitable
 
 These are the currently defined stub features, in more detail:
@@ -23631,6 +23690,7 @@
 @item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
 @cindex read special object, remote request
 @cindex @samp{qXfer} packet
+@anchor{qXfer read}
 Read uninterpreted bytes from the target's special data area
 identified by the keyword @var{object}.  Request @var{length} bytes
 starting at @var{offset} bytes into the data.  The content and
@@ -23652,6 +23712,17 @@
 by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
 @end table
 
+@table @samp
+@item qXfer:memory-map:read::@var{offset},@var{length}
+@anchor{qXfer memory map read}
+Access the target's @dfn{memory-map}.  @xref{Memory map format}.  The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
 Reply:
 @table @samp
 @item m @var{data}
@@ -25132,6 +25203,88 @@
 <- @code{T02}
 @end smallexample
 
+@node Memory map format
+@section Memory map format
+@cindex memory map format
+
+To be able to write into flash memory, @value{GDBN} needs to obtain
+memory map from the target.  This section describes the format of the
+memory map.
+
+The memory map is obtained using the @samp{qXfer:memory-map:read}
+(@pxref{qXfer memory map read}) packet and is an XML document that
+lists memory regions.  The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE memory-map
+          PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+                 "http://sourceware.org/gdb/gdb-memory-map.dtd">
+<memory-map>
+    region...
+</memory-map>
+@end smallexample
+
+Each region can be either:
+
+@itemize
+
+@item 
+A region of RAM starting at @var{addr} and extending for @var{length}
+bytes from there:
+
+@smallexample
+<memory type="ram" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item 
+A region of read-only memory:
+
+@smallexample
+<memory type="rom" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item 
+A region of flash memory, with erasure blocks @var{blocksize}
+bytes in length:
+
+@smallexample
+<memory type="flash" start="@var{addr}" length="@var{length}">
+  <property name="blocksize">@var{blocksize}</property>
+</memory>
+@end smallexample
+
+@end itemize
+
+Regions must not overlap.  @value{GDBN} assumes that areas of memory not covered
+by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
+packets to write to addresses in such ranges.
+
+The formal DTD for memory map format is given below:
+
+@smallexample
+<!-- ................................................... -->
+<!-- Memory Map XML DTD ................................ -->
+<!-- File: memory-map.dtd .............................. -->
+<!-- .................................... .............. -->
+<!-- memory-map.dtd -->
+<!-- memory-map: Root element with versioning -->
+<!ELEMENT memory-map (memory | property)>
+<!ATTLIST memory-map    version CDATA   #FIXED  "1.0.0">
+<!ELEMENT memory (property)>
+<!-- memory: Specifies a memory region, 
+             and its type, or device. -->
+<!ATTLIST memory        type    CDATA   #REQUIRED
+                        start   CDATA   #REQUIRED
+                        length  CDATA   #REQUIRED
+                        device  CDATA   #IMPLIED>
+<!-- property: Generic attribute tag -->
+<!ELEMENT property (#PCDATA | property)*>
+<!ATTLIST property      name    CDATA   #REQUIRED>
+@end smallexample
+
 @include agentexpr.texi
 
 @include gpl.texi

Re: Flash support part 3: documentation

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Sat, 22 Jul 2006 16:40:31 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > 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.
> 
> Strictly speaking, there might be several disjoint regions. How about this:
> 
>    If a packet writes to an address that was neither erased by a preceding
>    @samp{vFlashErase} packet nor by some other target-specific method,
>    the results are unpredictable.  

Fine with me.

> Here's yet another revision of the patch.

This is approved to go in; thanks.

Re: Flash support part 3: documentation

[Daniel Jacobowitz]

On Sat, Jul 22, 2006 at 05:05:28PM +0300, Eli Zaretskii wrote:
> > Here's yet another revision of the patch.
> 
> This is approved to go in; thanks.

Hi Eli,

I'll be around to applying these patches shortly, after unanticipated
delay.  I have two small changes to the documentation; does this look
OK (along with Vlad's patch)?  The only changes are a minor grammar
nit, and a clarification for one thing we found particularly confusing
when implementing this spec: that vFlashWrite packets only have an
ordering requirement w.r.t. other vFlashWrite packets, but that GDB's
behavior of sending all the erase packets before any write packets
was intended to be OK.

-- 
Daniel Jacobowitz
CodeSourcery

Index: src/gdb/doc/gdb.texinfo
===================================================================
--- src.orig/gdb/doc/gdb.texinfo	2006-09-20 18:18:50.000000000 -0400
+++ src/gdb/doc/gdb.texinfo	2006-09-20 18:12:14.000000000 -0400
@@ -23181,10 +23181,12 @@ Direct the stub to write data to flash a
 is passed in binary form using the same encoding as for the @samp{X}
 packet (@pxref{Binary Data}).  The memory ranges specified by
 @samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
-not overlap, and must appear in order of increasing addresses.  If a
-packet writes to an address that was neither erased by a preceding
-@samp{vFlashErase} packet nor by some other target-specific method,
-the results are unpredictable.
+not overlap, and must appear in order of increasing addresses
+(although @samp{vFlashErase} packets for higher addresses may already
+have been received; the ordering is guaranteed only between
+@samp{vFlashWrite} packets).  If a packet writes to an address that was
+neither erased by a preceding @samp{vFlashErase} packet nor by some other
+target-specific method, the results are unpredictable.
 
 
 Reply:
@@ -25367,7 +25369,7 @@ host is called:
 @section Memory map format
 @cindex memory map format
 
-To be able to write into flash memory, @value{GDBN} needs to obtain
+To be able to write into flash memory, @value{GDBN} needs to obtain a
 memory map from the target.  This section describes the format of the
 memory map.
 

Re: Flash support part 3: documentation

[Eli Zaretskii]

> Date: Wed, 20 Sep 2006 18:21:06 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> I have two small changes to the documentation; does this look
> OK (along with Vlad's patch)?

Yes, thanks.

Re: Flash support part 3: documentation

[Daniel Jacobowitz]

On Thu, Sep 21, 2006 at 06:21:58AM +0300, Eli Zaretskii wrote:
> > Date: Wed, 20 Sep 2006 18:21:06 -0400
> > From: Daniel Jacobowitz <drow@false.org>
> > 
> > I have two small changes to the documentation; does this look
> > OK (along with Vlad's patch)?
> 
> Yes, thanks.

Thank you, checked in.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Flash support part 3: documentation

[Daniel Jacobowitz]

FYI, I looked over this patch again today; except for minor nits below,
it still accurately describes the other two flash patches.  This covers
the usage and protocol sides, and only the bits in the middle have
changed.

On Sat, Jul 22, 2006 at 04:40:31PM +0400, Vladimir Prus wrote:
> +To be able to write into flash memory, @value{GDBN} needs to obtain
> +memory map from the target.  This section describes the format of the
> +memory map.

"obtain a memory map"?

> +<!DOCTYPE memory-map
> +          PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
> +                 "http://sourceware.org/gdb/gdb-memory-map.dtd">

This URL is not yet valid.  Once the flash patches are merged,
let's remember to make it valid; any DTDs should be available from the
GDB web site.  Automatic XML validation tools will use that.

-- 
Daniel Jacobowitz
CodeSourcery