flash/startup: extend "program" command to accept "exit"

This optional argument tells OpenOCD to exit after finishing (either
succesfully, or with an error) the programming sequence. Without it
OpenOCD stays running.

Change-Id: I6ecaf33ff985eea9a9cd02ff644a74403ae3e1e5
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Reviewed-on: http://openocd.zylin.com/2492
Tested-by: jenkins
Reviewed-by: Uwe Bonnes <bon@elektron.ikp.physik.tu-darmstadt.de>
Reviewed-by: Spencer Oliver <spen@spen-soft.co.uk>

doc/openocd.texi

@@ -4922,7 +4922,7 @@ comamnd or the flash driver then it defaults to 0xff.
 @end deffn
 
 @anchor{program}
-@deffn Command {program} filename [verify] [reset] [offset]
+@deffn Command {program} filename [verify] [reset] [exit] [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}.
@@ -5928,7 +5928,7 @@ Programming can be acheived by either using GDB @ref{programmingusinggdb,,Progra
 or using the cmds given in @ref{flashprogrammingcommands,,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.
+OpenOCD will program/verify/reset the target and optionally shutdown.
 
 The script is executed as follows and by default the following actions will be peformed.
 @enumerate
@@ -5937,7 +5937,7 @@ The script is executed as follows and by default the following actions will be p
 @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.
+@item OpenOCD is shutdown if @option{exit} parameter is given.
 @end enumerate
 
 An example of usage is given below. @xref{program}.
@@ -5946,11 +5946,11 @@ An example of usage is given below. @xref{program}.
 # program and verify using elf/hex/s19. verify and reset
 # are optional parameters
 openocd -f board/stm32f3discovery.cfg \
-	-c "program filename.elf verify reset"
+	-c "program filename.elf verify reset exit"
 
 # binary files need the flash address passing
 openocd -f board/stm32f3discovery.cfg \
-	-c "program filename.bin 0x08000000"
+	-c "program filename.bin exit 0x08000000"
 @end example
 
 @node NAND Flash Commands

src/flash/startup.tcl

@@ -3,16 +3,28 @@
 #
 # program utility proc
 # usage: program filename
-# optional args: verify, reset and address
+# optional args: verify, reset, exit and address
 #
 
+proc program_error {description exit} {
+	if {$exit == 1} {
+	        echo $description
+		shutdown
+	}
+
+	error $description
+}
+
 proc program {filename args} {
+	set exit 0
 
 	foreach arg $args {
 		if {[string equal $arg "verify"]} {
 			set verify 1
 		} elseif {[string equal $arg "reset"]} {
 			set reset 1
+		} elseif {[string equal $arg "exit"]} {
+			set exit 1
 		} else {
 			set address $arg
 		}
@@ -20,16 +32,12 @@ proc program {filename args} {
 
 	# make sure init is called
 	if {[catch {init}] != 0} {
-		echo "** OpenOCD init Failed **"
-		shutdown
-		return
+		program_error "** OpenOCD init failed **" 1
 	}
 
 	# reset target and call any init scripts
 	if {[catch {reset init}] != 0} {
-		echo "** Unable to reset target **"
-		shutdown
-		return
+		program_error "** Unable to reset target **" $exit
 	}
 
 	# start programming phase
@@ -48,7 +56,7 @@ proc program {filename args} {
 			if {[catch {eval verify_image $flash_args}] == 0} {
 				echo "** Verified OK **"
 			} else {
-				echo "** Verify Failed **"
+				program_error "** Verify Failed **" $exit
 			}
 		}
 
@@ -60,15 +68,17 @@ proc program {filename args} {
 			reset run
 		}
 	} else {
-		echo "** Programming Failed **"
+		program_error "** Programming Failed **" $exit
 	}
 
-	# shutdown OpenOCD
-	shutdown
+	if {$exit == 1} {
+		shutdown
+	}
+	return
 }
 
-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\]"
+add_help_text program "write an image to flash, address is only required for binary images. verify, reset, exit are optional"
+add_usage_text program "<filename> \[address\] \[verify\] \[reset\] \[exit\]"
 
 # stm32f0x uses the same flash driver as the stm32f1x
 # this alias enables the use of either name.