doc/README.commands

   1 Command definition
   2 ------------------
   3
   4 Commands are added to U-Boot by creating a new command structure.
   5 This is done by first including command.h, then using the U_BOOT_CMD() or the
   6 U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl struct.
   7
   8 U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help")
   9 U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)
  10
  11 name:           The name of the command. THIS IS NOT a string.
  12
  13 maxargs:        The maximum number of arguments this function takes including
  14                 the command itself.
  15
  16 repeatable:     Either 0 or 1 to indicate if autorepeat is allowed.
  17
  18 command:        Pointer to the command function. This is the function that is
  19                 called when the command is issued.
  20
  21 usage:          Short description. This is a string.
  22
  23 help:           Long description. This is a string. The long description is
  24                 only available if CONFIG_SYS_LONGHELP is defined.
  25
  26 comp:           Pointer to the completion function. May be NULL.
  27                 This function is called if the user hits the TAB key while
  28                 entering the command arguments to complete the entry. Command
  29                 completion is only available if CONFIG_AUTO_COMPLETE is defined.
  30
  31 Sub-command definition
  32 ----------------------
  33
  34 Likewise an array of struct cmd_tbl holding sub-commands can be created using either
  35 of the following macros:
  36
  37 * U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help")
  38 * U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help",
  39   comp)
  40
  41 This table has to be evaluated in the command function of the main command, e.g.
  42
  43     static struct cmd_tbl cmd_sub[] = {
  44         U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""),
  45         U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""),
  46     };
  47
  48     static int do_cmd(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])
  49     {
  50         struct cmd_tbl *cp;
  51
  52         if (argc < 2)
  53                 return CMD_RET_USAGE;
  54
  55         /* drop sub-command argument */
  56         argc--;
  57         argv++;
  58
  59         cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub));
  60
  61         if (cp)
  62             return cp->cmd(cmdtp, flag, argc, argv);
  63
  64         return CMD_RET_USAGE;
  65     }
  66
  67 Command function
  68 ----------------
  69
  70 The command function pointer has to be of type
  71 int (*cmd)(struct cmd_tbl *cmdtp, int flag, int argc, const char *argv[]);
  72
  73 cmdtp:          Table entry describing the command (see above).
  74
  75 flag:           A bitmap which may contain the following bit:
  76                 CMD_FLAG_REPEAT - The last command is repeated.
  77                 CMD_FLAG_BOOTD  - The command is called by the bootd command.
  78                 CMD_FLAG_ENV    - The command is called by the run command.
  79
  80 argc:           Number of arguments including the command.
  81
  82 argv:           Arguments.
  83
  84 Allowable return value are:
  85
  86 CMD_RET_SUCCESS The command was successfully executed.
  87
  88 CMD_RET_FAILURE The command failed.
  89
  90 CMD_RET_USAGE   The command was called with invalid parameters. This value
  91                 leads to the display of the usage string.
  92
  93 Completion function
  94 -------------------
  95
  96 The completion function pointer has to be of type
  97 int (*complete)(int argc, char *const argv[], char last_char,
  98                 int maxv, char *cmdv[]);
  99
 100 argc:           Number of arguments including the command.
 101
 102 argv:           Arguments.
 103
 104 last_char:      The last character in the command line buffer.
 105
 106 maxv:           Maximum number of possible completions that may be returned by
 107                 the function.
 108
 109 cmdv:           Used to return possible values for the last argument. The last
 110                 possible completion must be followed by NULL.
 111
 112 The function returns the number of possible completions (without the terminating
 113 NULL value).
 114
 115 Behind the scene
 116 ----------------
 117
 118 The structure created is named with a special prefix and placed by
 119 the linker in a special section using the linker lists mechanism
 120 (see include/linker_lists.h)
 121
 122 This makes it possible for the final link to extract all commands
 123 compiled into any object code and construct a static array so the
 124 command array can be iterated over using the linker lists macros.
 125
 126 The linker lists feature ensures that the linker does not discard
 127 these symbols when linking full U-Boot even though they are not
 128 referenced in the source code as such.
 129
 130 If a new board is defined do not forget to define the command section
 131 by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
 132 3 lines:
 133
 134         .u_boot_list : {
 135                 KEEP(*(SORT(.u_boot_list*)));
 136         }
 137
 138 Writing tests
 139 -------------
 140
 141 All new commands should have tests. Tests for existing commands are very
 142 welcome.
 143
 144 It is fairly easy to write a test for a command. Enable it in sandbox, and
 145 then add code that runs the command and checks the output.
 146
 147 Here is an example:
 148
 149 /* Test 'acpi items' command */
 150 static int dm_test_acpi_cmd_items(struct unit_test_state *uts)
 151 {
 152         struct acpi_ctx ctx;
 153         void *buf;
 154
 155         buf = malloc(BUF_SIZE);
 156         ut_assertnonnull(buf);
 157
 158         ctx.current = buf;
 159         ut_assertok(acpi_fill_ssdt(&ctx));
 160         console_record_reset();
 161         run_command("acpi items", 0);
 162         ut_assert_nextline("dev 'acpi-test', type 1, size 2");
 163         ut_assert_nextline("dev 'acpi-test2', type 1, size 2");
 164         ut_assert_console_end();
 165
 166         ctx.current = buf;
 167         ut_assertok(acpi_inject_dsdt(&ctx));
 168         console_record_reset();
 169         run_command("acpi items", 0);
 170         ut_assert_nextline("dev 'acpi-test', type 2, size 2");
 171         ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
 172         ut_assert_console_end();
 173
 174         console_record_reset();
 175         run_command("acpi items -d", 0);
 176         ut_assert_nextline("dev 'acpi-test', type 2, size 2");
 177         ut_assert_nextlines_are_dump(2);
 178         ut_assert_nextline("%s", "");
 179         ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
 180         ut_assert_nextlines_are_dump(2);
 181         ut_assert_nextline("%s", "");
 182         ut_assert_console_end();
 183
 184         return 0;
 185 }
 186 DM_TEST(dm_test_acpi_cmd_items, DM_TESTF_SCAN_PDATA | DM_TESTF_SCAN_FDT);