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
  67 static const struct command_registration hello_command_handlers[] = {
  68         {
  69                 .name = "hello",
  70                 .mode = COMMAND_ANY,
  71                 .handler = handle_hello_command,
  72                 .help = "print a warm greeting",
  73                 .usage = "[name]",
  74         },
  75         {
  76                 .chain = foo_command_handlers,
  77         }
  78         COMMAND_REGISTRATION_DONE
  79 };
  80
  81 int hello_register_commands(struct command_context_s *cmd_ctx)
  82 {
  83         return register_commands(cmd_ctx, NULL, handle_command_handlers);
  84 }
  85 @endcode
  86
  87 Note that the "usage" text should use the same EBNF that's found
  88 in the User's Guide:  literals in 'single quotes', sequences of
  89 optional parameters in [square brackets], and alternatives in
  90 (parentheses|with|vertical bars), and so forth.  No angle brackets.
  91
  92 That's it!  The command should now be registered and available to scripts.
  93
  94 @section primercmdchain Command Chaining
  95
  96 This example also shows how to chain command handler registration, so
  97 your modules can "inherit" commands provided by other (sub)modules.
  98 Here, the hello module includes the foo commands in the same context
  99 that the 'hello' command will be registered.
 100
 101 If the @c chain field had been put in the 'hello' command, then the
 102 @c foo module commands would be registered under it.  Indeed, that
 103 technique is used to define the 'foo bar' and 'foo baz' commands,
 104 as well as for the example drivers that use these modules.
 105
 106 The code for the 'foo' command handlers can be found in @c hello.c.
 107
 108 @section primercmdcode Trying These Example Commands
 109
 110 These commands have been inherited by the dummy interface, faux flash,
 111 and testee target drivers.  The easiest way to test these is by using the
 112 dummy interface.
 113
 114 Once OpenOCD has been built with this example code, the following command
 115 demonstrates the abilities that the @c hello module provides:
 116 @code
 117 openocd -c 'interface dummy' \
 118         -c 'dummy hello' \
 119         -c 'dummy hello World' \
 120         -c 'dummy hello {John Doe}' \
 121         -c 'dummy hello John Doe'  # error: too many arguments
 122 @endcode
 123
 124 If saved in @c hello.cfg, then running <code>openocd -f hello.cfg</code>
 125 should produce the following output before displaying the help text and
 126 exiting:
 127 @code
 128 Greetings!
 129 Greetings, World!
 130 Greetings, John Doe!
 131 Error: hello: too many arguments
 132 Runtime error, file "openocd.cfg", line 14:
 133     hello: too many arguments
 134 dummy hello [<name>]
 135       prints a warm welcome
 136 @endcode
 137
 138  */