tcl: add flash programming helper

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index a5b0a12a4c7303bd9fea1689ac5c0a3730832881..9f3a8515c94ff884e63c2d329f717202e9d4eade 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -72,6 +72,7 @@ Free Documentation License''.
 * TAP Declaration::                  TAP Declaration
 * CPU Configuration::                CPU Configuration
 * Flash Commands::                   Flash Commands
+* Flash Programming::                Flash Programming
 * NAND Flash Commands::              NAND Flash Commands
 * PLD/FPGA Commands::                PLD/FPGA Commands
 * General Commands::                 General Commands
@@ -4596,6 +4597,7 @@ but most don't bother.
 @cindex flash reading
 @cindex flash writing
 @cindex flash programming
+@anchor{Flash Programming Commands}
 
 One feature distinguishing NOR flash from NAND or serial flash technologies
 is that for read access, it acts exactly like any other addressible memory.
@@ -4739,6 +4741,13 @@ specifies "to the end of the flash bank".
 The @var{num} parameter is a value shown by @command{flash banks}.
 @end deffn
 
+@anchor{program}
+@deffn Command {program} filename [verify] [reset] [offset]
+This is a helper script that simplifies using OpenOCD as a standalone
+programmer. The only required parameter is @option{filename}, the others are optional.
+@xref{Flash Programming}.
+@end deffn
+
 @anchor{Flash Driver List}
 @section Flash Driver List
 As noted above, the @command{flash bank} command requires a driver name,
@@ -5580,6 +5589,38 @@ Write the binary file @var{filename} to mflash bank @var{num}, starting at
 @var{offset} bytes from the beginning of the bank.
 @end deffn
 
+@node Flash Programming
+@chapter Flash Programming
+
+OpenOCD implements numerous ways to program the target flash, whether internal or external.
+Programming can be acheived by either using GDB @ref{Programming using GDB}, or using the cmds given in @ref{Flash Programming Commands}.
+
+@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
+OpenOCD will program/verify/reset the target and shutdown.
+
+The script is executed as follows and by default the following actions will be peformed.
+@enumerate
+@item 'init' is executed.
+@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
+@item @code{flash write_image} is called to erase and write any flash using the filename given.
+@item @code{verify_image} is called if @option{verify} parameter is given.
+@item @code{reset run} is called if @option{reset} parameter is given.
+@item OpenOCD is shutdown.
+@end enumerate
+
+An example of usage is given below. @xref{program}.
+
+@example
+# program and verify using elf/hex/s19. verify and reset
+# are optional parameters
+openocd -f board/stm32f3discovery.cfg \
+       -c "program filename.elf verify reset"
+
+# binary files need the flash address passing
+openocd -f board/stm32f3discovery.cfg \
+       -c "program filename.bin 0x08000000"
+@end example
+
 @node NAND Flash Commands
 @chapter NAND Flash Commands
 @cindex NAND
@@ -7871,6 +7912,7 @@ using @command{gdb -x filename}.
 
 @section Programming using GDB
 @cindex Programming using GDB
+@anchor{Programming using GDB}
 
 By default the target memory map is sent to GDB. This can be disabled by
 the following OpenOCD configuration option: