openocd: add post-init and pre-shutdown helpers

It is a common requirement to automatically execute some command
after "init".
This can be achieved, either in scripts or through OpenOCD command
line, by explicitly calling "init" followed by the commands.
But this approach fails if the request for post-init commands is
spread across configuration files; only one of the files can split
pre-init and post-init status by calling "init".
The common workaround is to "rename" the command "init" and
replace it with a TCL proc that calls the original "init" and the
post-init commands. E.g. in Zephyr script [1].

To simplify and formalize the post-init execution, use a TCL list
that contains the list of commands to be executed. Every script
can contribute adding new commands, e.g. using "lappend".

In the same way, formalize the pre-shutdown execution with a TCL
list of user commands to be executed before OpenOCD exit.

Document them and add trivial examples.

Drop from documentation the suggestion to rename "shutdown".

Change-Id: I9464fb40ccede3e7760d425873adca363b49a64f
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Link: [1] https://github.com/zephyrproject-rtos/zephyr/blob/zephyr-v2.7.1/boards/arm/nucleo_h743zi/support/openocd.cfg#L15
Reviewed-on: https://review.openocd.org/c/openocd/+/6851
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>
Tested-by: jenkins

diff --git a/doc/openocd.texi b/doc/openocd.texi
index b87e87f87868f341800936ebcc22664841d66b51..9b78fee806b76736ab5b0a2a083368d364144faa 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2120,6 +2120,15 @@ corresponding subsystems:
 @deffnx {Config Command} {pld init}
 @deffnx {Command} {tpiu init}
 @end deffn
+
+At last, @command{init} executes all the commands that are specified in
+the TCL list @var{post_init_commands}. The commands are executed in the
+same order they occupy in the list. If one of the commands fails, then
+the error is propagated and OpenOCD fails too.
+@example
+lappend post_init_commands @{echo "OpenOCD successfully initialized."@}
+lappend post_init_commands @{echo "Have fun with OpenOCD !"@}
+@end example
 @end deffn
 
 @deffn {Config Command} {noinit}
@@ -8433,18 +8442,19 @@ Close the OpenOCD server, disconnecting all clients (GDB, telnet,
 other). If option @option{error} is used, OpenOCD will return a
 non-zero exit code to the parent process.
 
-Like any TCL commands, also @command{shutdown} can be redefined, e.g.:
+If user types CTRL-C or kills OpenOCD, the command @command{shutdown}
+will be automatically executed to cause OpenOCD to exit.
+
+It is possible to specify, in the TCL list @var{pre_shutdown_commands} , a
+set of commands to be automatically executed before @command{shutdown} , e.g.:
 @example
-# redefine shutdown
-rename shutdown original_shutdown
-proc shutdown @{@} @{
-    puts "This is my implementation of shutdown"
-    # my own stuff before exit OpenOCD
-    original_shutdown
-@}
+lappend pre_shutdown_commands @{echo "Goodbye, my friend ..."@}
+lappend pre_shutdown_commands @{echo "see you soon !"@}
 @end example
-If user types CTRL-C or kills OpenOCD, either the command @command{shutdown}
-or its replacement will be automatically executed before OpenOCD exits.
+The commands in the list will be executed (in the same order they occupy
+in the list) before OpenOCD exits. If one of the commands in the list
+fails, then the remaining commands are not executed anymore while OpenOCD
+will proceed to quit.
 @end deffn
 
 @anchor{debuglevel}

diff --git a/src/helper/startup.tcl b/src/helper/startup.tcl
index 71f489dd5f3c2b2068a2586f4bac99e34042a862..6389262a3d5cb3a4ce530c793dbe6496057d1563 100644 (file)
--- a/src/helper/startup.tcl
+++ b/src/helper/startup.tcl
@@ -28,4 +28,26 @@ proc script {filename} {
 add_help_text script "filename of OpenOCD script (tcl) to run"
 add_usage_text script "<file>"
 
+# Run a list of post-init commands
+# Each command should be added with 'lappend post_init_commands command'
+lappend _telnet_autocomplete_skip _run_post_init_commands
+proc _run_post_init_commands {} {
+       if {[info exists ::post_init_commands]} {
+               foreach cmd $::post_init_commands {
+                       eval $cmd
+               }
+       }
+}
+
+# Run a list of pre-shutdown commands
+# Each command should be added with 'lappend pre_shutdown_commands command'
+lappend _telnet_autocomplete_skip _run_pre_shutdown_commands
+proc _run_pre_shutdown_commands {} {
+       if {[info exists ::pre_shutdown_commands]} {
+               foreach cmd $::pre_shutdown_commands {
+                       eval $cmd
+               }
+       }
+}
+
 #########

diff --git a/src/openocd.c b/src/openocd.c
index 3c96d321456a053d2e6eb35457c64e68061e9fab..fdc4a874b6eab13b658a4d3bc5ab1086348f5b5b 100644 (file)
--- a/src/openocd.c
+++ b/src/openocd.c
@@ -182,6 +182,9 @@ COMMAND_HANDLER(handle_init_command)
 
        target_register_event_callback(log_target_callback_event_handler, CMD_CTX);
 
+       if (command_run_line(CMD_CTX, "_run_post_init_commands") != ERROR_OK)
+               return ERROR_FAIL;
+
        return ERROR_OK;
 }
 

diff --git a/src/server/server.c b/src/server/server.c
index dd408048cf1736dabc94f4fe6ca8c42af6ee4d1e..c7cafb78994b0da4f69df6ec1e6b9a4d0e978acd 100644 (file)
--- a/src/server/server.c
+++ b/src/server/server.c
@@ -762,6 +762,8 @@ COMMAND_HANDLER(handle_shutdown_command)
 
        shutdown_openocd = SHUTDOWN_REQUESTED;
 
+       command_run_line(CMD_CTX, "_run_pre_shutdown_commands");
+
        if (CMD_ARGC == 1) {
                if (!strcmp(CMD_ARGV[0], "error")) {
                        shutdown_openocd = SHUTDOWN_WITH_ERROR_CODE;