doc/uefi/uefi.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. Copyright (c) 2018 Heinrich Schuchardt
   3
   4 UEFI on U-Boot
   5 ==============
   6
   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.
  12
  13 Development target
  14 ------------------
  15
  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
  20 reference.
  21
  22 A full blown UEFI implementation would contradict the U-Boot design principle
  23 "keep it small".
  24
  25 Building U-Boot for UEFI
  26 ------------------------
  27
  28 The UEFI standard supports only little-endian systems. The UEFI support can be
  29 activated for ARM and x86 by specifying::
  30
  31     CONFIG_CMD_BOOTEFI=y
  32     CONFIG_EFI_LOADER=y
  33
  34 in the .config file.
  35
  36 Support for attaching virtual block devices, e.g. iSCSI drives connected by the
  37 loaded UEFI application [4], requires::
  38
  39     CONFIG_BLK=y
  40     CONFIG_PARTITIONS=y
  41
  42 Executing a UEFI binary
  43 ~~~~~~~~~~~~~~~~~~~~~~~
  44
  45 The bootefi command is used to start UEFI applications or to install UEFI
  46 drivers. 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
  53 Below 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
  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.
  65
  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
  68 arguments.
  69
  70 Launching a UEFI binary from a FIT image
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  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::
  75
  76     CONFIG_BOOTM_EFI=y
  77
  78 A sample configuration is provided as file doc/uImage.FIT/uefi.its.
  79
  80 Below you find the output of an example session starting GRUB::
  81
  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
  95          Hash algo:    sha256
  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) ...
 100     Welcome to GRUB!
 101
 102 See doc/uImage.FIT/howto.txt for an introduction to FIT images.
 103
 104 Configuring UEFI secure boot
 105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 106
 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::
 110
 111     CONFIG_UEFI_SECURE_BOOT=y
 112
 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
 115
 116 * PK - Platform Key
 117 * KEK - Key Exchange Keys
 118 * db - white list database
 119 * dbx - black list database
 120
 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
 125 environment.):
 126
 127 Install the required tools on your host
 128
 129 * openssl
 130 * efitools
 131 * sbsigntool
 132
 133 Create signing keys and the key database on your host:
 134
 135 The platform key
 136
 137 .. code-block:: bash
 138
 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 \
 142             PK.crt PK.esl;
 143     sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth
 144
 145 The key exchange keys
 146
 147 .. code-block:: bash
 148
 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 \
 152             KEK.crt KEK.esl
 153     sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth
 154
 155 The whitelist database
 156
 157 .. code-block:: bash
 158
 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 \
 162             db.crt db.esl
 163     $ sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth
 164
 165 Copy the \*.auth files to media, say mmc, that is accessible from U-Boot.
 166
 167 Sign an image with one of the keys in "db" on your host
 168
 169 .. code-block:: bash
 170
 171     sbsign --key db.key --cert db.crt helloworld.efi
 172
 173 Now in U-Boot install the keys on your board::
 174
 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
 181
 182 Set up boot parameters on your board::
 183
 184     efidebug boot add 1 HELLO mmc 0:1 /helloworld.efi.signed ""
 185
 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,
 188 on the sandbox
 189
 190 .. code-block:: bash
 191
 192     cd <U-Boot source directory>
 193     pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox
 194
 195 UEFI binaries may be signed by Microsoft using the following certificates:
 196
 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.
 203
 204 Using OP-TEE for EFI variables
 205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 206
 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.
 211
 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.
 218
 219 [1] https://optee.readthedocs.io/ - OP-TEE documentation
 220
 221 Executing the boot manager
 222 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 223
 224 The UEFI specification foresees to define boot entries and boot sequence via
 225 UEFI variables. Booting according to these variables is possible via::
 226
 227     bootefi bootmgr [fdt address]
 228
 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.
 231
 232 Executing the built in hello world application
 233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 234
 235 A hello world UEFI application can be built with::
 236
 237     CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
 238
 239 It can be embedded into the U-Boot binary with::
 240
 241     CONFIG_CMD_BOOTEFI_HELLO=y
 242
 243 The bootefi command is used to start the embedded hello world application::
 244
 245     bootefi hello [fdt address]
 246
 247 Below you find the output of an example session::
 248
 249     => bootefi hello ${fdtcontroladdr}
 250     ## Starting EFI application at 01000000 ...
 251     WARNING: using memory device/image path, this may confuse some payloads!
 252     Hello, world!
 253     Running on UEFI 2.7
 254     Have SMBIOS table
 255     Have device tree
 256     Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
 257     ## Application terminated, r = 0
 258
 259 The environment variable fdtcontroladdr points to U-Boot's internal device tree
 260 (if available).
 261
 262 Executing the built-in self-test
 263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 264
 265 An UEFI self-test suite can be embedded in U-Boot by building with::
 266
 267     CONFIG_CMD_BOOTEFI_SELFTEST=y
 268
 269 For testing the UEFI implementation the bootefi command can be used to start the
 270 self-test::
 271
 272     bootefi selftest [fdt address]
 273
 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.
 277
 278 Below you can find the output of an example session::
 279
 280     => setenv efi_selftest simple network protocol
 281     => bootefi selftest
 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'
 287     DHCP Discover
 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
 294     Summary: 0 failures
 295     Preparing for reset. Press any key.
 296
 297 The UEFI life cycle
 298 -------------------
 299
 300 After the U-Boot platform has been initialized the UEFI API provides two kinds
 301 of services:
 302
 303 * boot services
 304 * runtime services
 305
 306 The API can be extended by loading UEFI drivers which come in two variants:
 307
 308 * boot drivers
 309 * runtime drivers
 310
 311 UEFI drivers are installed with U-Boot's bootefi command. With the same command
 312 UEFI applications can be executed.
 313
 314 Loaded images of UEFI drivers stay in memory after returning to U-Boot while
 315 loaded images of applications are removed from memory.
 316
 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
 319 ExitBootServices
 320
 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
 325
 326 So this is a point of no return. Afterwards the UEFI application can only return
 327 to U-Boot by rebooting.
 328
 329 The UEFI object model
 330 ---------------------
 331
 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
 334 handles.
 335
 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.
 339
 340 Handles are created by the InstallProtocolInterface or the
 341 InstallMultipleProtocolinterfaces service if NULL is passed as handle.
 342
 343 Handles are deleted when the last protocol has been removed with the
 344 UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service.
 345
 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
 348 tree.
 349
 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).
 352
 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.
 355
 356 The UEFI events
 357 ---------------
 358
 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:
 362
 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
 371
 372 Events can be created with the CreateEvent service and deleted with CloseEvent
 373 service.
 374
 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.
 377
 378 The UEFI driver model
 379 ---------------------
 380
 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.
 384
 385 The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This
 386 protocol has has three functions:
 387
 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
 392
 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.
 397
 398 A driver can be detached from a device using the DisconnectController service.
 399
 400 U-Boot devices mapped as UEFI devices
 401 -------------------------------------
 402
 403 Some of the U-Boot devices are mapped as UEFI devices
 404
 405 * block IO devices
 406 * console
 407 * graphical output
 408 * network adapter
 409
 410 As of U-Boot 2018.03 the logic for doing this is hard coded.
 411
 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.
 417
 418 UEFI devices mapped as U-Boot devices
 419 -------------------------------------
 420
 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.
 425
 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.
 428
 429 In U-Boot 2018.03 this has only been implemented for block IO devices.
 430
 431 UEFI uclass
 432 ~~~~~~~~~~~
 433
 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.
 437
 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::
 441
 442     /* Identify as UEFI driver */
 443     U_BOOT_DRIVER(efi_block) = {
 444         .name  = "EFI block driver",
 445         .id    = UCLASS_EFI,
 446         .ops   = &driver_ops,
 447     };
 448
 449 The available operations are defined via the structure struct efi_driver_ops::
 450
 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);
 455     };
 456
 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
 460 checking the GUID.
 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.)
 464
 465 UEFI block IO driver
 466 ~~~~~~~~~~~~~~~~~~~~
 467
 468 The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL.
 469
 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].
 474
 475 This driver is only available if U-Boot is configured with::
 476
 477     CONFIG_BLK=y
 478     CONFIG_PARTITIONS=y
 479
 480 Miscellaneous
 481 -------------
 482
 483 Load file 2 protocol
 484 ~~~~~~~~~~~~~~~~~~~~
 485
 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::
 488
 489     EFI_LOAD_FILE2_INITRD=y
 490     EFI_INITRD_FILESPEC=interface dev:part path_to_initrd
 491
 492 Links
 493 -----
 494
 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
 500 * [4] :doc:`iscsi`
 501 * [5] :doc:`../driver-model/index`