xref: /openbmc/u-boot/doc/README.commands (revision 2d1d65838eacd314b989701bd2f9e2b657bbf62b)

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.

U_BOOT_CMD(name,maxargs,repeatable,command,"usage","help")

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


**** Behind the scene ******

The structure created is named with a special prefix (__u_boot_cmd_)
and placed by the linker in a special section.

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.

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).

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
3 lines:

	__u_boot_cmd_start = .;
	.u_boot_cmd : { *(.u_boot_cmd) }
	__u_boot_cmd_end = .;