X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=src%2Fhelper%2Fcommand.h;h=74c6f367b0bc88452fbff38f4deae9e37e07eb78;hp=732fa525ade98678d252c28bd43b98f328f8103f;hb=a585bdf7269ce5c861c83ee3294ba1f074e9c877;hpb=2d3cc1eac126990c5cd4ca8a47b0c09814dc1e5c

diff --git a/src/helper/command.h b/src/helper/command.h
index 732fa525ad..74c6f367b0 100644
--- a/src/helper/command.h
+++ b/src/helper/command.h
@@ -51,6 +51,12 @@ enum command_mode
 	COMMAND_ANY,
 };
 
+struct command_context_s;
+
+/// The type signature for command context's output handler.
+typedef int (*command_output_handler_t)(struct command_context_s *context,
+				const char* line);
+
 typedef struct command_context_s
 {
 	enum command_mode mode;
@@ -70,16 +76,67 @@ typedef struct command_context_s
 	 * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
 	 * printing out the syntax of the command.
 	 */
-	int (*output_handler)(struct command_context_s *context, const char* line);
+	command_output_handler_t output_handler;
 	void *output_handler_priv;
 } command_context_t;
 
+
+/**
+ * Command handlers may be defined with more parameters than the base
+ * set provided by command.c.  This macro uses C99 magic to allow
+ * defining all such derivative types using this macro.
+ */
+#define __COMMAND_HANDLER(name, extra...) \
+		int name(struct command_context_s *cmd_ctx, \
+				char *cmd, char **args, int argc, ##extra)
+
+/**
+ * Use this to macro to call a command helper (or a nested handler).
+ * It provides command handler authors protection against reordering or
+ * removal of unused parameters.
+ *
+ * @b Note: This macro uses lexical capture to provide some arguments.
+ * As a result, this macro should be used @b only within functions
+ * defined by the COMMAND_HANDLER or COMMAND_HELPER macros.  Those
+ * macros provide the expected lexical context captured by this macro.
+ * Furthermore, it should be used only from the top-level of handler or
+ * helper function, or care must be taken to avoid redefining the same
+ * variables in intervening scope(s) by accident.
+ */
+#define CALL_COMMAND_HANDLER(name, extra...) \
+		name(cmd_ctx, cmd, args, argc, ##extra)
+
+/**
+ * Always use this macro to define new command handler functions.
+ * It ensures the parameters are ordered, typed, and named properly, so
+ * they be can be used by other macros (e.g. COMMAND_PARSE_NUMBER).
+ * All command handler functions must be defined as static in scope.
+ */
+#define COMMAND_HANDLER(name) static __COMMAND_HANDLER(name)
+
+/**
+ * Similar to COMMAND_HANDLER, except some parameters are expected.
+ * A helper is globally-scoped because it may be shared between several
+ * source files (e.g. the s3c24xx device command helper).
+ */
+#define COMMAND_HELPER(name, extra...) __COMMAND_HANDLER(name, extra)
+
+/**
+ * Use this macro to access the name of the command being handled,
+ * rather than accessing the variable directly.  It may be moved.
+ */
+#define CMD_NAME cmd
+
+
+/// The type signature for commands' handler functions.
+typedef __COMMAND_HANDLER((*command_handler_t));
+
 typedef struct command_s
 {
 	char *name;
 	struct command_s *parent;
 	struct command_s *children;
-	int (*handler)(struct command_context_s *context, char* name, char** args, int argc);
+	command_handler_t handler;
 	enum command_mode mode;
 	struct command_s *next;
 } command_t;
@@ -95,17 +152,14 @@ typedef struct command_s
 char *command_name(struct command_s *c, char delim);
 
 command_t* register_command(command_context_t *context,
-		command_t *parent, char *name,
-		int (*handler)(struct command_context_s *context,
-				char* name, char** args, int argc),
+		command_t *parent, char *name, command_handler_t handler,
 		enum command_mode mode, char *help);
 
 int unregister_command(command_context_t *context, char *name);
 int unregister_all_commands(command_context_t *context);
 
 void command_set_output_handler(command_context_t* context,
-		int (*output_handler)(struct command_context_s *context,
-		const char* line), void *priv);
+		command_output_handler_t output_handler, void *priv);
 
 command_context_t* copy_command_context(command_context_t* context);