Re: Flash support part 3: documentation

[Vladimir Prus <vladimir@codesourcery.com>]

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