doc/manual/primer/commands.txt

   1 /** @page primercommand Command Development Primer
   2
   3 This page provides a primer for writing commands by introducing @c hello
   4 module.  The full source code used in this example can be found in
   5 hello.c, and the @ref primercmdcode section shows how to use it.
   6
   7 A summary of this information can be found in @ref helpercommand .
   8
   9 @section primercmdhandler Command Handlers
  10
  11 Defining new commands and their helpers is easy.  The following code
  12 defines a simple command handler that delegates its argument parsing:
  13 @code
  14 COMMAND_HANDLER(handle_hello_command)
  15 {
  16         const char *sep, *name;
  17         int retval = CALL_COMMAND_HANDLER(handle_hello_args);
  18         if (ERROR_OK == retval)
  19                 command_print(CMD_CTX, "Greetings%s%s!", sep, name);
  20         return retval;
  21 }
  22 @endcode
  23
  24 Here, the @c COMMAND_HANDLER macro establishes the function signature,
  25 see in command.h by the @c __COMMAND_HANDLER macro.
  26
  27 The COMMAND_HELPER macro function allows defining functions with an
  28 extended version of the base signature.  These helper functions can be
  29 called (with the appropriate parameters), the @c CALL_COMMAND_HANDLER
  30 macro to pass any e as parameters to the following helper function:
  31
  32 The subsequent blocks of code are a normal C function that can do
  33 anything, so only complex commands deserve should use comamnd helper
  34 functions.  In this respect, this example uses one to demonstrate how --
  35 not when -- they should be used.
  36
  37 @code
  38 static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
  39 {
  40         if (argc > 1)
  41         {
  42                 LOG_ERROR("%s: too many arguments", CMD_NAME);
  43                 return ERROR_COMMAND_SYNTAX_ERROR;
  44         }
  45         if (1 == CMD_ARGC)
  46         {
  47                 *sep = ", ";
  48                 *name = CMD_ARGV[0];
  49         }
  50         else
  51                 *sep = *name = "";
  52
  53         return ERROR_OK;
  54 }
  55 @endcode
  56
  57 Of course, you may also call other macros or functions, but that extends
  58 beyond the scope of this tutorial on writing commands.
  59
  60 @section primercmdreg Command Registration
  61
  62 Before this new function can be used, it must be registered somehow.
  63 For a new module, registering should be done in a new function for
  64 the purpose, which must be called from @c openocd.c:
  65 @code
  66 int hello_register_commands(struct command_context_s *cmd_ctx)
  67 {
  68         struct command_s *cmd = register_command(cmd_ctx, NULL, "hello",
  69                         NULL, COMMAND_ANY, "print greetings");
  70         return cmd ? ERROR_OK : -ENOMEM;
  71 }
  72 @endcode
  73
  74 That's it!  The command should now be registered and avaiable to scripts.
  75
  76 @section primercmdcode Trying These Example Commands
  77
  78 The commands may be enabled by editing src/openocd.c and uncommenting
  79 the call to @c hello_register_commands and rebuilding the source tree.
  80
  81 Once OpenOCD has been built with this example code, the following script
  82 demonstrate the abilities that the @c hello module provides:
  83 @code
  84 hello
  85 hello World
  86 hello {John Doe}
  87 hello John Doe  # error: too many arguments
  88 @endcode
  89
  90 If saved in @c hello.cfg, then running <code>openocd -f hello.cfg</code>
  91 should produce the following output before exiting:
  92 @code
  93 Greetings!
  94 Greetings, World!
  95 Greetings, John Doe!
  96 Error: ocd_hello: too many arguments
  97 @endcode
  98
  99 This difference between the registered and displayed command name comes from
 100 the fact that the TCL scripts are provided with a stub that calls the munged
 101 name.  This stub wraps the internal <code>ocd_</code>-prefixed routine,
 102 providing a measure of high-level error handling.
 103
 104  */