semihosting: add custom user command handler

[fw/openocd] / src / helper / command.h

diff --git a/src/helper/command.h b/src/helper/command.h
index 4d1928c5a9630ecd03d249e607bebaac7041978e..796cd9d3b3860b10f465d0627ca9ad00cd4a5b10 100644 (file)
--- a/src/helper/command.h
+++ b/src/helper/command.h
@@ -24,8 +24,8 @@
 
 #include <stdint.h>
 #include <stdbool.h>
-#include <jim-nvp.h>
 
+#include <helper/jim-nvp.h>
 #include <helper/list.h>
 #include <helper/types.h>
 
@@ -38,6 +38,15 @@
 #define PRINTF_ATTRIBUTE_FORMAT printf
 #endif
 
+/**
+ * OpenOCD command mode is COMMAND_CONFIG at start, then switches to COMMAND_EXEC
+ * during the execution of command 'init'.
+ * The field 'mode' in struct command_registration specifies in which command mode
+ * the command can be executed:
+ * - during COMMAND_CONFIG only,
+ * - during COMMAND_EXEC only,
+ * - in both modes (COMMAND_ANY).
+ */
 enum command_mode {
        COMMAND_EXEC,
        COMMAND_CONFIG,
@@ -54,7 +63,6 @@ typedef int (*command_output_handler_t)(struct command_context *context,
 struct command_context {
        Jim_Interp *interp;
        enum command_mode mode;
-       struct command *commands;
        struct target *current_target;
                /* The target set by 'targets xx' command or the latest created */
        struct target *current_target_override;
@@ -85,6 +93,17 @@ struct command_invocation {
        Jim_Obj *output;
 };
 
+/**
+ * Return true if the command @c cmd is registered by OpenOCD.
+ */
+bool jimcmd_is_oocd_command(Jim_Cmd *cmd);
+
+/**
+ * Return the pointer to the command's private data specified during the
+ * registration of command @a cmd .
+ */
+void *jimcmd_privdata(Jim_Cmd *cmd);
+
 /**
  * Command handlers may be defined with more parameters than the base
  * set provided by command.c.  This macro uses C99 magic to allow
@@ -182,8 +201,6 @@ typedef __COMMAND_HANDLER((*command_handler_t));
 
 struct command {
        char *name;
-       struct command *parent;
-       struct command *children;
        command_handler_t handler;
        Jim_CmdProc *jim_handler;
        void *jim_handler_data;
@@ -191,7 +208,6 @@ struct command {
        struct target *jim_override_target;
                /* Used only for target of target-prefixed cmd */
        enum command_mode mode;
-       struct command *next;
 };
 
 /*
@@ -420,7 +436,7 @@ DECLARE_PARSE_WRAPPER(_target_addr, target_addr_t);
 #define COMMAND_PARSE_NUMBER(type, in, out) \
        do { \
                int retval_macro_tmp = parse_ ## type(in, &(out)); \
-               if (ERROR_OK != retval_macro_tmp) { \
+               if (retval_macro_tmp != ERROR_OK) { \
                        command_print(CMD, stringify(out) \
                                " option value ('%s') is not valid", in); \
                        return retval_macro_tmp; \
@@ -430,6 +446,48 @@ DECLARE_PARSE_WRAPPER(_target_addr, target_addr_t);
 #define COMMAND_PARSE_ADDRESS(in, out) \
        COMMAND_PARSE_NUMBER(target_addr, in, out)
 
+/**
+ * @brief parses the command argument at position @a argn into @a out
+ * as a @a type, or prints a command error referring to @a name_str
+ * and passes the error code to the caller. @a argn will be incremented
+ * if no error occurred. Otherwise the calling function will return
+ * the error code produced by the parsing function.
+ *
+ * This function may cause the calling function to return immediately,
+ * so it should be used carefully to avoid leaking resources.  In most
+ * situations, parsing should be completed in full before proceeding
+ * to allocate resources, and this strategy will most prevents leaks.
+ */
+#define COMMAND_PARSE_ADDITIONAL_NUMBER(type, argn, out, name_str) \
+       do { \
+               if (argn+1 >= CMD_ARGC || CMD_ARGV[argn+1][0] == '-') { \
+                       command_print(CMD, "no " name_str " given"); \
+                       return ERROR_FAIL; \
+               } \
+               ++argn; \
+               COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
+       } while (0)
+
+/**
+ * @brief parses the command argument at position @a argn into @a out
+ * as a @a type if the argument @a argn does not start with '-'.
+ * and passes the error code to the caller. @a argn will be incremented
+ * if no error occurred. Otherwise the calling function will return
+ * the error code produced by the parsing function.
+ *
+ * This function may cause the calling function to return immediately,
+ * so it should be used carefully to avoid leaking resources.  In most
+ * situations, parsing should be completed in full before proceeding
+ * to allocate resources, and this strategy will most prevents leaks.
+ */
+#define COMMAND_PARSE_OPTIONAL_NUMBER(type, argn, out) \
+       do { \
+               if (argn+1 < CMD_ARGC && CMD_ARGV[argn+1][0] != '-') { \
+                       ++argn; \
+                       COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
+               } \
+       } while (0)
+
 /**
  * Parse the string @c as a binary parameter, storing the boolean value
  * in @c out.  The strings @c on and @c off are used to match different
@@ -440,7 +498,7 @@ DECLARE_PARSE_WRAPPER(_target_addr, target_addr_t);
        do { \
                bool value; \
                int retval_macro_tmp = command_parse_bool_arg(in, &value); \
-               if (ERROR_OK != retval_macro_tmp) { \
+               if (retval_macro_tmp != ERROR_OK) { \
                        command_print(CMD, stringify(out) \
                                " option value ('%s') is not valid", in); \
                        command_print(CMD, "  choices are '%s' or '%s'", \
@@ -460,6 +518,4 @@ COMMAND_HELPER(handle_command_parse_bool, bool *out, const char *label);
 #define COMMAND_PARSE_ENABLE(in, out) \
        COMMAND_PARSE_BOOL(in, out, "enable", "disable")
 
-void script_debug(Jim_Interp *interp, unsigned int argc, Jim_Obj * const *argv);
-
 #endif /* OPENOCD_HELPER_COMMAND_H */