1 .. SPDX-License-Identifier: GPL-2.0+
2 .. Copyright (c) 2018 Heinrich Schuchardt
7 The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
8 the default for booting on AArch64 and x86 systems. It provides a stable API for
9 the interaction of drivers and applications with the firmware. The API comprises
10 access to block storage, network, and console to name a few. The Linux kernel
11 and boot loaders like GRUB or the FreeBSD loader can be executed.
16 The implementation of UEFI in U-Boot strives to reach the requirements described
17 in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0"
18 [2]. The "Server Base Boot Requirements System Software on ARM Platforms" [3]
19 describes a superset of the EBBR specification and may be used as further
22 A full blown UEFI implementation would contradict the U-Boot design principle
25 Building U-Boot for UEFI
26 ------------------------
28 The UEFI standard supports only little-endian systems. The UEFI support can be
29 activated for ARM and x86 by specifying::
36 Support for attaching virtual block devices, e.g. iSCSI drives connected by the
37 loaded UEFI application [4], requires::
42 Executing a UEFI binary
43 ~~~~~~~~~~~~~~~~~~~~~~~
45 The bootefi command is used to start UEFI applications or to install UEFI
46 drivers. It takes two parameters::
48 bootefi <image address> [fdt address]
50 * image address - the memory address of the UEFI binary
51 * fdt address - the memory address of the flattened device tree
53 Below you find the output of an example session starting GRUB::
55 => load mmc 0:2 ${fdt_addr_r} boot/dtb
56 29830 bytes read in 14 ms (2 MiB/s)
57 => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
58 reading efi/debian/grubaa64.efi
59 120832 bytes read in 7 ms (16.5 MiB/s)
60 => bootefi ${kernel_addr_r} ${fdt_addr_r}
62 The bootefi command uses the device, the file name, and the file size
63 (environment variable 'filesize') of the most recently loaded file when setting
64 up the binary for execution. So the UEFI binary should be loaded last.
66 The environment variable 'bootargs' is passed as load options in the UEFI system
67 table. The Linux kernel EFI stub uses the load options as command line
70 Launching a UEFI binary from a FIT image
71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73 A signed FIT image can be used to securely boot a UEFI image via the
74 bootm command. This feature is available if U-Boot is configured with::
78 A sample configuration is provided as file doc/uImage.FIT/uefi.its.
80 Below you find the output of an example session starting GRUB::
82 => load mmc 0:1 ${kernel_addr_r} image.fit
83 4620426 bytes read in 83 ms (53.1 MiB/s)
84 => bootm ${kernel_addr_r}#config-grub-nofdt
85 ## Loading kernel from FIT Image at 40400000 ...
86 Using 'config-grub-nofdt' configuration
87 Verifying Hash Integrity ... sha256,rsa2048:dev+ OK
88 Trying 'efi-grub' kernel subimage
89 Description: GRUB EFI Firmware
90 Created: 2019-11-20 8:18:16 UTC
91 Type: Kernel Image (no loading done)
92 Compression: uncompressed
93 Data Start: 0x404000d0
94 Data Size: 450560 Bytes = 440 KiB
96 Hash value: 4dbee00021112df618f58b3f7cf5e1595533d543094064b9ce991e8b054a9eec
97 Verifying Hash Integrity ... sha256+ OK
98 XIP Kernel Image (no loading done)
99 ## Transferring control to EFI (at address 404000d0) ...
102 See doc/uImage.FIT/howto.txt for an introduction to FIT images.
104 Configuring UEFI secure boot
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107 The UEFI specification[1] defines a secure way of executing UEFI images
108 by verifying a signature (or message digest) of image with certificates.
109 This feature on U-Boot is enabled with::
111 CONFIG_UEFI_SECURE_BOOT=y
113 To make the boot sequence safe, you need to establish a chain of trust;
114 In UEFI secure boot the chain trust is defined by the following UEFI variables
117 * KEK - Key Exchange Keys
118 * db - white list database
119 * dbx - black list database
121 An in depth description of UEFI secure boot is beyond the scope of this
122 document. Please, refer to the UEFI specification and available online
123 documentation. Here is a simple example that you can follow for your initial
124 attempt (Please note that the actual steps will depend on your system and
127 Install the required tools on your host
133 Create signing keys and the key database on your host:
139 openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_PK/ \
140 -keyout PK.key -out PK.crt -nodes -days 365
141 cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \
143 sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth
145 The key exchange keys
149 openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_KEK/ \
150 -keyout KEK.key -out KEK.crt -nodes -days 365
151 cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \
153 sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth
155 The whitelist database
159 $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \
160 -keyout db.key -out db.crt -nodes -days 365
161 $ cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \
163 $ sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth
165 Copy the \*.auth files to media, say mmc, that is accessible from U-Boot.
167 Sign an image with one of the keys in "db" on your host
171 sbsign --key db.key --cert db.crt helloworld.efi
173 Now in U-Boot install the keys on your board::
175 fatload mmc 0:1 <tmpaddr> PK.auth
176 setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize PK
177 fatload mmc 0:1 <tmpaddr> KEK.auth
178 setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize KEK
179 fatload mmc 0:1 <tmpaddr> db.auth
180 setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize db
182 Set up boot parameters on your board::
184 efidebug boot add 1 HELLO mmc 0:1 /helloworld.efi.signed ""
186 Now your board can run the signed image via the boot manager (see below).
187 You can also try this sequence by running Pytest, test_efi_secboot,
192 cd <U-Boot source directory>
193 pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox
195 UEFI binaries may be signed by Microsoft using the following certificates:
197 * KEK: Microsoft Corporation KEK CA 2011
198 http://go.microsoft.com/fwlink/?LinkId=321185.
199 * db: Microsoft Windows Production PCA 2011
200 http://go.microsoft.com/fwlink/p/?linkid=321192.
201 * db: Microsoft Corporation UEFI CA 2011
202 http://go.microsoft.com/fwlink/p/?linkid=321194.
204 Using OP-TEE for EFI variables
205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207 Instead of implementing UEFI variable services inside U-Boot they can
208 also be provided in the secure world by a module for OP-TEE[1]. The
209 interface between U-Boot and OP-TEE for variable services is enabled by
210 CONFIG_EFI_MM_COMM_TEE=y.
212 Tianocore EDK II's standalone management mode driver for variables can
213 be linked to OP-TEE for this purpose. This module uses the Replay
214 Protected Memory Block (RPMB) of an eMMC device for persisting
215 non-volatile variables. When calling the variable services via the
216 OP-TEE API U-Boot's OP-TEE supplicant relays calls to the RPMB driver
217 which has to be enabled via CONFIG_SUPPORT_EMMC_RPMB=y.
219 [1] https://optee.readthedocs.io/ - OP-TEE documentation
221 Executing the boot manager
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~
224 The UEFI specification foresees to define boot entries and boot sequence via
225 UEFI variables. Booting according to these variables is possible via::
227 bootefi bootmgr [fdt address]
229 As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot
230 command 'efidebug' can be used to set the variables.
232 Executing the built in hello world application
233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235 A hello world UEFI application can be built with::
237 CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
239 It can be embedded into the U-Boot binary with::
241 CONFIG_CMD_BOOTEFI_HELLO=y
243 The bootefi command is used to start the embedded hello world application::
245 bootefi hello [fdt address]
247 Below you find the output of an example session::
249 => bootefi hello ${fdtcontroladdr}
250 ## Starting EFI application at 01000000 ...
251 WARNING: using memory device/image path, this may confuse some payloads!
256 Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
257 ## Application terminated, r = 0
259 The environment variable fdtcontroladdr points to U-Boot's internal device tree
262 Executing the built-in self-test
263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265 An UEFI self-test suite can be embedded in U-Boot by building with::
267 CONFIG_CMD_BOOTEFI_SELFTEST=y
269 For testing the UEFI implementation the bootefi command can be used to start the
272 bootefi selftest [fdt address]
274 The environment variable 'efi_selftest' can be used to select a single test. If
275 it is not provided all tests are executed except those marked as 'on request'.
276 If the environment variable is set to 'list' a list of all tests is shown.
278 Below you can find the output of an example session::
280 => setenv efi_selftest simple network protocol
282 Testing EFI API implementation
283 Selected test: 'simple network protocol'
284 Setting up 'simple network protocol'
285 Setting up 'simple network protocol' succeeded
286 Executing 'simple network protocol'
288 DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02)
289 as broadcast message.
290 Executing 'simple network protocol' succeeded
291 Tearing down 'simple network protocol'
292 Tearing down 'simple network protocol' succeeded
293 Boot services terminated
295 Preparing for reset. Press any key.
300 After the U-Boot platform has been initialized the UEFI API provides two kinds
306 The API can be extended by loading UEFI drivers which come in two variants:
311 UEFI drivers are installed with U-Boot's bootefi command. With the same command
312 UEFI applications can be executed.
314 Loaded images of UEFI drivers stay in memory after returning to U-Boot while
315 loaded images of applications are removed from memory.
317 An UEFI application (e.g. an operating system) that wants to take full control
318 of the system calls ExitBootServices. After a UEFI application calls
321 * boot services are not available anymore
322 * timer events are stopped
323 * the memory used by U-Boot except for runtime services is released
324 * the memory used by boot time drivers is released
326 So this is a point of no return. Afterwards the UEFI application can only return
327 to U-Boot by rebooting.
329 The UEFI object model
330 ---------------------
332 UEFI offers a flexible and expandable object model. The objects in the UEFI API
333 are devices, drivers, and loaded images. These objects are referenced by
336 The interfaces implemented by the objects are referred to as protocols. These
337 are identified by GUIDs. They can be installed and uninstalled by calling the
338 appropriate boot services.
340 Handles are created by the InstallProtocolInterface or the
341 InstallMultipleProtocolinterfaces service if NULL is passed as handle.
343 Handles are deleted when the last protocol has been removed with the
344 UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service.
346 Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation
347 of device nodes. By their device paths all devices of a system are arranged in a
350 Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect
351 a driver to devices (which are referenced as controllers in this context).
353 Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta
354 information about the image and a pointer to the unload callback function.
359 In the UEFI terminology an event is a data object referencing a notification
360 function which is queued for calling when the event is signaled. The following
361 types of events exist:
363 * periodic and single shot timer events
364 * exit boot services events, triggered by calling the ExitBootServices() service
365 * virtual address change events
366 * memory map change events
367 * read to boot events
368 * reset system events
369 * system table events
370 * events that are only triggered programmatically
372 Events can be created with the CreateEvent service and deleted with CloseEvent
375 Events can be assigned to an event group. If any of the events in a group is
376 signaled, all other events in the group are also set to the signaled state.
378 The UEFI driver model
379 ---------------------
381 A driver is specific for a single protocol installed on a device. To install a
382 driver on a device the ConnectController service is called. In this context
383 controller refers to the device for which the driver is installed.
385 The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This
386 protocol has has three functions:
388 * supported - determines if the driver is compatible with the device
389 * start - installs the driver by opening the relevant protocol with
390 attribute EFI_OPEN_PROTOCOL_BY_DRIVER
391 * stop - uninstalls the driver
393 The driver may create child controllers (child devices). E.g. a driver for block
394 IO devices will create the device handles for the partitions. The child
395 controllers will open the supported protocol with the attribute
396 EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
398 A driver can be detached from a device using the DisconnectController service.
400 U-Boot devices mapped as UEFI devices
401 -------------------------------------
403 Some of the U-Boot devices are mapped as UEFI devices
410 As of U-Boot 2018.03 the logic for doing this is hard coded.
412 The development target is to integrate the setup of these UEFI devices with the
413 U-Boot driver model [5]. So when a U-Boot device is discovered a handle should
414 be created and the device path protocol and the relevant IO protocol should be
415 installed. The UEFI driver then would be attached by calling ConnectController.
416 When a U-Boot device is removed DisconnectController should be called.
418 UEFI devices mapped as U-Boot devices
419 -------------------------------------
421 UEFI drivers binaries and applications may create new (virtual) devices, install
422 a protocol and call the ConnectController service. Now the matching UEFI driver
423 is determined by iterating over the implementations of the
424 EFI_DRIVER_BINDING_PROTOCOL.
426 It is the task of the UEFI driver to create a corresponding U-Boot device and to
427 proxy calls for this U-Boot device to the controller.
429 In U-Boot 2018.03 this has only been implemented for block IO devices.
434 An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
435 takes care of initializing the UEFI drivers and providing the
436 EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers.
438 A linker created list is used to keep track of the UEFI drivers. To create an
439 entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying
440 UCLASS_EFI as the ID of its uclass, e.g::
442 /* Identify as UEFI driver */
443 U_BOOT_DRIVER(efi_block) = {
444 .name = "EFI block driver",
449 The available operations are defined via the structure struct efi_driver_ops::
451 struct efi_driver_ops {
452 const efi_guid_t *protocol;
453 const efi_guid_t *child_protocol;
454 int (*bind)(efi_handle_t handle, void *interface);
457 When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the
458 uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver.
459 In the start() function the bind() function of the UEFI driver is called after
461 The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child
462 controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03
463 this is not yet completely implemented.)
468 The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL.
470 When connected it creates a new U-Boot block IO device with interface type
471 IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the
472 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the
473 software iPXE to boot from iSCSI network drives [4].
475 This driver is only available if U-Boot is configured with::
486 The load file 2 protocol can be used by the Linux kernel to load the initial
487 RAM disk. U-Boot can be configured to provide an implementation with::
489 EFI_LOAD_FILE2_INITRD=y
490 EFI_INITRD_FILESPEC=interface dev:part path_to_initrd
495 * [1] http://uefi.org/specifications - UEFI specifications
496 * [2] https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf -
497 Embedded Base Boot Requirements (EBBR) Specification - Release v1.0
498 * [3] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 -
499 Server Base Boot Requirements System Software on ARM Platforms - Version 1.1
501 * [5] :doc:`../driver-model/index`