X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2FREADME.commands;h=e03eb44187edd43ce495d374c8904b03036b0b57;hb=a8973731a452323e8767e8f9775c7d06921ebed5;hp=27815d2ba18faada4344e68ed65ac3b188569797;hpb=2acca35ce4604dcef933f07d90aa9c9c930e1049;p=oweals%2Fu-boot.git diff --git a/doc/README.commands b/doc/README.commands index 27815d2ba1..e03eb44187 100644 --- a/doc/README.commands +++ b/doc/README.commands @@ -1,31 +1,136 @@ +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. -The structure created is named with a special prefix (__u_boot_cmd_) -and placed by the linker in a special section. +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 cmd_tbl_t 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 cmd_tbl_t 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(cmd_tbl_t *cmdtp, int flag, int argc, char * const argv[]) + { + cmd_tbl_t *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_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 can be found in an array starting at __u_boot_cmd_start. +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 ($(TOPDIR)/board/boardname/u-boot.lds) these +by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these 3 lines: - __u_boot_cmd_start = .; - .u_boot_cmd : { *(.u_boot_cmd) } - __u_boot_cmd_end = .; + .u_boot_list : { + KEEP(*(SORT(.u_boot_list*))); + }