openocd-commit

[Zach W. <zw...@us...>]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Main OpenOCD repository".

The branch, master has been updated
       via  be65f497f5f50d6d037295d5f466db5314f99de1 (commit)
       via  5dd6457d2c06caed01d4b75ecf1415afc68b48ea (commit)
       via  3d204ec66a840849372ab4c0ec4526a6f8557106 (commit)
       via  bc9ae740730efacc2daa3ecbdb0ee75601ec18df (commit)
      from  c0630d8a58c525e09aa938c7a50d4c99d39a93a3 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit be65f497f5f50d6d037295d5f466db5314f99de1
Author: Zachary T Welch <zw...@su...>
Date:   Sun Nov 29 16:48:40 2009 -0800

    fix foo command group help messages
    
    Splits the old help strings to provide proper usage as well.

diff --git a/src/hello.c b/src/hello.c
index 2e5c928..cfd6e2f 100644
--- a/src/hello.c
+++ b/src/hello.c
@@ -58,19 +58,22 @@ static const struct command_registration foo_command_handlers[] = {
 		.name = "bar",
 		.handler = &handle_foo_command,
 		.mode = COMMAND_ANY,
-		.help = "<address> [enable|disable] - an example command",
+		.usage = "<address> [enable|disable]",
+		.help = "an example command",
 	},
 	{
 		.name = "baz",
 		.handler = &handle_foo_command,
 		.mode = COMMAND_ANY,
-		.help = "<address> [enable|disable] - a sample command",
+		.usage = "<address> [enable|disable]",
+		.help = "a sample command",
 	},
 	{
 		.name = "flag",
 		.handler = &handle_flag_command,
 		.mode = COMMAND_ANY,
-		.help = "[on|off] - set a flag",
+		.usage = "[on|off]",
+		.help = "set a flag",
 	},
 	COMMAND_REGISTRATION_DONE
 };

commit 5dd6457d2c06caed01d4b75ecf1415afc68b48ea
Author: Zachary T Welch <zw...@su...>
Date:   Sun Nov 29 16:32:06 2009 -0800

    make syntax errors respond with 'usage'
    
    The 'help' text will become more verbose, so its entire text will be
    far more than desired when you only borked your syntax.  The usage
    still allows the commands to be looked up for more help.

