doc/README.commands

   1 Command definition
   2 ------------------
   3
   4 Commands are added to U-Boot by creating a new command structure.
   5 This is done by first including command.h, then using the U_BOOT_CMD() or the
   6 U_BOOT_CMD_COMPLETE macro to fill in a cmd_tbl_t struct.
   7
   8 U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help")
   9 U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp)
  10
  11 name:           The name of the command. THIS IS NOT a string.
  12
  13 maxargs:        The maximum number of arguments this function takes including
  14                 the command itself.
  15
  16 repeatable:     Either 0 or 1 to indicate if autorepeat is allowed.
  17
  18 command:        Pointer to the command function. This is the function that is
  19                 called when the command is issued.
  20
  21 usage:          Short description. This is a string.
  22
  23 help:           Long description. This is a string. The long description is
  24                 only available if CONFIG_SYS_LONGHELP is defined.
  25
  26 comp:           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
  31 Command function
  32 ----------------
  33
  34 The commmand function pointer has to be of type
  35 int (*cmd)(struct cmd_tbl_s *cmdtp, int flag, int argc, const char *argv[]);
  36
  37 cmdtp:          Table entry describing the command (see above).
  38
  39 flag:           A bitmap which may contain the following bit:
  40                 CMD_FLAG_REPEAT - The last command is repeated.
  41                 CMD_FLAG_BOOTD  - The command is called by the bootd command.
  42                 CMD_FLAG_ENV    - The command is called by the run command.
  43
  44 argc:           Number of arguments including the command.
  45
  46 argv:           Arguments.
  47
  48 Allowable return value are:
  49
  50 CMD_SUCCESS     The command was successfully executed.
  51
  52 CMD_FAILURE     The command failed.
  53
  54 CMD_RET_USAGE   The command was called with invalid parameters. This value
  55                 leads to the display of the usage string.
  56
  57 Completion function
  58 -------------------
  59
  60 The completion function pointer has to be of type
  61 int (*complete)(int argc, char *const argv[], char last_char,
  62                 int maxv, char *cmdv[]);
  63
  64 argc:           Number of arguments including the command.
  65
  66 argv:           Arguments.
  67
  68 last_char:      The last character in the command line buffer.
  69
  70 maxv:           Maximum number of possible completions that may be returned by
  71                 the function.
  72
  73 cmdv:           Used to return possible values for the last argument. The last
  74                 possible completion must be followed by NULL.
  75
  76 The function returns the number of possible completions (without the terminating
  77 NULL value).
  78
  79 Behind the scene
  80 ----------------
  81
  82 The structure created is named with a special prefix and placed by
  83 the linker in a special section using the linker lists mechanism
  84 (see include/linker_lists.h)
  85
  86 This makes it possible for the final link to extract all commands
  87 compiled into any object code and construct a static array so the
  88 command array can be iterated over using the linker lists macros.
  89
  90 The linker lists feature ensures that the linker does not discard
  91 these symbols when linking full U-Boot even though they are not
  92 referenced in the source code as such.
  93
  94 If a new board is defined do not forget to define the command section
  95 by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
  96 3 lines:
  97
  98         .u_boot_list : {
  99                 KEEP(*(SORT(.u_boot_list*)));
 100         }