X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2FREADME.commands;h=716ad227aa1917261ccaf0bfd189f9f5693f9027;hb=32a8f800a96e8add063a31f6ef80d9ead3fcec04;hp=125f077c08ffc03f7cf549e6c54480e3a6a41b87;hpb=2d1d65838eacd314b989701bd2f9e2b657bbf62b;p=oweals%2Fu-boot.git diff --git a/doc/README.commands b/doc/README.commands index 125f077c08..716ad227aa 100644 --- a/doc/README.commands +++ b/doc/README.commands @@ -1,38 +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 struct cmd_tbl 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 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 can be found in an array starting at __u_boot_cmd_start. +command array can be iterated over using the linker lists macros. -To ensure that the linker does not discard these symbols when linking -full U-Boot we generate a list of all the commands we have built (based -on the sections mentioned above) and use that to force the linker to -first enter the symbol as undefined in the output object so that there -is then a need for the symbol to be kept (this is the UNDEF_SYM logic in -the Makefile). +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*))); + }