commands.rst 6.1 KB

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