diff options
author | Tom Rini <trini@konsulko.com> | 2020-12-20 22:55:59 +0300 |
---|---|---|
committer | Tom Rini <trini@konsulko.com> | 2020-12-20 22:55:59 +0300 |
commit | 46a4d752034646b7c10178988c08b85c08b44bf6 (patch) | |
tree | a54859b7ccfca56d96df727b7801763d3ac9047f /doc | |
parent | 549e7cb70843d4729524cbb03fe3a4b5dab42d94 (diff) | |
parent | 77504ee6764994f18039f7f634a419a1606296b0 (diff) | |
download | u-boot-46a4d752034646b7c10178988c08b85c08b44bf6.tar.xz |
Merge tag 'efi-2021-01-rc4' of https://gitlab.denx.de/u-boot/custodians/u-boot-efi
Pull request for UEFI sub-system for efi-2021-01-rc4
* Provide a tool to create a file with UEFI variables to preseed UEFI
variable store.
* Make size of UEFI variable store configurable.
* Add man pages for commands 'bootefi' and 'button'.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/usage/bootefi.rst | 135 | ||||
-rw-r--r-- | doc/usage/button.rst | 64 | ||||
-rw-r--r-- | doc/usage/index.rst | 2 |
3 files changed, 201 insertions, 0 deletions
diff --git a/doc/usage/bootefi.rst b/doc/usage/bootefi.rst new file mode 100644 index 0000000000..282f22aac9 --- /dev/null +++ b/doc/usage/bootefi.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de> + +bootefi command +=============== + +Synopsis +-------- + +:: + + bootefi [image_addr] [fdt_addr] + bootefi bootmgr [fdt_addr] + bootefi hello [fdt_addr] + bootefi selftest [fdt_addr] + +Description +----------- + +The *bootefi* command is used to launch a UEFI binary which can be either of + +* UEFI application +* UEFI boot services driver +* UEFI run-time services driver + +An operating system requires a hardware description which can either be +presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree +The load address of the device-tree may be provided as parameter *fdt\_addr*. If +this address is not specified, the bootefi command will try to fall back in +sequence to: + +* the device-tree specified by environment variable *fdt\_addr* +* the device-tree specified by environment variable *fdtcontroladdr* + +The load address of the binary is specified by parameter *image_address*. A +command sequence to run a UEFI application might look like + +:: + + load mmc 0:2 $fdt_addr_r dtb + load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi + bootefi $kernel_addr_r $fdt_addr_r + +The last file loaded defines the image file path in the loaded image protocol. +Hence the executable should always be loaded last. + +The value of the environment variable *bootargs* is converted from UTF-8 to +UTF-16 and passed as load options in the loaded image protocol to the UEFI +binary. + +Note + UEFI binaries that are contained in FIT images are launched via the + *bootm* command. + +UEFI boot manager +''''''''''''''''' + +The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command. +Here boot options are defined by UEFI variables with a name consisting of the +letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or +*BootA03E*. The boot variable defines a label, the device path of the binary to +execute as well as the load options passed in the loaded image protocol. + +If the UEFI variable *BootNext* is defined, it specifies the number of the boot +option to execute next. If no binary can be loaded via *BootNext* the variable +*BootOrder* specifies in which sequence boot options shalled be tried. + +The values of these variables can be managed using the U-Boot command +*efidebug*. + +UEFI hello world application +'''''''''''''''''''''''''''' + +U-Boot can be compiled with a hello world application that can be launched using +the *bootefi hello* sub-command. A session might look like + +:: + + => setenv bootargs 'Greetings to the world' + => bootefi hello + Booting /MemoryMapped(0x0,0x10001000,0x1000) + Hello, world! + Running on UEFI 2.8 + Have SMBIOS table + Have device tree + Load options: Greetings to the world + +UEFI selftest +''''''''''''' + +U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using +the *bootefi selftest* sub-command. + +Which unit test is executed is controlled by the environment variable +*efi\_selftest*. If this variable is not set, all unit tests that are not marked +as 'on request' are executed. + +To show a list of the available unit tests the value *list* can be used + +:: + + => setenv efi_selftest list + => bootefi selftest + + Available tests: + 'block image transfer' - on request + 'block device' + 'configuration tables' + ... + +A single test is selected for execution by setting the *efi\_selftest* +environment variable to match one of the listed identifiers + +:: + + => setenv efi_selftest 'block image transfer' + => bootefi selftest + +Some of the tests execute the ExitBootServices() UEFI boot service and will not +return to the command line but require a board reset. + +Configuration +------------- + +To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y. +The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y. +The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y. + +See also +-------- + +* *bootm* for launching UEFI binaries packed in FIT images +* *booti*, *bootm*, *bootz* for launching a Linux kernel without using the + UEFI sub-system +* *efidebug* for setting UEFI boot variables diff --git a/doc/usage/button.rst b/doc/usage/button.rst new file mode 100644 index 0000000000..ea41762757 --- /dev/null +++ b/doc/usage/button.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +button command +============== + +Synopsis +-------- + +:: + + button list + button <name> + +Description +----------- + +The button command is used to retrieve the status of a button. To show the +status of a button with name 'button1' you would issue the command + +:: + + button button1 + +The status of the button is both written to the console as *ON* or *OFF* and +set in the return value variable *$?* as 0 (true) or 1 (false). To retrieve +the status of a button with name *button1* and to write it to environment +variable *status1* you would execute the commands + +:: + + button button1 + setenv status1 $? + +A list of all available buttons and their status can be displayed using + +:: + + button list + +If a button device has not been probed yet, its status will be shown as +*<inactive>* in the list. + +Configuration +------------- + +To use the button command you must specify CONFIG_CMD_BUTTON=y and enable a +button driver. The available buttons are defined in the device-tree. + +Return value +------------ + +The variable *$?* takes the following values + ++---+-----------------------------+ +| 0 | ON, the button is pressed | ++---+-----------------------------+ +| 1 | OFF, the button is released | ++---+-----------------------------+ +| 0 | button list was shown | ++---+-----------------------------+ +| 1 | button not found | ++---+-----------------------------+ +| 1 | invalid arguments | ++---+-----------------------------+ diff --git a/doc/usage/index.rst b/doc/usage/index.rst index d0f5a9f26e..fbb2c0481c 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -11,5 +11,7 @@ Shell commands .. toctree:: :maxdepth: 1 + bootefi bootmenu + button pstore |