X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2FREADME.commands;h=e03eb44187edd43ce495d374c8904b03036b0b57;hb=80be404a25953ff14743705f2ec7403eb894c6f5;hp=07825b9a05c9782cf32f25bed6ec84a409f2b815;hpb=1d0350ed0b1b0f63e3fb5db6b19397b84a2ea1c7;p=platform%2Fkernel%2Fu-boot.git diff --git a/doc/README.commands b/doc/README.commands index 07825b9..e03eb44 100644 --- a/doc/README.commands +++ b/doc/README.commands @@ -1,100 +1,136 @@ -# -# The commands in this table are sorted alphabetically by the -# command name and in descending order by the command name string -# length. This is to prevent conflicts in command name parsing. -# Please ensure that new commands are added according to that rule. -# See $(TOPDIR)/common/command.c -# -######################## -# -# command length -# -######################## -askenv 8 -as 2 -autoscr 5 -base 2 -bdinfo 2 -bootelf 7 -bootm 5 -bootp 5 -bootvx 6 -bootd 4 -break 2 -brginfo 3 -carinfo 3 -chpart 6 -cmp 3 -coninfo 5 -continue 4 -cp 2 -crc32 3 -date 3 -dcache 2 -dhcp 4 -dmainfo 3 -ds 2 -dtt 3 -echo 4 -eeprom 3 -erase 3 -fccinfo 3 -fdcboot 4 -flinfo 3 -fpga 4 -fsinfo 5 -fsload 5 -getdcr 6 # IBM 4XX DCR registers -go 2 -help 1 -i2cinfo 4 -i2c 3 -icache 2 -icinfo 3 -ide 3 -iminfo 3 -iopinfo 3 -irqinfo 3 -kgdb 4 -loadb 5 -loads 5 -loop 4 -ls 2 -mccinfo 3 -md 2 -memcinfo 4 -mii 3 -mm 2 -mtest 5 -muxinfo 3 -mw 2 -next 4 -nm 2 -pciinfo 3 -pinit 4 -printenv 8 -protect 4 -rarpboot 4 -rdump 5 -reginfo 3 -reset 5 -run 3 -saveenv 4 -sccinfo 3 -scsiboot 5 -scsi 4 -siiinfo 3 -sitinfo 3 -siuinfo 3 -setdcr 6 # IBM 4XX DCR registers -setenv 6 -smcinfo 3 -spiinfo 3 -sspi 4 -stack 5 -step 4 -tftpboot 4 -usbboot 5 -usb 4 -version 4 -? 1 +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. + +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 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*))); + }