1.. SPDX-License-Identifier: GPL-2.0+ 2.. Copyright (c) 2018 Heinrich Schuchardt 3 4UEFI on U-Boot 5============== 6 7The Unified Extensible Firmware Interface Specification (UEFI) [1] has become 8the default for booting on AArch64 and x86 systems. It provides a stable API for 9the interaction of drivers and applications with the firmware. The API comprises 10access to block storage, network, and console to name a few. The Linux kernel 11and boot loaders like GRUB or the FreeBSD loader can be executed. 12 13Development target 14------------------ 15 16The implementation of UEFI in U-Boot strives to reach the requirements described 17in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0" 18[2]. The "Server Base Boot Requirements System Software on ARM Platforms" [3] 19describes a superset of the EBBR specification and may be used as further 20reference. 21 22A full blown UEFI implementation would contradict the U-Boot design principle 23"keep it small". 24 25Building U-Boot for UEFI 26------------------------ 27 28The UEFI standard supports only little-endian systems. The UEFI support can be 29activated for ARM and x86 by specifying:: 30 31 CONFIG_CMD_BOOTEFI=y 32 CONFIG_EFI_LOADER=y 33 34in the .config file. 35 36Support for attaching virtual block devices, e.g. iSCSI drives connected by the 37loaded UEFI application [4], requires:: 38 39 CONFIG_BLK=y 40 CONFIG_PARTITIONS=y 41 42Executing a UEFI binary 43~~~~~~~~~~~~~~~~~~~~~~~ 44 45The bootefi command is used to start UEFI applications or to install UEFI 46drivers. It takes two parameters:: 47 48 bootefi <image address> [fdt address] 49 50* image address - the memory address of the UEFI binary 51* fdt address - the memory address of the flattened device tree 52 53Below you find the output of an example session starting GRUB:: 54 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} 61 62When booting from a memory location it is unknown from which file it was loaded. 63Therefore the bootefi command uses the device path of the block device partition 64or the network adapter and the file name of the most recently loaded PE-COFF 65file when setting up the loaded image protocol. 66 67Launching a UEFI binary from a FIT image 68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 69 70A signed FIT image can be used to securely boot a UEFI image via the 71bootm command. This feature is available if U-Boot is configured with:: 72 73 CONFIG_BOOTM_EFI=y 74 75A sample configuration is provided as file doc/uImage.FIT/uefi.its. 76 77Below you find the output of an example session starting GRUB:: 78 79 => load mmc 0:1 ${kernel_addr_r} image.fit 80 4620426 bytes read in 83 ms (53.1 MiB/s) 81 => bootm ${kernel_addr_r}#config-grub-nofdt 82 ## Loading kernel from FIT Image at 40400000 ... 83 Using 'config-grub-nofdt' configuration 84 Verifying Hash Integrity ... sha256,rsa2048:dev+ OK 85 Trying 'efi-grub' kernel subimage 86 Description: GRUB EFI Firmware 87 Created: 2019-11-20 8:18:16 UTC 88 Type: Kernel Image (no loading done) 89 Compression: uncompressed 90 Data Start: 0x404000d0 91 Data Size: 450560 Bytes = 440 KiB 92 Hash algo: sha256 93 Hash value: 4dbee00021112df618f58b3f7cf5e1595533d543094064b9ce991e8b054a9eec 94 Verifying Hash Integrity ... sha256+ OK 95 XIP Kernel Image (no loading done) 96 ## Transferring control to EFI (at address 404000d0) ... 97 Welcome to GRUB! 98 99See doc/uImage.FIT/howto.txt for an introduction to FIT images. 100 101Configuring UEFI secure boot 102~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 103 104The UEFI specification[1] defines a secure way of executing UEFI images 105by verifying a signature (or message digest) of image with certificates. 106This feature on U-Boot is enabled with:: 107 108 CONFIG_UEFI_SECURE_BOOT=y 109 110To make the boot sequence safe, you need to establish a chain of trust; 111In UEFI secure boot the chain trust is defined by the following UEFI variables 112 113* PK - Platform Key 114* KEK - Key Exchange Keys 115* db - white list database 116* dbx - black list database 117 118An in depth description of UEFI secure boot is beyond the scope of this 119document. Please, refer to the UEFI specification and available online 120documentation. Here is a simple example that you can follow for your initial 121attempt (Please note that the actual steps will depend on your system and 122environment.): 123 124Install the required tools on your host 125 126* openssl 127* efitools 128* sbsigntool 129 130Create signing keys and the key database on your host: 131 132The platform key 133 134.. code-block:: bash 135 136 openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_PK/ \ 137 -keyout PK.key -out PK.crt -nodes -days 365 138 cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ 139 PK.crt PK.esl; 140 sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth 141 142The key exchange keys 143 144.. code-block:: bash 145 146 openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_KEK/ \ 147 -keyout KEK.key -out KEK.crt -nodes -days 365 148 cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ 149 KEK.crt KEK.esl 150 sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth 151 152The whitelist database 153 154.. code-block:: bash 155 156 openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \ 157 -keyout db.key -out db.crt -nodes -days 365 158 cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ 159 db.crt db.esl 160 sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth 161 162Copy the \*.auth files to media, say mmc, that is accessible from U-Boot. 163 164Sign an image with one of the keys in "db" on your host 165 166.. code-block:: bash 167 168 sbsign --key db.key --cert db.crt helloworld.efi 169 170Now in U-Boot install the keys on your board:: 171 172 fatload mmc 0:1 <tmpaddr> PK.auth 173 setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize PK 174 fatload mmc 0:1 <tmpaddr> KEK.auth 175 setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize KEK 176 fatload mmc 0:1 <tmpaddr> db.auth 177 setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize db 178 179Set up boot parameters on your board:: 180 181 efidebug boot add 1 HELLO mmc 0:1 /helloworld.efi.signed "" 182 183Now your board can run the signed image via the boot manager (see below). 184You can also try this sequence by running Pytest, test_efi_secboot, 185on the sandbox 186 187.. code-block:: bash 188 189 cd <U-Boot source directory> 190 pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox 191 192UEFI binaries may be signed by Microsoft using the following certificates: 193 194* KEK: Microsoft Corporation KEK CA 2011 195 http://go.microsoft.com/fwlink/?LinkId=321185. 196* db: Microsoft Windows Production PCA 2011 197 http://go.microsoft.com/fwlink/p/?linkid=321192. 198* db: Microsoft Corporation UEFI CA 2011 199 http://go.microsoft.com/fwlink/p/?linkid=321194. 200 201Using OP-TEE for EFI variables 202~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 203 204Instead of implementing UEFI variable services inside U-Boot they can 205also be provided in the secure world by a module for OP-TEE[1]. The 206interface between U-Boot and OP-TEE for variable services is enabled by 207CONFIG_EFI_MM_COMM_TEE=y. 208 209Tianocore EDK II's standalone management mode driver for variables can 210be linked to OP-TEE for this purpose. This module uses the Replay 211Protected Memory Block (RPMB) of an eMMC device for persisting 212non-volatile variables. When calling the variable services via the 213OP-TEE API U-Boot's OP-TEE supplicant relays calls to the RPMB driver 214which has to be enabled via CONFIG_SUPPORT_EMMC_RPMB=y. 215 216[1] https://optee.readthedocs.io/ - OP-TEE documentation 217 218Executing the boot manager 219~~~~~~~~~~~~~~~~~~~~~~~~~~ 220 221The UEFI specification foresees to define boot entries and boot sequence via 222UEFI variables. Booting according to these variables is possible via:: 223 224 bootefi bootmgr [fdt address] 225 226As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot 227command 'efidebug' can be used to set the variables. 228 229Executing the built in hello world application 230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 231 232A hello world UEFI application can be built with:: 233 234 CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y 235 236It can be embedded into the U-Boot binary with:: 237 238 CONFIG_CMD_BOOTEFI_HELLO=y 239 240The bootefi command is used to start the embedded hello world application:: 241 242 bootefi hello [fdt address] 243 244Below you find the output of an example session:: 245 246 => bootefi hello ${fdtcontroladdr} 247 ## Starting EFI application at 01000000 ... 248 WARNING: using memory device/image path, this may confuse some payloads! 249 Hello, world! 250 Running on UEFI 2.7 251 Have SMBIOS table 252 Have device tree 253 Load options: root=/dev/sdb3 init=/sbin/init rootwait ro 254 ## Application terminated, r = 0 255 256The environment variable fdtcontroladdr points to U-Boot's internal device tree 257(if available). 258 259Executing the built-in self-test 260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 261 262An UEFI self-test suite can be embedded in U-Boot by building with:: 263 264 CONFIG_CMD_BOOTEFI_SELFTEST=y 265 266For testing the UEFI implementation the bootefi command can be used to start the 267self-test:: 268 269 bootefi selftest [fdt address] 270 271The environment variable 'efi_selftest' can be used to select a single test. If 272it is not provided all tests are executed except those marked as 'on request'. 273If the environment variable is set to 'list' a list of all tests is shown. 274 275Below you can find the output of an example session:: 276 277 => setenv efi_selftest simple network protocol 278 => bootefi selftest 279 Testing EFI API implementation 280 Selected test: 'simple network protocol' 281 Setting up 'simple network protocol' 282 Setting up 'simple network protocol' succeeded 283 Executing 'simple network protocol' 284 DHCP Discover 285 DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02) 286 as broadcast message. 287 Executing 'simple network protocol' succeeded 288 Tearing down 'simple network protocol' 289 Tearing down 'simple network protocol' succeeded 290 Boot services terminated 291 Summary: 0 failures 292 Preparing for reset. Press any key. 293 294The UEFI life cycle 295------------------- 296 297After the U-Boot platform has been initialized the UEFI API provides two kinds 298of services: 299 300* boot services 301* runtime services 302 303The API can be extended by loading UEFI drivers which come in two variants: 304 305* boot drivers 306* runtime drivers 307 308UEFI drivers are installed with U-Boot's bootefi command. With the same command 309UEFI applications can be executed. 310 311Loaded images of UEFI drivers stay in memory after returning to U-Boot while 312loaded images of applications are removed from memory. 313 314An UEFI application (e.g. an operating system) that wants to take full control 315of the system calls ExitBootServices. After a UEFI application calls 316ExitBootServices 317 318* boot services are not available anymore 319* timer events are stopped 320* the memory used by U-Boot except for runtime services is released 321* the memory used by boot time drivers is released 322 323So this is a point of no return. Afterwards the UEFI application can only return 324to U-Boot by rebooting. 325 326The UEFI object model 327--------------------- 328 329UEFI offers a flexible and expandable object model. The objects in the UEFI API 330are devices, drivers, and loaded images. These objects are referenced by 331handles. 332 333The interfaces implemented by the objects are referred to as protocols. These 334are identified by GUIDs. They can be installed and uninstalled by calling the 335appropriate boot services. 336 337Handles are created by the InstallProtocolInterface or the 338InstallMultipleProtocolinterfaces service if NULL is passed as handle. 339 340Handles are deleted when the last protocol has been removed with the 341UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. 342 343Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation 344of device nodes. By their device paths all devices of a system are arranged in a 345tree. 346 347Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect 348a driver to devices (which are referenced as controllers in this context). 349 350Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta 351information about the image and a pointer to the unload callback function. 352 353The UEFI events 354--------------- 355 356In the UEFI terminology an event is a data object referencing a notification 357function which is queued for calling when the event is signaled. The following 358types of events exist: 359 360* periodic and single shot timer events 361* exit boot services events, triggered by calling the ExitBootServices() service 362* virtual address change events 363* memory map change events 364* read to boot events 365* reset system events 366* system table events 367* events that are only triggered programmatically 368 369Events can be created with the CreateEvent service and deleted with CloseEvent 370service. 371 372Events can be assigned to an event group. If any of the events in a group is 373signaled, all other events in the group are also set to the signaled state. 374 375The UEFI driver model 376--------------------- 377 378A driver is specific for a single protocol installed on a device. To install a 379driver on a device the ConnectController service is called. In this context 380controller refers to the device for which the driver is installed. 381 382The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This 383protocol has has three functions: 384 385* supported - determines if the driver is compatible with the device 386* start - installs the driver by opening the relevant protocol with 387 attribute EFI_OPEN_PROTOCOL_BY_DRIVER 388* stop - uninstalls the driver 389 390The driver may create child controllers (child devices). E.g. a driver for block 391IO devices will create the device handles for the partitions. The child 392controllers will open the supported protocol with the attribute 393EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 394 395A driver can be detached from a device using the DisconnectController service. 396 397U-Boot devices mapped as UEFI devices 398------------------------------------- 399 400Some of the U-Boot devices are mapped as UEFI devices 401 402* block IO devices 403* console 404* graphical output 405* network adapter 406 407As of U-Boot 2018.03 the logic for doing this is hard coded. 408 409The development target is to integrate the setup of these UEFI devices with the 410U-Boot driver model [5]. So when a U-Boot device is discovered a handle should 411be created and the device path protocol and the relevant IO protocol should be 412installed. The UEFI driver then would be attached by calling ConnectController. 413When a U-Boot device is removed DisconnectController should be called. 414 415UEFI devices mapped as U-Boot devices 416------------------------------------- 417 418UEFI drivers binaries and applications may create new (virtual) devices, install 419a protocol and call the ConnectController service. Now the matching UEFI driver 420is determined by iterating over the implementations of the 421EFI_DRIVER_BINDING_PROTOCOL. 422 423It is the task of the UEFI driver to create a corresponding U-Boot device and to 424proxy calls for this U-Boot device to the controller. 425 426In U-Boot 2018.03 this has only been implemented for block IO devices. 427 428UEFI uclass 429~~~~~~~~~~~ 430 431An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that 432takes care of initializing the UEFI drivers and providing the 433EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. 434 435A linker created list is used to keep track of the UEFI drivers. To create an 436entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying 437UCLASS_EFI as the ID of its uclass, e.g:: 438 439 /* Identify as UEFI driver */ 440 U_BOOT_DRIVER(efi_block) = { 441 .name = "EFI block driver", 442 .id = UCLASS_EFI, 443 .ops = &driver_ops, 444 }; 445 446The available operations are defined via the structure struct efi_driver_ops:: 447 448 struct efi_driver_ops { 449 const efi_guid_t *protocol; 450 const efi_guid_t *child_protocol; 451 int (*bind)(efi_handle_t handle, void *interface); 452 }; 453 454When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the 455uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. 456In the start() function the bind() function of the UEFI driver is called after 457checking the GUID. 458The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child 459controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 460this is not yet completely implemented.) 461 462UEFI block IO driver 463~~~~~~~~~~~~~~~~~~~~ 464 465The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. 466 467When connected it creates a new U-Boot block IO device with interface type 468IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the 469EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the 470software iPXE to boot from iSCSI network drives [4]. 471 472This driver is only available if U-Boot is configured with:: 473 474 CONFIG_BLK=y 475 CONFIG_PARTITIONS=y 476 477Miscellaneous 478------------- 479 480Load file 2 protocol 481~~~~~~~~~~~~~~~~~~~~ 482 483The load file 2 protocol can be used by the Linux kernel to load the initial 484RAM disk. U-Boot can be configured to provide an implementation with:: 485 486 EFI_LOAD_FILE2_INITRD=y 487 EFI_INITRD_FILESPEC=interface dev:part path_to_initrd 488 489Links 490----- 491 492* [1] http://uefi.org/specifications - UEFI specifications 493* [2] https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf - 494 Embedded Base Boot Requirements (EBBR) Specification - Release v1.0 495* [3] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 - 496 Server Base Boot Requirements System Software on ARM Platforms - Version 1.1 497* [4] :doc:`iscsi` 498* [5] :doc:`../driver-model/index` 499