The Jim API provides access to a small-footprint TCL implementation.
-Visit http://jim.berlios.de/ for more information on Jim.
+Visit http://jim.tcl.tk/ for more information on Jim.
This section needs to be expanded to describe OpenOCD's Jim API.
/** @page helpercommand OpenOCD Command API
-This section needs to be expanded to describe OpenOCD's Command API.
+OpenOCD's command API allows modules to register callbacks that are then
+available to the scripting services. It provides the mechanism for
+these commands to be dispatched to the module using a standard
+interface. It provides macros for defining functions that use and
+extend this interface.
+
+@section helpercmdhandler Command Handlers
+
+Command handlers are functions with a particular signature, which can
+be extended by modules for passing additional parameters to helpers or
+another layer of handlers.
+
+@subsection helpercmdhandlerdef Defining and Calling Command Handlers
+
+These functions should be defined using the @c COMMAND_HANDLER macro.
+These methods must be defined as static, as their principal 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 @c COMMAND_HELPER. These must be
+declared static by you, as sometimes you might want to share a helper
+among several files (e.g. @c s3c24xx_nand.h).
+
+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 be a name or function pointer). Calls to helpers and
+derived handlers must pass those extra parameters specified by their
+definitions; however, lexical capture is used for the core parameters.
+This dirty trick is being used as a stop-gap measure while the API is
+migrated to one that passes a pointer to a structure containing the
+same ingredients. At that point, this macro will be removed and callers
+will be able to use direct invocations.
+
+Thus, the following macros can be used to define and call command
+handlers or helpers:
+
+- @c COMMAND_HANDLER - declare or define a command handler.
+- @c COMMAND_HELPER - declare or define a derived command handler or helper.
+- @c CALL_COMMAND_HANDLER - call a command handler/helper.
+
+@subsection helpercmdhandlermacros Command Handler Macros
+
+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 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,
+showing how the pieces described on this page fit together.
*/
Code Review / openocd.git / blobdiff