101 lines
3.3 KiB
Plaintext
101 lines
3.3 KiB
Plaintext
/** @page helperdocs OpenOCD Helper APIs
|
|
|
|
OpenOCD uses several low-level APIs as the foundation for high-level APIs:
|
|
|
|
- @subpage helperporting
|
|
- @subpage helperjim
|
|
- @subpage helpercommand
|
|
- @subpage helperlogging
|
|
- @subpage helperbuffers
|
|
|
|
This section needs to be expanded.
|
|
|
|
*/
|
|
|
|
/** @page helperporting OpenOCD Types/Portability APIs
|
|
|
|
This section needs to be expanded to describe OpenOCD's type and
|
|
portability API.
|
|
|
|
*/
|
|
|
|
/** @page helperjim OpenOCD Jim API
|
|
|
|
The Jim API provides access to a small-footprint TCL implementation.
|
|
|
|
Visit http://jim.berlios.de/ for more information on Jim.
|
|
|
|
This section needs to be expanded to describe OpenOCD's Jim API.
|
|
|
|
*/
|
|
|
|
/** @page helpercommand OpenOCD 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 modlue using a standard
|
|
interfaces. 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 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 @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 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_COMMAND - 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 helpercmdprimer Command Development Primer
|
|
|
|
This @ref primercommand provides details about the @c hello module,
|
|
showing how the pieces desrcribed on this page fit together.
|
|
|
|
*/
|
|
|
|
/** @page helperlogging OpenOCD Logging API
|
|
|
|
This section needs to be expanded to describe OpenOCD's Logging API.
|
|
|
|
*/
|
|
|
|
/** @page helperbuffers OpenOCD Byte Buffer API
|
|
|
|
This section needs to be expanded to describe OpenOCD's Byte Buffer API.
|
|
|
|
*/
|