blob: 4e9e8098fa81a8090fac38c0391815c5b6bfaa1f [file] [log] [blame]
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +02001Command definition
2------------------
wdenk0d498392003-07-01 21:06:45 +00003
4Commands are added to U-Boot by creating a new command structure.
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +02005This is done by first including command.h, then using the U_BOOT_CMD() or the
6U_BOOT_CMD_COMPLETE macro to fill in a cmd_tbl_t struct.
wdenk0d498392003-07-01 21:06:45 +00007
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +02008U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help")
9U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)
wdenk0d498392003-07-01 21:06:45 +000010
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020011name: The name of the command. THIS IS NOT a string.
wdenk0d498392003-07-01 21:06:45 +000012
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020013maxargs: The maximum number of arguments this function takes including
14 the command itself.
wdenk0d498392003-07-01 21:06:45 +000015
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020016repeatable: Either 0 or 1 to indicate if autorepeat is allowed.
17
18command: Pointer to the command function. This is the function that is
19 called when the command is issued.
20
21usage: Short description. This is a string.
22
23help: Long description. This is a string. The long description is
24 only available if CONFIG_SYS_LONGHELP is defined.
25
26comp: 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
Heinrich Schuchardtca80b562018-12-21 02:57:03 +010031Sub-command definition
32----------------------
33
34Likewise an array of cmd_tbl_t holding sub-commands can be created using either
35of 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
41This table has to be evaluated in the command function of the main command, e.g.
42
43 static cmd_tbl_t 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(cmd_tbl_t *cmdtp, int flag, int argc, char * const argv[])
49 {
50 cmd_tbl_t *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
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020067Command function
68----------------
69
Heinrich Schuchardtf3ccba32018-12-30 13:00:51 +010070The command function pointer has to be of type
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020071int (*cmd)(struct cmd_tbl_s *cmdtp, int flag, int argc, const char *argv[]);
72
73cmdtp: Table entry describing the command (see above).
74
75flag: 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
80argc: Number of arguments including the command.
81
82argv: Arguments.
83
84Allowable return value are:
85
Luka Kovacic4dbc1072020-01-05 20:10:56 +010086CMD_RET_SUCCESS The command was successfully executed.
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020087
Luka Kovacic4dbc1072020-01-05 20:10:56 +010088CMD_RET_FAILURE The command failed.
Heinrich Schuchardt3d9640f2018-05-10 15:57:27 +020089
90CMD_RET_USAGE The command was called with invalid parameters. This value
91 leads to the display of the usage string.
92
93Completion function
94-------------------
95
96The completion function pointer has to be of type
97int (*complete)(int argc, char *const argv[], char last_char,
98 int maxv, char *cmdv[]);
99
100argc: Number of arguments including the command.
101
102argv: Arguments.
103
104last_char: The last character in the command line buffer.
105
106maxv: Maximum number of possible completions that may be returned by
107 the function.
108
109cmdv: Used to return possible values for the last argument. The last
110 possible completion must be followed by NULL.
111
112The function returns the number of possible completions (without the terminating
113NULL value).
114
115Behind the scene
116----------------
wdenk0d498392003-07-01 21:06:45 +0000117
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000118The structure created is named with a special prefix and placed by
119the linker in a special section using the linker lists mechanism
120(see include/linker_lists.h)
wdenk0d498392003-07-01 21:06:45 +0000121
122This makes it possible for the final link to extract all commands
123compiled into any object code and construct a static array so the
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000124command array can be iterated over using the linker lists macros.
wdenk0d498392003-07-01 21:06:45 +0000125
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000126The linker lists feature ensures that the linker does not discard
127these symbols when linking full U-Boot even though they are not
128referenced in the source code as such.
Tom Rini2d1d6582012-09-20 06:02:43 +0000129
wdenk0d498392003-07-01 21:06:45 +0000130If a new board is defined do not forget to define the command section
Masahiro Yamada4379ac62014-03-11 11:05:19 +0900131by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
wdenk0d498392003-07-01 21:06:45 +00001323 lines:
133
Marek Vasut6c7c9462012-10-12 10:27:04 +0000134 .u_boot_list : {
Albert ARIBAUDef123c52013-02-25 00:59:00 +0000135 KEEP(*(SORT(.u_boot_list*)));
Marek Vasut6c7c9462012-10-12 10:27:04 +0000136 }