Some minor URL fixes and typo fixes, no functional changes.
[openocd.git] / doc / manual / helper.txt
1 /** @page helperdocs OpenOCD Helper APIs
2
3 OpenOCD uses several low-level APIs as the foundation for high-level APIs:
4
5   - @subpage helperporting
6   - @subpage helperjim
7   - @subpage helpercommand
8   - @subpage helperlogging
9   - @subpage helperbuffers
10
11 This section needs to be expanded.
12
13  */
14
15 /** @page helperporting OpenOCD Types/Portability APIs
16
17 This section needs to be expanded to describe OpenOCD's type and
18 portability API.
19
20  */
21
22 /** @page helperjim OpenOCD Jim API
23
24 The Jim API provides access to a small-footprint TCL implementation.
25
26 Visit http://jim.tcl.tk/ for more information on Jim.
27
28 This section needs to be expanded to describe OpenOCD's Jim API.
29
30  */
31
32 /** @page helpercommand OpenOCD Command API
33
34 OpenOCD's command API allows modules to register callbacks that are then
35 available to the scripting services.  It provides the mechanism for
36 these commands to be dispatched to the module using a standard
37 interface.  It provides macros for defining functions that use and
38 extend this interface.
39
40 @section helpercmdhandler Command Handlers
41
42 Command handlers are functions with a particular signature, which can
43 be extended by modules for passing additional parameters to helpers or
44 another layer of handlers.
45
46 @subsection helpercmdhandlerdef Defining and Calling Command Handlers
47
48 These functions should be defined using the @c COMMAND_HANDLER macro.
49 These methods must be defined as static, as their principal entry point
50 should be the run_command dispatch mechanism.
51
52 Command helper functions that require access to the full set of
53 parameters should be defined using the @c COMMAND_HELPER.  These must be
54 declared static by you, as sometimes you might want to share a helper
55 among several files (e.g. @c s3c24xx_nand.h).
56
57 Both types of routines must be called using the @c CALL_COMMAND_HANDLER macro.
58 Calls using this macro to normal handlers require the name of the command
59 handler (which can be a name or function pointer).  Calls to helpers and
60 derived handlers must pass those extra parameters specified by their
61 definitions; however, lexical capture is used for the core parameters.
62 This dirty trick is being used as a stop-gap measure while the API is
63 migrated to one that passes a pointer to a structure containing the
64 same ingredients.  At that point, this macro will be removed and callers
65 will be able to use direct invocations.
66
67 Thus, the following macros can be used to define and call command
68 handlers or helpers:
69
70 - @c COMMAND_HANDLER - declare or define a command handler.
71 - @c COMMAND_HELPER - declare or define a derived command handler or helper.
72 - @c CALL_COMMAND_HANDLER - call a command handler/helper.
73
74 @subsection helpercmdhandlermacros Command Handler Macros
75
76 In addition, the following macros may be used in the context of
77 command handlers and helpers:
78 - @c CMD_CTX - the current @c command_context
79 - @c CMD_NAME - invoked command name
80 - @c CMD_ARGC - the number of command arguments
81 - @c CMD_ARGV - array of command argument strings
82
83 @section helpercmdregister Command Registration
84
85 In order to use a command handler, it must be registered with the
86 command subsystem.  All commands are registered with command_registration
87 structures, specifying the name of the command, its handler, its allowed
88 mode(s) of execution, and strings that provide usage and help text.
89 A single handler may be registered using multiple names, but any name
90 may have only one handler associated with it.
91
92 The @c register_commands() and @c register_commands() functions provide
93 registration, while the @c unregister_command() and
94 @c unregister_all_commands() functions will remove existing commands.
95 These may be called at any time, allowing the command set to change in
96 response to system actions.
97
98 @subsection helpercmdjim Jim Command Registration
99
100 The command_registration structure provides support for registering
101 native Jim command handlers (@c jim_handler) too.  For these handlers,
102 the module can provide help and usage support; however, this mechanism
103 allows Jim handlers to be called as sub-commands of other commands.
104 These commands may be registered with a private data value (@c
105 jim_handler_data) that will be available when called, as with low-level
106 Jim command registration.
107
108 A command may have a normal @c handler or a @c jim_handler, but not both.
109
110 @subsection helpercmdregisterchains Command Chaining
111
112 When using register_commands(), the array of commands may reference
113 other arrays.  When the @c chain field is filled in a
114 command_registration record, the commands on in the chained list will
115 added in one of two places.  If the record defines a new command, then
116 the chained commands are added under it; otherwise, the commands are
117 added in the same context as the other commands in the array.
118
119 @section helpercmdprimer Command Development Primer
120
121 This @ref primercommand provides details about the @c hello module,
122 showing how the pieces described on this page fit together.
123
124  */
125
126 /** @page helperlogging OpenOCD Logging API
127
128 This section needs to be expanded to describe OpenOCD's Logging API.
129
130  */
131
132 /** @page helperbuffers OpenOCD Byte Buffer API
133
134 This section needs to be expanded to describe OpenOCD's Byte Buffer API.
135
136  */