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>[:<image_size>] [<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 UEFI binary loaded defines the image file path in the loaded image
45protocol.
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
51image_addr
52    Address of the UEFI binary.
53
54fdt_addr
55    Address of the device-tree or '-'. If no address is specifiy, the
56    environment variable $fdt_addr is used as first fallback, the address of
57    U-Boot's internal device-tree $fdtcontroladdr as second fallback.
58    When using ACPI no device-tree shall be specified.
59
60image_size
61    Size of the UEFI binary file. This argument is only needed if *image_addr*
62    does not match the address of the last loaded UEFI binary. In this case
63    a memory device path will be used as image file path in the loaded image
64    protocol.
65
66Note
67    UEFI binaries that are contained in FIT images are launched via the
68    *bootm* command.
69
70UEFI boot manager
71'''''''''''''''''
72
73The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command.
74Here boot options are defined by UEFI variables with a name consisting of the
75letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or
76*BootA03E*. The boot variable defines a label, the device path of the binary to
77execute as well as the load options passed in the loaded image protocol.
78
79If the UEFI variable *BootNext* is defined, it specifies the number of the boot
80option to execute next. If no binary can be loaded via *BootNext* the variable
81*BootOrder* specifies in which sequence boot options shalled be tried.
82
83The values of these variables can be managed using the U-Boot command
84*efidebug*.
85
86UEFI hello world application
87''''''''''''''''''''''''''''
88
89U-Boot can be compiled with a hello world application that can be launched using
90the *bootefi hello* sub-command. A session might look like
91
92::
93
94    => setenv bootargs 'Greetings to the world'
95    => bootefi hello
96    Booting /MemoryMapped(0x0,0x10001000,0x1000)
97    Hello, world!
98    Running on UEFI 2.8
99    Have SMBIOS table
100    Have device tree
101    Load options: Greetings to the world
102
103UEFI selftest
104'''''''''''''
105
106U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using
107the *bootefi selftest* sub-command.
108
109Which unit test is executed is controlled by the environment variable
110*efi\_selftest*. If this variable is not set, all unit tests that are not marked
111as 'on request' are executed.
112
113To show a list of the available unit tests the value *list* can be used
114
115::
116
117    => setenv efi_selftest list
118    => bootefi selftest
119
120    Available tests:
121    'block image transfer' - on request
122    'block device'
123    'configuration tables'
124    ...
125
126A single test is selected for execution by setting the *efi\_selftest*
127environment variable to match one of the listed identifiers
128
129::
130
131    => setenv efi_selftest 'block image transfer'
132    => bootefi selftest
133
134Some of the tests execute the ExitBootServices() UEFI boot service and will not
135return to the command line but require a board reset.
136
137Configuration
138-------------
139
140To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y.
141The *bootefi bootmgr* sub-command requries CMD\_BOOTEFI\_BOOTMGR=y.
142The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y.
143The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y.
144
145See also
146--------
147
148* *bootm* for launching UEFI binaries packed in FIT images
149* :doc:`booti<booti>`, *bootm*, *bootz* for launching a Linux kernel without
150  using the UEFI sub-system
151* *efidebug* for setting UEFI boot variables and boot options
152