tcl: add flash programming helper

This adds a program proc that simplifies using OpenOCD as a standalone
programmer.

Change-Id: I6ece492cd878c170b734e8bb2e09fe8c4557d5a6
Signed-off-by: Spencer Oliver <spen@spen-soft.co.uk>
Reviewed-on: http://openocd.zylin.com/1199
Tested-by: jenkins
Reviewed-by: Jörg Fischer <turboj@gmx.de>
Reviewed-by: Andreas Fritiofson <andreas.fritiofson@gmail.com>
Reviewed-by: Øyvind Harboe <oyvindharboe@gmail.com>

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
 * 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
 * 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
 @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.
 
 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
 
 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,
 @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
 
 @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
 @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
 
 @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:
 
 By default the target memory map is sent to GDB. This can be disabled by
 the following OpenOCD configuration option:

diff --git a/src/flash/startup.tcl b/src/flash/startup.tcl
index 5f40e64912a2515bed7a43403b2c3f60dcf63be9..82959c8a136b418890f3ddbb3cc94eee3d723e71 100644 (file)
--- a/src/flash/startup.tcl
+++ b/src/flash/startup.tcl
@@ -1,5 +1,73 @@
 # Defines basic Tcl procs for OpenOCD flash module
 
 # Defines basic Tcl procs for OpenOCD flash module
 

+#
+# program utility proc
+# usage: program filename
+# optional args: verify, reset and address
+#
+
+proc program {filename args} {
+
+       foreach arg $args {
+               if {[string equal $arg "verify"]} {
+                       set verify 1
+               } elseif {[string equal $arg "reset"]} {
+                       set reset 1
+               } else {
+                       set address $arg
+               }
+       }
+
+       # make sure init is called
+       if {[catch {init}] != 0} {
+               echo "** OpenOCD init Failed **"
+               shutdown
+               return
+       }
+
+       # reset target and call any init scripts
+       if {[catch {reset init}] != 0} {
+               echo "** Unable to reset target **"
+               shutdown
+               return
+       }
+
+       # start programming phase
+       echo "** Programming Started **"
+       if {[info exists address]} {
+               set flash_args "$filename $address"
+       } else {
+               set flash_args "$filename"
+       }
+
+       if {[catch {eval flash write_image erase $flash_args}] == 0} {
+               echo "** Programming Finished **"
+               if {[info exists verify]} {
+                       # verify phase
+                       echo "** Verify Started **"
+                       if {[catch {eval verify_image $flash_args}] == 0} {
+                               echo "** Verified OK **"
+                       } else {
+                               echo "** Verify Failed **"
+                       }
+               }
+
+               if {[info exists reset]} {
+                       # reset target if requested
+                       echo "** Resetting Target **"
+                       reset run
+               }
+       } else {
+               echo "** Programming Failed **"
+       }
+
+       # shutdown OpenOCD
+       shutdown
+}
+
+add_help_text program "write an image to flash, address is only required for binary images. verify, reset are optional"
+add_usage_text program "<filename> \[address\] \[verify\] \[reset\]"
+

 # ease migration to updated flash driver
 proc stm32x args {
        echo "DEPRECATED! use 'stm32f1x $args' not 'stm32x $args'"
 # ease migration to updated flash driver
 proc stm32x args {
        echo "DEPRECATED! use 'stm32f1x $args' not 'stm32x $args'"


@@ -10,4 +78,3 @@ proc stm32f2xxx args {
        echo "DEPRECATED! use 'stm32f2x $args' not 'stm32f2xxx $args'"
        eval stm32f2x $args
 }
        echo "DEPRECATED! use 'stm32f2x $args' not 'stm32f2xxx $args'"
        eval stm32f2x $args
 }

-