From 3d9640f55cb22afd018135768209bd79a7907270 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Thu, 10 May 2018 15:57:27 +0200 Subject: [PATCH] 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 --- doc/README.commands | 84 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 74 insertions(+), 10 deletions(-) diff --git a/doc/README.commands b/doc/README.commands index afd5577..1d29c4d 100644 --- a/doc/README.commands +++ b/doc/README.commands @@ -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