target: uplevel add_{break,watch}point() error checks

[fw/openocd] / doc / manual / helper.txt

diff --git a/doc/manual/helper.txt b/doc/manual/helper.txt
index 7060607cd4d2e804d6146b0a4d3e635c7e24b720..aa52355f5dddb66a21f50b6aff5006ecf0304e45 100644 (file)
--- a/doc/manual/helper.txt
+++ b/doc/manual/helper.txt
@@ -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,54 @@ 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_s *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 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