From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22456 invoked by alias); 22 Jul 2006 12:40:45 -0000 Received: (qmail 22448 invoked by uid 22791); 22 Jul 2006 12:40:43 -0000 X-Spam-Check-By: sourceware.org Received: from potter.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sat, 22 Jul 2006 12:40:39 +0000 Received: (qmail 19011 invoked from network); 22 Jul 2006 12:40:36 -0000 Received: from unknown (HELO zigzag.lvk.cs.msu.su) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 22 Jul 2006 12:40:36 -0000 From: Vladimir Prus To: Eli Zaretskii Subject: Re: Flash support part 3: documentation Date: Sat, 22 Jul 2006 12:40:00 -0000 User-Agent: KMail/1.7.2 Cc: gdb-patches@sources.redhat.com References: <200607201343.32483.vladimir@codesourcery.com> <200607211604.02942.vladimir@codesourcery.com> In-Reply-To: MIME-Version: 1.0 Content-Type: Multipart/Mixed; boundary="Boundary-00=_/yhwE7ayzYAitKF" Message-Id: <200607221640.31522.vladimir@codesourcery.com> Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2006-07/txt/msg00310.txt.bz2 --Boundary-00=_/yhwE7ayzYAitKF Content-Type: text/plain; charset="koi8-r" Content-Transfer-Encoding: 7bit Content-Disposition: inline Content-length: 2186 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 --Boundary-00=_/yhwE7ayzYAitKF Content-Type: text/x-diff; charset="koi8-r"; name="flash_docs.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="flash_docs.diff" Content-length: 6446 === 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 + + + + region... + +@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 + +@end smallexample + + +@item +A region of read-only memory: + +@smallexample + +@end smallexample + + +@item +A region of flash memory, with erasure blocks @var{blocksize} +bytes in length: + +@smallexample + + @var{blocksize} + +@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 + + + + + + + + + + + + + + +@end smallexample + @include agentexpr.texi @include gpl.texi --Boundary-00=_/yhwE7ayzYAitKF--