summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZachary T Welch <zw@superlucidity.net>2009-11-24 18:47:35 -0800
committerZachary T Welch <zw@superlucidity.net>2009-11-25 10:29:06 -0800
commited90b6659f6d6b98b59d65f7a889e0221bdffa87 (patch)
tree593a554ccd1f9207595dcc06425e3559c7b02bdd
parent9d4c89f37f814df05837cec280b362ad2962c667 (diff)
downloadopenocd_libswd-ed90b6659f6d6b98b59d65f7a889e0221bdffa87.tar.gz
openocd_libswd-ed90b6659f6d6b98b59d65f7a889e0221bdffa87.tar.bz2
openocd_libswd-ed90b6659f6d6b98b59d65f7a889e0221bdffa87.tar.xz
openocd_libswd-ed90b6659f6d6b98b59d65f7a889e0221bdffa87.zip
update command handler documentation
Adds sections on command registration and chaining, giving an overview to developers that want to use these features.
-rw-r--r--doc/manual/helper.txt36
-rw-r--r--doc/manual/primer/commands.txt65
2 files changed, 83 insertions, 18 deletions
diff --git a/doc/manual/helper.txt b/doc/manual/helper.txt
index e7454b69..aa52355f 100644
--- a/doc/manual/helper.txt
+++ b/doc/manual/helper.txt
@@ -80,6 +80,42 @@ command handlers and helpers:
- @c CMD_ARGC - the number of command arguments
- @c CMD_ARGV - array of command argument strings
+@section helpercmdregister Command Registration
+
+In order to use a command handler, it must be registered with the
+command subsystem. All commands are registered with command_registration
+structures, specifying the name of the command, its handler, its allowed
+mode(s) of execution, and strings that provide usage and help text.
+A single handler may be registered using multiple names, but any name
+may have only one handler associated with it.
+
+The @c register_commands() and @c register_commands() functions provide
+registration, while the @c unregister_command() and
+@c unregister_all_commands() functions will remove existing commands.
+These may be called at any time, allowing the command set to change in
+response to system actions.
+
+@subsection helpercmdjim Jim Command Registration
+
+The command_registration structure provides support for registering
+native Jim command handlers (@c jim_handler) too. For these handlers,
+the module can provide help and usage support; however, this mechanism
+allows Jim handlers to be called as sub-commands of other commands.
+These commands may be registered with a private data value (@c
+jim_handler_data) that will be available when called, as with low-level
+Jim command registration.
+
+A command may have a normal @c handler or a @c jim_handler, but not both.
+
+@subsection helpercmdregisterchains Command Chaining
+
+When using register_commands(), the array of commands may reference
+other arrays. When the @c chain field is filled in a
+command_registration record, the commands on in the chained list will
+added in one of two places. If the record defines a new command, then
+the chained commands are added under it; otherwise, the commands are
+added in the same context as the other commands in the array.
+
@section helpercmdprimer Command Development Primer
This @ref primercommand provides details about the @c hello module,
diff --git a/doc/manual/primer/commands.txt b/doc/manual/primer/commands.txt
index b15f6697..c9db7ccb 100644
--- a/doc/manual/primer/commands.txt
+++ b/doc/manual/primer/commands.txt
@@ -63,42 +63,71 @@ 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
+
+static const struct command_registration hello_command_handlers[] = {
+ {
+ .name = "hello",
+ .mode = COMMAND_ANY,
+ .handler = &handle_hello_command,
+ .help = "print a warm greetings",
+ .usage = "[<name>]",
+ },
+ {
+ .chain = foo_command_handlers,
+ }
+ COMMAND_REGISTRATION_DONE
+};
+
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;
+ return register_commands(cmd_ctx, NULL, handle_command_handlers);
}
@endcode
That's it! The command should now be registered and avaiable to scripts.
+@section primercmdchain Command Chaining
+
+This example also shows how to chain command handler registration, so
+your modules can "inherit" commands provided by other (sub)modules.
+Here, the hello module includes the foo commands in the same context
+that the 'hello' command will be registered.
+
+If the @c chain field had been put in the 'hello' command, then the
+@c foo module commands would be registered under it. Indeed, that
+technique is used to define the 'foo bar' and 'foo baz' commands,
+as well as for the example drivers that use these modules.
+
+The code for the 'foo' command handlers can be found in @c hello.c.
+
@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.
+These commands have been inherited by the dummy interface, faux flash,
+and testee target drivers. The easiest way to test these is by using the
+dummy interface.
-Once OpenOCD has been built with this example code, the following script
-demonstrate the abilities that the @c hello module provides:
+Once OpenOCD has been built with this example code, the following command
+demonstrates the abilities that the @c hello module provides:
@code
-hello
-hello World
-hello {John Doe}
-hello John Doe # error: too many arguments
+openocd -c 'interface dummy' \
+ -c 'dummy hello' \
+ -c 'dummy hello World' \
+ -c 'dummy hello {John Doe}' \
+ -c 'dummy 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:
+should produce the following output before displaying the help text and
+exiting:
@code
Greetings!
Greetings, World!
Greetings, John Doe!
-Error: ocd_hello: too many arguments
+Error: hello: too many arguments
+Runtime error, file "openocd.cfg", line 14:
+ hello: too many arguments
+dummy hello [<name>]
+ prints a warm welcome
@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.
-
*/