You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

137 lines
5.0 KiB

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