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.berlios.de/ 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 modlue using a standard
  37 interfaces.  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 principle 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 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_COMMAND - 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 helpercmdprimer Command Development Primer
  84
  85 This @ref primercommand provides details about the @c hello module,
  86 showing how the pieces desrcribed on this page fit together.
  87
  88  */
  89
  90 /** @page helperlogging OpenOCD Logging API
  91
  92 This section needs to be expanded to describe OpenOCD's Logging API.
  93
  94  */
  95
  96 /** @page helperbuffers OpenOCD Byte Buffer API
  97
  98 This section needs to be expanded to describe OpenOCD's Byte Buffer API.
  99
 100  */