doc/develop/commands.rst

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