1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de>
3
4bootefi command
5===============
6
7Synopsis
8--------
9
10::
11
12    bootefi [image_addr] [fdt_addr]
13    bootefi bootmgr [fdt_addr]
14    bootefi hello [fdt_addr]
15    bootefi selftest [fdt_addr]
16
17Description
18-----------
19
20The *bootefi* command is used to launch a UEFI binary which can be either of
21
22* UEFI application
23* UEFI boot services driver
24* UEFI run-time services driver
25
26An operating system requires a hardware description which can either be
27presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree
28The load address of the device-tree may be provided as parameter *fdt\_addr*. If
29this address is not specified, the bootefi command will try to fall back in
30sequence to:
31
32* the device-tree specified by environment variable *fdt\_addr*
33* the device-tree specified by environment variable *fdtcontroladdr*
34
35The load address of the binary is specified by parameter *image_address*. A
36command sequence to run a UEFI application might look like
37
38::
39
40    load mmc 0:2 $fdt_addr_r dtb
41    load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi
42    bootefi $kernel_addr_r $fdt_addr_r
43
44The last file loaded defines the image file path in the loaded image protocol.
45Hence the executable should always be loaded last.
46
47The value of the environment variable *bootargs* is converted from UTF-8 to
48UTF-16 and passed as load options in the loaded image protocol to the UEFI
49binary.
50
51Note
52    UEFI binaries that are contained in FIT images are launched via the
53    *bootm* command.
54
55UEFI boot manager
56'''''''''''''''''
57
58The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command.
59Here boot options are defined by UEFI variables with a name consisting of the
60letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or
61*BootA03E*. The boot variable defines a label, the device path of the binary to
62execute as well as the load options passed in the loaded image protocol.
63
64If the UEFI variable *BootNext* is defined, it specifies the number of the boot
65option to execute next. If no binary can be loaded via *BootNext* the variable
66*BootOrder* specifies in which sequence boot options shalled be tried.
67
68The values of these variables can be managed using the U-Boot command
69*efidebug*.
70
71UEFI hello world application
72''''''''''''''''''''''''''''
73
74U-Boot can be compiled with a hello world application that can be launched using
75the *bootefi hello* sub-command. A session might look like
76
77::
78
79    => setenv bootargs 'Greetings to the world'
80    => bootefi hello
81    Booting /MemoryMapped(0x0,0x10001000,0x1000)
82    Hello, world!
83    Running on UEFI 2.8
84    Have SMBIOS table
85    Have device tree
86    Load options: Greetings to the world
87
88UEFI selftest
89'''''''''''''
90
91U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using
92the *bootefi selftest* sub-command.
93
94Which unit test is executed is controlled by the environment variable
95*efi\_selftest*. If this variable is not set, all unit tests that are not marked
96as 'on request' are executed.
97
98To show a list of the available unit tests the value *list* can be used
99
100::
101
102    => setenv efi_selftest list
103    => bootefi selftest
104
105    Available tests:
106    'block image transfer' - on request
107    'block device'
108    'configuration tables'
109    ...
110
111A single test is selected for execution by setting the *efi\_selftest*
112environment variable to match one of the listed identifiers
113
114::
115
116    => setenv efi_selftest 'block image transfer'
117    => bootefi selftest
118
119Some of the tests execute the ExitBootServices() UEFI boot service and will not
120return to the command line but require a board reset.
121
122Configuration
123-------------
124
125To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y.
126The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y.
127The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y.
128
129See also
130--------
131
132* *bootm* for launching UEFI binaries packed in FIT images
133* *booti*, *bootm*, *bootz* for launching a Linux kernel without using the
134  UEFI sub-system
135* *efidebug* for setting UEFI boot variables
136