Flash support part 3: documentation

[Vladimir Prus <vladimir at codesourcery dot com>]

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.

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