diff --git a/src/helper/command.c b/src/helper/command.c
index 6031ce6..319f081 100644
--- a/src/helper/command.c
+++ b/src/helper/command.c
@@ -562,7 +562,7 @@ static int run_command(struct command_context *context,
 		/* Print help for command */
 		char *full_name = command_name(c, ' ');
 		if (NULL != full_name) {
-			command_run_linef(context, "help %s", full_name);
+			command_run_linef(context, "usage %s", full_name);
 			free(full_name);
 		} else
 			retval = -ENOMEM;
@@ -980,10 +980,10 @@ static int command_unknown(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 	}
 	else
 	{
-		c = command_find(cmd_ctx->commands, "help");
+		c = command_find(cmd_ctx->commands, "usage");
 		if (NULL == c)
 		{
-			LOG_ERROR("unknown command, but help is missing too");
+			LOG_ERROR("unknown command, but usage is missing too");
 			return JIM_ERR;
 		}
 		count = argc - remaining;
diff --git a/src/helper/startup.tcl b/src/helper/startup.tcl
index dda89c8..d1c73ef 100644
--- a/src/helper/startup.tcl
+++ b/src/helper/startup.tcl
@@ -25,7 +25,7 @@ proc ocd_bouncer {name args} {
 			set errmsg "Command handler execution failed"
 		}
 	} else {if {$type == "group"} {
-		catch {eval ocd_help $name $args}
+		catch {eval ocd_usage $name $args}
 		set errmsg [format "%s: command requires more arguments" \
 			[concat $name " " $args]]
 	} else {

commit 3d204ec66a840849372ab4c0ec4526a6f8557106
Author: Zachary T Welch <zw...@su...>
Date:   Sun Nov 29 16:30:00 2009 -0800

    move improperly located documentation
    
    Somehow, the comment block for command handlers ended up associated
    with the output_handler.  Move it to the command_handler_t declaration.

diff --git a/src/helper/command.h b/src/helper/command.h
index 72c5647..0723596 100644
--- a/src/helper/command.h
+++ b/src/helper/command.h
@@ -62,20 +62,6 @@ struct command_context
 	enum command_mode mode;
 	struct command *commands;
 	int current_target;
-	/* Execute a command.
-	 *
-	 * If the command fails, it *MUST* return a value != ERROR_OK
-	 * (many commands break this rule, patches welcome!)
-	 *
-	 * This is *especially* important for commands such as writing
-	 * to flash or verifying memory. The reason is that those commands
-	 * can be used by programs to determine if the operation succeded
-	 * or not. If the operation failed, then a program can try
-	 * an alternative approach.
-	 *
-	 * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
-	 * printing out the syntax of the command.
-	 */
 	command_output_handler_t output_handler;
 	void *output_handler_priv;
 };
@@ -166,7 +152,23 @@ struct command_invocation {
 #define CMD_DATA CMD_CURRENT->jim_handler_data
 
 
-/// The type signature for commands' handler functions.
+/**
+ * The type signature for command handling functions.  They are
+ * usually registered as part of command_registration, providing
+ * a high-level means for executing a command.
+ *
+ * If the command fails, it *MUST* return a value != ERROR_OK
+ * (many commands break this rule, patches welcome!)
+ *
+ * This is *especially* important for commands such as writing
+ * to flash or verifying memory. The reason is that those commands
+ * can be used by programs to determine if the operation succeded
+ * or not. If the operation failed, then a program can try
+ * an alternative approach.
+ *
+ * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
+ * printing out the syntax of the command.
+ */
 typedef __COMMAND_HANDLER((*command_handler_t));
 
 struct command

commit bc9ae740730efacc2daa3ecbdb0ee75601ec18df
Author: Zachary T Welch <zw...@su...>
Date:   Sun Nov 29 15:58:16 2009 -0800

    improve command_done() API and docs
    
    command_done() does not need to return an error, but it needed
    Doxygen comment.  Provide some for copy_command_context as well.
    
    Note: this audit revealed some potential bugs with the command context
    implementation.  There was a reason that commands were added at the
    end of the list.  Shallow copying of command_context means that
    the list is shared between them.  And commands added at the top-level
    before the pre-existing commands will not be available in the shared
    context as they were before.  Yikes!
    
    Fortunately, this does not seem to occur in general use, as
    'add_help_text' gets registered in startup.tcl and claims the first slot
    in my own test cases.  Thus, it seems that we have been masking the issue
    for now, but it shows the need for further architectural improvement in
    the core command module.

diff --git a/src/helper/command.c b/src/helper/command.c
index ac7c8d8..6031ce6 100644
--- a/src/helper/command.c
+++ b/src/helper/command.c
@@ -683,12 +683,12 @@ struct command_context* copy_command_context(struct command_context* context)
 	return copy_context;
 }
 
-int command_done(struct command_context *context)
+void command_done(struct command_context *cmd_ctx)
 {
-	free(context);
-	context = NULL;
+	if (NULL == cmd_ctx)
+		return;
 
-	return ERROR_OK;
+	free(cmd_ctx);
 }
 
 /* find full path to file */
diff --git a/src/helper/command.h b/src/helper/command.h
index 2d33484..72c5647 100644
--- a/src/helper/command.h
+++ b/src/helper/command.h
@@ -316,7 +316,6 @@ void command_set_handler_data(struct command *c, void *p);
 void command_set_output_handler(struct command_context* context,
 		command_output_handler_t output_handler, void *priv);
 
-struct command_context* copy_command_context(struct command_context* context);
 
 int command_context_mode(struct command_context *context, enum command_mode mode);
 
@@ -324,7 +323,21 @@ int command_context_mode(struct command_context *context, enum command_mode mode
  * Creates a new command context using the startup TCL provided.
  */
 struct command_context* command_init(const char *startup_tcl);
-int command_done(struct command_context *context);
+/**
+ * Creates a copy of an existing command context.  This does not create
+ * a deep copy of the command list, so modifications in one context will
+ * affect all shared contexts.  The caller must track reference counting
+ * and ensure the commands are freed before destroying the last instance.
+ * @param cmd_ctx The command_context that will be copied.
+ * @returns A new command_context with the same state as the original.
+ */
+struct command_context* copy_command_context(struct command_context* cmd_ctx);
+/**
+ * Frees the resources associated with a command context.  The commands
+ * are not removed, so unregister_all_commands() must be called first.
+ * @param cmd_ctx The command_context that will be destroyed.
+ */
+void command_done(struct command_context *context);
 
 void command_print(struct command_context *context, const char *format, ...)
 		__attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));

-----------------------------------------------------------------------

Summary of changes:
 src/hello.c            |    9 +++++--
 src/helper/command.c   |   14 ++++++------
 src/helper/command.h   |   49 +++++++++++++++++++++++++++++++----------------
 src/helper/startup.tcl |    2 +-
 4 files changed, 46 insertions(+), 28 deletions(-)


hooks/post-receive
-- 
Main OpenOCD repository