[J-u-boot.git] / doc / README.commands

Command definition
------------------

Commands are added to U-Boot by creating a new command structure.
This is done by first including command.h, then using the U_BOOT_CMD() or the
U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl struct.

U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help")
U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)

name:		The name of the command. THIS IS NOT a string.

maxargs:	The maximum number of arguments this function takes including
		the command itself.

repeatable:	Either 0 or 1 to indicate if autorepeat is allowed.

command:	Pointer to the command function. This is the function that is
		called when the command is issued.

usage:		Short description. This is a string.

help:		Long description. This is a string. The long description is
		only available if CONFIG_SYS_LONGHELP is defined.

comp:		Pointer to the completion function. May be NULL.
		This function is called if the user hits the TAB key while
		entering the command arguments to complete the entry. Command
		completion is only available if CONFIG_AUTO_COMPLETE is defined.

Sub-command definition
----------------------

Likewise an array of struct cmd_tbl holding sub-commands can be created using either
of the following macros:

* U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help")
* U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help",
  comp)

This table has to be evaluated in the command function of the main command, e.g.

    static struct cmd_tbl cmd_sub[] = {
        U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""),
        U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""),
    };

    static int do_cmd(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])
    {
        struct cmd_tbl *cp;

        if (argc < 2)
                return CMD_RET_USAGE;

        /* drop sub-command argument */
        argc--;
        argv++;

        cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub));

        if (cp)
            return cp->cmd(cmdtp, flag, argc, argv);

        return CMD_RET_USAGE;
    }

Command function
----------------

The command function pointer has to be of type
int (*cmd)(struct cmd_tbl *cmdtp, int flag, int argc, const char *argv[]);

cmdtp:		Table entry describing the command (see above).

flag:		A bitmap which may contain the following bit:
		CMD_FLAG_REPEAT - The last command is repeated.
		CMD_FLAG_BOOTD  - The command is called by the bootd command.
		CMD_FLAG_ENV    - The command is called by the run command.

argc:		Number of arguments including the command.

argv:		Arguments.

Allowable return value are:

CMD_RET_SUCCESS	The command was successfully executed.

CMD_RET_FAILURE	The command failed.

CMD_RET_USAGE	The command was called with invalid parameters. This value
		leads to the display of the usage string.

Completion function
-------------------

The completion function pointer has to be of type
int (*complete)(int argc, char *const argv[], char last_char,
		int maxv, char *cmdv[]);

argc:		Number of arguments including the command.

argv:		Arguments.

last_char:	The last character in the command line buffer.

maxv:		Maximum number of possible completions that may be returned by
		the function.

cmdv:		Used to return possible values for the last argument. The last
		possible completion must be followed by NULL.

The function returns the number of possible completions (without the terminating
NULL value).

Behind the scene
----------------

The structure created is named with a special prefix and placed by
the linker in a special section using the linker lists mechanism
(see include/linker_lists.h)

This makes it possible for the final link to extract all commands
compiled into any object code and construct a static array so the
command array can be iterated over using the linker lists macros.

The linker lists feature ensures that the linker does not discard
these symbols when linking full U-Boot even though they are not
referenced in the source code as such.

If a new board is defined do not forget to define the command section
by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
3 lines:

	.u_boot_list : {
		KEEP(*(SORT(.u_boot_list*)));
	}

Writing tests
-------------

All new commands should have tests. Tests for existing commands are very
welcome.

It is fairly easy to write a test for a command. Enable it in sandbox, and
then add code that runs the command and checks the output.

Here is an example:

/* Test 'acpi items' command */
static int dm_test_acpi_cmd_items(struct unit_test_state *uts)
{
	struct acpi_ctx ctx;
	void *buf;

	buf = malloc(BUF_SIZE);
	ut_assertnonnull(buf);

	ctx.current = buf;
	ut_assertok(acpi_fill_ssdt(&ctx));
	console_record_reset();
	run_command("acpi items", 0);
	ut_assert_nextline("dev 'acpi-test', type 1, size 2");
	ut_assert_nextline("dev 'acpi-test2', type 1, size 2");
	ut_assert_console_end();

	ctx.current = buf;
	ut_assertok(acpi_inject_dsdt(&ctx));
	console_record_reset();
	run_command("acpi items", 0);
	ut_assert_nextline("dev 'acpi-test', type 2, size 2");
	ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
	ut_assert_console_end();

	console_record_reset();
	run_command("acpi items -d", 0);
	ut_assert_nextline("dev 'acpi-test', type 2, size 2");
	ut_assert_nextlines_are_dump(2);
	ut_assert_nextline("%s", "");
	ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
	ut_assert_nextlines_are_dump(2);
	ut_assert_nextline("%s", "");
	ut_assert_console_end();

	return 0;
}
DM_TEST(dm_test_acpi_cmd_items, DM_TESTF_SCAN_PDATA | DM_TESTF_SCAN_FDT);
Commit	Line	Data
3d9640f5 HS	1	Command definition
3d9640f5 HS	2	------------------
0d498393 WD	3
0d498393 WD	4	Commands are added to U-Boot by creating a new command structure.
3d9640f5	5	This is done by first including command.h, then using the U_BOOT_CMD() or the
09140113	6	U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl struct.
0d498393	7
3d9640f5 HS	8	U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help")
3d9640f5 HS	9	U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)
0d498393	10
3d9640f5	11	name: The name of the command. THIS IS NOT a string.
0d498393	12
3d9640f5 HS	13	maxargs: The maximum number of arguments this function takes including
3d9640f5 HS	14	the command itself.
0d498393	15
3d9640f5 HS	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
ca80b561 HS	31	Sub-command definition
	32	----------------------
	33
09140113	34	Likewise an array of struct cmd_tbl holding sub-commands can be created using either
ca80b561 HS	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
09140113	43	static struct cmd_tbl cmd_sub[] = {
ca80b561 HS	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
09140113	48	static int do_cmd(struct cmd_tbl cmdtp, int flag, int argc, char const argv[])
ca80b561	49	{
09140113	50	struct cmd_tbl *cp;
ca80b561 HS	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
3d9640f5 HS	67	Command function
	68	----------------
	69
f3ccba3e	70	The command function pointer has to be of type
09140113	71	int (cmd)(struct cmd_tbl cmdtp, int flag, int argc, const char *argv[]);
3d9640f5 HS	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
4dbc107f	86	CMD_RET_SUCCESS The command was successfully executed.
3d9640f5	87
4dbc107f	88	CMD_RET_FAILURE The command failed.
3d9640f5 HS	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	----------------
0d498393	117
ef123c52 AA	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)
0d498393 WD	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
ef123c52	124	command array can be iterated over using the linker lists macros.
0d498393	125
ef123c52 AA	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.
2d1d6583	129
0d498393	130	If a new board is defined do not forget to define the command section
4379ac61	131	by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
0d498393 WD	132	3 lines:
0d498393 WD	133
6c7c946c	134	.u_boot_list : {
ef123c52	135	KEEP((SORT(.u_boot_list)));
6c7c946c	136	}
58978114 SG	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);