update command_handler documentation
authorZachary T Welch <zw@superlucidity.net>
Tue, 17 Nov 2009 13:38:17 +0000 (05:38 -0800)
committerZachary T Welch <zw@superlucidity.net>
Tue, 17 Nov 2009 19:40:21 +0000 (11:40 -0800)
Improve the developer manual and primer sections which talk about
writing command handlers.  Notably, it documents the new CMD_* macros.


index 247d7b42bcc780570054228f9d188566d0430985..e7454b6980536a3a82ea008b3eeddce79480dcdb 100644 (file)
@@ -45,16 +45,16 @@ another layer of handlers.
 @subsection helpercmdhandlerdef Defining and Calling Command Handlers
-These functions should be defined using the COMMAND_HANDLER macro.
+These functions should be defined using the @c COMMAND_HANDLER macro.
 These methods must be defined as static, as their principle entry point
 should be the run_command dispatch mechanism.
 Command helper functions that require access to the full set of
-parameters should be defined using the COMMAND_HELPER.  These must be
+parameters should be defined using the @c COMMAND_HELPER.  These must be
 declared static by you, as sometimes you might want to share a helper
-among several files (e.g. s3c24xx_nand.h).
+among several files (e.g. @c s3c24xx_nand.h).
-Both types of routines must be called using the CALL_COMMAND_HANDLER macro.
+Both types of routines must be called using the @c CALL_COMMAND_HANDLER macro.
 Calls using this macro to normal handlers require the name of the command
 handler (which can a name or function pointer).  Calls to helpers and
 derived handlers must pass those extra parameters specified by their
@@ -67,22 +67,18 @@ will be able to use direct invocations.
 Thus, the following macros can be used to define and call command
 handlers or helpers:
-- COMMAND_HANDLER - declare or define a command handler.
-- COMMAND_HELPER - declare or define a derived command handler or helper.
-- CALL_COMMAND_COMMAND - call a command handler/helper.
-@subsection helpercmdhandlerparam Command Handler Parameters
-The following parameters are defined in the scope of all command
-handlers and helpers:
-- <code>struct command_context *cmd_ctx</code> - the command's context
-- <code>unsigned argc</code> - the number of command arguments
-- <code>const char *args[]</code> - contains the command arguments
+- @c COMMAND_HANDLER - declare or define a command handler.
+- @c COMMAND_HELPER - declare or define a derived command handler or helper.
+- @c CALL_COMMAND_COMMAND - call a command handler/helper.
 @subsection helpercmdhandlermacros Command Handler Macros
-In addition, the following macro may be used:
-- <code>COMMAND_NAME</code> - contains the command name
+In addition, the following macros may be used in the context of
+command handlers and helpers:
+- @c CMD_CTX - the current @c command_context
+- @c CMD_NAME - invoked command name
+- @c CMD_ARGC - the number of command arguments
+- @c CMD_ARGV - array of command argument strings
 @section helpercmdprimer Command Development Primer
index 9efcca2e84c5b596222e85ac2d313b56338a9201..b15f6697562123b3da8f6142e42df59b297bb9e7 100644 (file)
@@ -16,7 +16,7 @@ COMMAND_HANDLER(handle_hello_command)
        const char *sep, *name;
        int retval = CALL_COMMAND_HANDLER(handle_hello_args);
        if (ERROR_OK == retval)
-               command_print(cmd_ctx, "Greetings%s%s!", sep, name);
+               command_print(CMD_CTX, "Greetings%s%s!", sep, name);
        return retval;
@@ -39,13 +39,13 @@ static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
        if (argc > 1)
-               LOG_ERROR("%s: too many arguments", COMMAND_NAME);
+               LOG_ERROR("%s: too many arguments", CMD_NAME);
                return ERROR_COMMAND_SYNTAX_ERROR;
-       if (1 == argc)
+       if (1 == CMD_ARGC)
                *sep = ", ";
-               *name = args[0];
+               *name = CMD_ARGV[0];
                *sep = *name = "";
@@ -96,4 +96,9 @@ Greetings, John Doe!
 Error: ocd_hello: too many arguments
+This difference between the registered and displayed command name comes from
+the fact that the TCL scripts are provided with a stub that calls the munged
+name.  This stub wraps the internal <code>ocd_</code>-prefixed routine,
+providing a measure of high-level error handling.

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)