100 lines
2.9 KiB
Plaintext
100 lines
2.9 KiB
Plaintext
|
/** @page primercommand Command Development Primer
|
||
|
|
|
||
|
|
This page provides a primer for writing commands by introducing @c hello
|
||
|
|
module. The full source code used in this example can be found in
|
||
|
|
hello.c, and the @ref primercmdcode section shows how to use it.
|
||
|
|
|
||
|
|
A summary of this information can be found in @ref helpercommand .
|
||
|
|
|
||
|
|
@section primercmdhandler Command Handlers
|
||
|
|
|
||
|
|
Defining new commands and their helpers is easy. The following code
|
||
|
|
defines a simple command handler that delegates its argument parsing:
|
||
|
|
@code
|
||
|
|
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);
|
||
|
|
return retval;
|
||
|
|
}
|
||
|
|
@endcode
|
||
|
|
|
||
|
|
Here, the @c COMMAND_HANDLER macro establishes the function signature,
|
||
|
|
see in command.h by the @c __COMMAND_HANDLER macro.
|
||
|
|
|
||
|
|
The COMMAND_HELPER macro function allows defining functions with an
|
||
|
|
extended version of the base signature. These helper functions can be
|
||
|
|
called (with the appropriate parameters), the @c CALL_COMMAND_HANDLER
|
||
|
|
macro to pass any e as parameters to the following helper function:
|
||
|
|
|
||
|
|
The subsequent blocks of code are a normal C function that can do
|
||
|
|
anything, so only complex commands deserve should use comamnd helper
|
||
|
|
functions. In this respect, this example uses one to demonstrate how --
|
||
|
|
not when -- they should be used.
|
||
|
|
|
||
|
|
@code
|
||
|
|
static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
|
||
|
|
{
|
||
|
|
if (argc > 1)
|
||
|
|
{
|
||
|
|
LOG_ERROR("%s: too many arguments", COMMAND_NAME);
|
||
|
|
return ERROR_COMMAND_SYNTAX_ERROR;
|
||
|
|
}
|
||
|
|
if (1 == argc)
|
||
|
|
{
|
||
|
|
*sep = ", ";
|
||
|
|
*name = args[0];
|
||
|
|
}
|
||
|
|
else
|
||
|
|
*sep = *name = "";
|
||
|
|
|
||
|
|
return ERROR_OK;
|
||
|
|
}
|
||
|
|
@endcode
|
||
|
|
|
||
|
|
Of course, you may also call other macros or functions, but that extends
|
||
|
|
beyond the scope of this tutorial on writing commands.
|
||
|
|
|
||
|
|
@section primercmdreg Command Registration
|
||
|
|
|
||
|
|
Before this new function can be used, it must be registered somehow.
|
||
|
|
For a new module, registering should be done in a new function for
|
||
|
|
the purpose, which must be called from @c openocd.c:
|
||
|
|
@code
|
||
|
|
int hello_register_commands(struct command_context_s *cmd_ctx)
|
||
|
|
{
|
||
|
|
struct command_s *cmd = register_command(cmd_ctx, NULL, "hello",
|
||
|
|
NULL, COMMAND_ANY, "print greetings");
|
||
|
|
return cmd ? ERROR_OK : -ENOMEM;
|
||
|
|
}
|
||
|
|
@endcode
|
||
|
|
|
||
|
|
That's it! The command should now be registered and avaiable to scripts.
|
||
|
|
|
||
|
|
@section primercmdcode Trying These Example Commands
|
||
|
|
|
||
|
|
The commands may be enabled by editing src/openocd.c and uncommenting
|
||
|
|
the call to @c hello_register_commands and rebuilding the source tree.
|
||
|
|
|
||
|
|
Once OpenOCD has been built with this example code, the following script
|
||
|
|
demonstrate the abilities that the @c hello module provides:
|
||
|
|
@code
|
||
|
|
hello
|
||
|
|
hello World
|
||
|
|
hello {John Doe}
|
||
|
|
hello John Doe # error: too many arguments
|
||
|
|
@endcode
|
||
|
|
|
||
|
|
If saved in @c hello.cfg, then running <code>openocd -f hello.cfg</code>
|
||
|
|
should produce the following output before exiting:
|
||
|
|
@code
|
||
|
|
Greetings!
|
||
|
|
Greetings, World!
|
||
|
|
Greetings, John Doe!
|
||
|
|
Error: ocd_hello: too many arguments
|
||
|
|
@endcode
|
||
|
|
|
||
|
|
*/
|