NOR: make flash_write_unlock() pad to sector end

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 1c20716c9d1e3b38e5da6b9e8addf47095da7a3b..154ecbcaec5e7ddc850b31bbe7d59e1e9d0ea311 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -3857,8 +3857,29 @@ explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
 The relevant flash sectors will be erased prior to programming
 if the @option{erase} parameter is given. If @option{unlock} is
 provided, then the flash banks are unlocked before erase and
-program. The flash bank to use is inferred from the @var{address} of
-each image segment.
+program. The flash bank to use is inferred from the address of
+each image section.
+
+@quotation Warning
+Be careful using the @option{erase} flag when the flash is holding
+data you want to preserve.
+Portions of the flash outside those described in the image's
+sections might be erased with no notice.
+@itemize
+@item
+When a section of the image being written does not fill out all the
+sectors it uses, the unwritten parts of those sectors are necessarily
+also erased, because sectors can't be partially erased.
+@item
+Data stored in sector "holes" between image sections are also affected.
+For example, "@command{flash write_image erase ...}" of an image with
+one byte at the beginning of a flash bank and one byte at the end
+erases the entire bank -- not just the two sectors being written.
+@end itemize
+Also, when flash protection is important, you must re-apply it after
+it has been removed by the @option{unlock} flag.
+@end quotation
+
 @end deffn
 
 @section Other Flash commands