Blame view
doc/README.commands
4.15 KB
3d9640f55 doc: expand READM... |
1 2 |
Command definition ------------------ |
0d4983930 Patch by Kenneth ... |
3 4 |
Commands are added to U-Boot by creating a new command structure. |
3d9640f55 doc: expand READM... |
5 6 |
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. |
0d4983930 Patch by Kenneth ... |
7 |
|
3d9640f55 doc: expand READM... |
8 9 |
U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help") U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) |
0d4983930 Patch by Kenneth ... |
10 |
|
3d9640f55 doc: expand READM... |
11 |
name: The name of the command. THIS IS NOT a string. |
0d4983930 Patch by Kenneth ... |
12 |
|
3d9640f55 doc: expand READM... |
13 14 |
maxargs: The maximum number of arguments this function takes including the command itself. |
0d4983930 Patch by Kenneth ... |
15 |
|
3d9640f55 doc: expand READM... |
16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
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. |
ca80b561e doc: README.comma... |
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
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; } |
3d9640f55 doc: expand READM... |
65 66 |
Command function ---------------- |
f3ccba3e4 doc: README.comma... |
67 |
The command function pointer has to be of type |
3d9640f55 doc: expand READM... |
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
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 ---------------- |
0d4983930 Patch by Kenneth ... |
114 |
|
ef123c525 Refactor linker-g... |
115 116 117 |
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) |
0d4983930 Patch by Kenneth ... |
118 119 120 |
This makes it possible for the final link to extract all commands compiled into any object code and construct a static array so the |
ef123c525 Refactor linker-g... |
121 |
command array can be iterated over using the linker lists macros. |
0d4983930 Patch by Kenneth ... |
122 |
|
ef123c525 Refactor linker-g... |
123 124 125 |
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. |
2d1d65838 README.commands: ... |
126 |
|
0d4983930 Patch by Kenneth ... |
127 |
If a new board is defined do not forget to define the command section |
4379ac614 kbuild: rename TO... |
128 |
by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these |
0d4983930 Patch by Kenneth ... |
129 |
3 lines: |
6c7c946ca common: Convert t... |
130 |
.u_boot_list : { |
ef123c525 Refactor linker-g... |
131 |
KEEP(*(SORT(.u_boot_list*))); |
6c7c946ca common: Convert t... |
132 |
} |