1Command definition
2------------------
3
4Commands are added to U-Boot by creating a new command structure.
5This is done by first including command.h, then using the U_BOOT_CMD() or the
6U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl struct.
7
8U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help")
9U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)
10
11name:		The name of the command. THIS IS NOT a string.
12
13maxargs:	The maximum number of arguments this function takes including
14		the command itself.
15
16repeatable:	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
31Sub-command definition
32----------------------
33
34Likewise an array of struct cmd_tbl 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 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
67Command function
68----------------
69
70The command function pointer has to be of type
71int (*cmd)(struct cmd_tbl *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
86CMD_RET_SUCCESS	The command was successfully executed.
87
88CMD_RET_FAILURE	The command failed.
89
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----------------
117
118The 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)
121
122This makes it possible for the final link to extract all commands
123compiled into any object code and construct a static array so the
124command array can be iterated over using the linker lists macros.
125
126The 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.
129
130If a new board is defined do not forget to define the command section
131by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
1323 lines:
133
134	.u_boot_list : {
135		KEEP(*(SORT(.u_boot_list*)));
136	}
137
138Writing tests
139-------------
140
141All new commands should have tests. Tests for existing commands are very
142welcome.
143
144It is fairly easy to write a test for a command. Enable it in sandbox, and
145then add code that runs the command and checks the output.
146
147Here is an example:
148
149/* Test 'acpi items' command */
150static 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}
186DM_TEST(dm_test_acpi_cmd_items, DM_TESTF_SCAN_PDATA | DM_TESTF_SCAN_FDT);
187