[thirdparty/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 cmd_tbl_t 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.

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

The commmand function pointer has to be of type
int (*cmd)(struct cmd_tbl_s *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_SUCCESS	The command was successfully executed.

CMD_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*)));
	}
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 HS	5	This is done by first including command.h, then using the U_BOOT_CMD() or the
3d9640f5 HS	6	U_BOOT_CMD_COMPLETE macro to fill in a cmd_tbl_t 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
	31	Command function
	32	----------------
	33
	34	The commmand function pointer has to be of type
	35	int (cmd)(struct cmd_tbl_s cmdtp, int flag, int argc, const char *argv[]);
	36
	37	cmdtp: Table entry describing the command (see above).
	38
	39	flag: A bitmap which may contain the following bit:
	40	CMD_FLAG_REPEAT - The last command is repeated.
	41	CMD_FLAG_BOOTD - The command is called by the bootd command.
	42	CMD_FLAG_ENV - The command is called by the run command.
	43
	44	argc: Number of arguments including the command.
	45
	46	argv: Arguments.
	47
	48	Allowable return value are:
	49
	50	CMD_SUCCESS The command was successfully executed.
	51
	52	CMD_FAILURE The command failed.
	53
	54	CMD_RET_USAGE The command was called with invalid parameters. This value
	55	leads to the display of the usage string.
	56
	57	Completion function
	58	-------------------
	59
	60	The completion function pointer has to be of type
	61	int (complete)(int argc, char const argv[], char last_char,
	62	int maxv, char *cmdv[]);
	63
	64	argc: Number of arguments including the command.
	65
	66	argv: Arguments.
	67
	68	last_char: The last character in the command line buffer.
	69
	70	maxv: Maximum number of possible completions that may be returned by
	71	the function.
	72
	73	cmdv: Used to return possible values for the last argument. The last
	74	possible completion must be followed by NULL.
	75
	76	The function returns the number of possible completions (without the terminating
	77	NULL value).
	78
	79	Behind the scene
80	----------------
0d498393	81
ef123c52 AA	82	The structure created is named with a special prefix and placed by
	83	the linker in a special section using the linker lists mechanism
	84	(see include/linker_lists.h)
0d498393 WD	85
	86	This makes it possible for the final link to extract all commands
	87	compiled into any object code and construct a static array so the
ef123c52	88	command array can be iterated over using the linker lists macros.
0d498393	89
ef123c52 AA	90	The linker lists feature ensures that the linker does not discard
	91	these symbols when linking full U-Boot even though they are not
	92	referenced in the source code as such.
2d1d6583	93
0d498393	94	If a new board is defined do not forget to define the command section
4379ac61	95	by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
0d498393 WD	96	3 lines:
0d498393 WD	97
6c7c946c	98	.u_boot_list : {
ef123c52	99	KEEP((SORT(.u_boot_list)));
6c7c946c	100	}