update command_handler documentation
Improve the developer manual and primer sections which talk about writing command handlers. Notably, it documents the new CMD_* macros.
This commit is contained in:
parent
cfaf7bdd0a
commit
789d47c180
|
@ -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
|
||||
|
||||
|
|
|
@ -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;
|
||||
}
|
||||
@endcode
|
||||
|
@ -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];
|
||||
}
|
||||
else
|
||||
*sep = *name = "";
|
||||
|
@ -96,4 +96,9 @@ Greetings, John Doe!
|
|||
Error: ocd_hello: too many arguments
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
*/
|
||||
|
|
Loading…
Reference in New Issue