1Command definition 2------------------ 3 4Commands are added to U-Boot by creating a new command structure. 5This is done by first including command.h, then using the U_BOOT_CMD() or the 6U_BOOT_CMD_COMPLETE macro to fill in a cmd_tbl_t struct. 7 8U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help") 9U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) 10 11name: The name of the command. THIS IS NOT a string. 12 13maxargs: The maximum number of arguments this function takes including 14 the command itself. 15 16repeatable: Either 0 or 1 to indicate if autorepeat is allowed. 17 18command: Pointer to the command function. This is the function that is 19 called when the command is issued. 20 21usage: Short description. This is a string. 22 23help: Long description. This is a string. The long description is 24 only available if CONFIG_SYS_LONGHELP is defined. 25 26comp: Pointer to the completion function. May be NULL. 27 This function is called if the user hits the TAB key while 28 entering the command arguments to complete the entry. Command 29 completion is only available if CONFIG_AUTO_COMPLETE is defined. 30 31Sub-command definition 32---------------------- 33 34Likewise an array of cmd_tbl_t holding sub-commands can be created using either 35of the following macros: 36 37* U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help") 38* U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help", 39 comp) 40 41This table has to be evaluated in the command function of the main command, e.g. 42 43 static cmd_tbl_t cmd_sub[] = { 44 U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""), 45 U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""), 46 }; 47 48 static int do_cmd(cmd_tbl_t *cmdtp, int flag, int argc, char * const argv[]) 49 { 50 cmd_tbl_t *cp; 51 52 if (argc < 2) 53 return CMD_RET_USAGE; 54 55 /* drop sub-command argument */ 56 argc--; 57 argv++; 58 59 cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub)); 60 61 if (cp) 62 return cp->cmd(cmdtp, flag, argc, argv); 63 64 return CMD_RET_USAGE; 65 } 66 67Command function 68---------------- 69 70The command function pointer has to be of type 71int (*cmd)(struct cmd_tbl_s *cmdtp, int flag, int argc, const char *argv[]); 72 73cmdtp: Table entry describing the command (see above). 74 75flag: A bitmap which may contain the following bit: 76 CMD_FLAG_REPEAT - The last command is repeated. 77 CMD_FLAG_BOOTD - The command is called by the bootd command. 78 CMD_FLAG_ENV - The command is called by the run command. 79 80argc: Number of arguments including the command. 81 82argv: Arguments. 83 84Allowable return value are: 85 86CMD_SUCCESS The command was successfully executed. 87 88CMD_FAILURE The command failed. 89 90CMD_RET_USAGE The command was called with invalid parameters. This value 91 leads to the display of the usage string. 92 93Completion function 94------------------- 95 96The completion function pointer has to be of type 97int (*complete)(int argc, char *const argv[], char last_char, 98 int maxv, char *cmdv[]); 99 100argc: Number of arguments including the command. 101 102argv: Arguments. 103 104last_char: The last character in the command line buffer. 105 106maxv: Maximum number of possible completions that may be returned by 107 the function. 108 109cmdv: Used to return possible values for the last argument. The last 110 possible completion must be followed by NULL. 111 112The function returns the number of possible completions (without the terminating 113NULL value). 114 115Behind the scene 116---------------- 117 118The structure created is named with a special prefix and placed by 119the linker in a special section using the linker lists mechanism 120(see include/linker_lists.h) 121 122This makes it possible for the final link to extract all commands 123compiled into any object code and construct a static array so the 124command array can be iterated over using the linker lists macros. 125 126The linker lists feature ensures that the linker does not discard 127these symbols when linking full U-Boot even though they are not 128referenced in the source code as such. 129 130If a new board is defined do not forget to define the command section 131by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these 1323 lines: 133 134 .u_boot_list : { 135 KEEP(*(SORT(.u_boot_list*))); 136 } 137