doc: expand README.commands

Describe U_BOOT_CMD_COMPLETE.
Describe the arguments of U_BOOT_CMD and U_BOOT_CMD_COMPLETE.
Describe the arguments of the command function.
Describe the arguments of the completion function.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
This commit is contained in:
Heinrich Schuchardt 2018-05-10 15:57:27 +02:00 committed by Tom Rini
parent 78ccbd1395
commit 3d9640f55c

View file

@ -1,19 +1,83 @@
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() macro
to fill in a cmd_tbl_t struct.
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(name, maxargs, repeatable, command, "usage", "help")
U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)
name: is the name of the commad. THIS IS NOT a string.
maxargs: the maximum number of arguments this function takes
repeatable: either 0 or 1 to indicate if autorepeat is allowed
command: Function pointer (*cmd)(struct cmd_tbl_s *, int, int, char *[]);
usage: Short description. This is a string
help: Long description. This is a string
name: The name of the command. THIS IS NOT a string.
maxargs: The maximum number of arguments this function takes including
the command itself.
**** Behind the scene ******
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