1<!-- 2SPDX-License-Identifier: GPL-2.0+ 3 4Copyright (c) 2018 Heinrich Schuchardt 5--> 6 7# UEFI on U-Boot 8 9The Unified Extensible Firmware Interface Specification (UEFI) [1] has become 10the default for booting on AArch64 and x86 systems. It provides a stable API for 11the interaction of drivers and applications with the firmware. The API comprises 12access to block storage, network, and console to name a few. The Linux kernel 13and boot loaders like GRUB or the FreeBSD loader can be executed. 14 15## Building for UEFI 16 17The UEFI standard supports only little endian systems. The UEFI support can be 18activated for ARM and x86 by specifying 19 20 CONFIG_CMD_BOOTEFI=y 21 CONFIG_EFI_LOADER=y 22 23in the .config file. 24 25Support for attaching virtual block devices, e.g. iSCSI drives connected by the 26loaded UEFI application [3], requires 27 28 CONFIG_BLK=y 29 CONFIG_PARTITIONS=y 30 31### Executing a UEFI binary 32 33The bootefi command is used to start UEFI applications or to install UEFI 34drivers. It takes two parameters 35 36 bootefi <image address> [fdt address] 37 38* image address - the memory address of the UEFI binary 39* fdt address - the memory address of the flattened device tree 40 41Below you find the output of an example session starting GRUB. 42 43 => load mmc 0:2 ${fdt_addr_r} boot/dtb 44 29830 bytes read in 14 ms (2 MiB/s) 45 => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi 46 reading efi/debian/grubaa64.efi 47 120832 bytes read in 7 ms (16.5 MiB/s) 48 => bootefi ${kernel_addr_r} ${fdt_addr_r} 49 50The environment variable 'bootargs' is passed as load options in the UEFI system 51table. The Linux kernel EFI stub uses the load options as command line 52arguments. 53 54### Executing the boot manager 55 56The UEFI specfication foresees to define boot entries and boot sequence via UEFI 57variables. Booting according to these variables is possible via 58 59 bootefi bootmgr [fdt address] 60 61As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at 62runtime. 63 64### Executing the built in hello world application 65 66A hello world UEFI application can be built with 67 68 CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y 69 70It can be embedded into the U-Boot binary with 71 72 CONFIG_CMD_BOOTEFI_HELLO=y 73 74The bootefi command is used to start the embedded hello world application. 75 76 bootefi hello [fdt address] 77 78Below you find the output of an example session. 79 80 => bootefi hello ${fdtcontroladdr} 81 ## Starting EFI application at 01000000 ... 82 WARNING: using memory device/image path, this may confuse some payloads! 83 Hello, world! 84 Running on UEFI 2.7 85 Have SMBIOS table 86 Have device tree 87 Load options: root=/dev/sdb3 init=/sbin/init rootwait ro 88 ## Application terminated, r = 0 89 90The environment variable fdtcontroladdr points to U-Boot's internal device tree 91(if available). 92 93### Executing the built-in selftest 94 95An UEFI selftest suite can be embedded in U-Boot by building with 96 97 CONFIG_CMD_BOOTEFI_SELFTEST=y 98 99For testing the UEFI implementation the bootefi command can be used to start the 100selftest. 101 102 bootefi selftest [fdt address] 103 104The environment variable 'efi_selftest' can be used to select a single test. If 105it is not provided all tests are executed except those marked as 'on request'. 106If the environment variable is set to 'list' a list of all tests is shown. 107 108Below you can find the output of an example session. 109 110 => setenv efi_selftest simple network protocol 111 => bootefi selftest 112 Testing EFI API implementation 113 Selected test: 'simple network protocol' 114 Setting up 'simple network protocol' 115 Setting up 'simple network protocol' succeeded 116 Executing 'simple network protocol' 117 DHCP Discover 118 DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02) 119 as broadcast message. 120 Executing 'simple network protocol' succeeded 121 Tearing down 'simple network protocol' 122 Tearing down 'simple network protocol' succeeded 123 Boot services terminated 124 Summary: 0 failures 125 Preparing for reset. Press any key. 126 127## The UEFI life cycle 128 129After the U-Boot platform has been initialized the UEFI API provides two kinds 130of services 131 132* boot services and 133* runtime services. 134 135The API can be extended by loading UEFI drivers which come in two variants 136 137* boot drivers and 138* runtime drivers. 139 140UEFI drivers are installed with U-Boot's bootefi command. With the same command 141UEFI applications can be executed. 142 143Loaded images of UEFI drivers stay in memory after returning to U-Boot while 144loaded images of applications are removed from memory. 145 146An UEFI application (e.g. an operating system) that wants to take full control 147of the system calls ExitBootServices. After a UEFI application calls 148ExitBootServices 149 150* boot services are not available anymore 151* timer events are stopped 152* the memory used by U-Boot except for runtime services is released 153* the memory used by boot time drivers is released 154 155So this is a point of no return. Afterwards the UEFI application can only return 156to U-Boot by rebooting. 157 158## The UEFI object model 159 160UEFI offers a flexible and expandable object model. The objects in the UEFI API 161are devices, drivers, and loaded images. These objects are referenced by 162handles. 163 164The interfaces implemented by the objects are referred to as protocols. These 165are identified by GUIDs. They can be installed and uninstalled by calling the 166appropriate boot services. 167 168Handles are created by the InstallProtocolInterface or the 169InstallMultipleProtocolinterfaces service if NULL is passed as handle. 170 171Handles are deleted when the last protocol has been removed with the 172UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. 173 174Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation 175of device nodes. By their device paths all devices of a system are arranged in a 176tree. 177 178Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect 179a driver to devices (which are referenced as controllers in this context). 180 181Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta 182information about the image and a pointer to the unload callback function. 183 184## The UEFI events 185 186In the UEFI terminology an event is a data object referencing a notification 187function which is queued for calling when the event is signaled. The following 188types of events exist: 189 190* periodic and single shot timer events 191* exit boot services events, triggered by calling the ExitBootServices() service 192* virtual address change events 193* memory map change events 194* read to boot events 195* reset system events 196* system table events 197* events that are only triggered programmatically 198 199Events can be created with the CreateEvent service and deleted with CloseEvent 200service. 201 202Events can be assigned to an event group. If any of the events in a group is 203signaled, all other events in the group are also set to the signaled state. 204 205## The UEFI driver model 206 207A driver is specific for a single protocol installed on a device. To install a 208driver on a device the ConnectController service is called. In this context 209controller refers to the device for which the driver is installed. 210 211The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This 212protocol has has three functions: 213 214* supported - determines if the driver is compatible with the device 215* start - installs the driver by opening the relevant protocol with 216 attribute EFI_OPEN_PROTOCOL_BY_DRIVER 217* stop - uninstalls the driver 218 219The driver may create child controllers (child devices). E.g. a driver for block 220IO devices will create the device handles for the partitions. The child 221controllers will open the supported protocol with the attribute 222EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 223 224A driver can be detached from a device using the DisconnectController service. 225 226## U-Boot devices mapped as UEFI devices 227 228Some of the U-Boot devices are mapped as UEFI devices 229 230* block IO devices 231* console 232* graphical output 233* network adapter 234 235As of U-Boot 2018.03 the logic for doing this is hard coded. 236 237The development target is to integrate the setup of these UEFI devices with the 238U-Boot driver model. So when a U-Boot device is discovered a handle should be 239created and the device path protocol and the relevant IO protocol should be 240installed. The UEFI driver then would be attached by calling ConnectController. 241When a U-Boot device is removed DisconnectController should be called. 242 243## UEFI devices mapped as U-Boot devices 244 245UEFI drivers binaries and applications may create new (virtual) devices, install 246a protocol and call the ConnectController service. Now the matching UEFI driver 247is determined by iterating over the implementations of the 248EFI_DRIVER_BINDING_PROTOCOL. 249 250It is the task of the UEFI driver to create a corresponding U-Boot device and to 251proxy calls for this U-Boot device to the controller. 252 253In U-Boot 2018.03 this has only been implemented for block IO devices. 254 255### UEFI uclass 256 257An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that 258takes care of initializing the UEFI drivers and providing the 259EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. 260 261A linker created list is used to keep track of the UEFI drivers. To create an 262entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying 263UCLASS_EFI as the ID of its uclass, e.g. 264 265 /* Identify as UEFI driver */ 266 U_BOOT_DRIVER(efi_block) = { 267 .name = "EFI block driver", 268 .id = UCLASS_EFI, 269 .ops = &driver_ops, 270 }; 271 272The available operations are defined via the structure struct efi_driver_ops. 273 274 struct efi_driver_ops { 275 const efi_guid_t *protocol; 276 const efi_guid_t *child_protocol; 277 int (*bind)(efi_handle_t handle, void *interface); 278 }; 279 280When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the 281uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. 282In the start() function the bind() function of the UEFI driver is called after 283checking the GUID. 284The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child 285controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 286this is not yet completely implemented.) 287 288### UEFI block IO driver 289 290The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. 291 292When connected it creates a new U-Boot block IO device with interface type 293IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the 294EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the 295software iPXE to boot from iSCSI network drives [3]. 296 297This driver is only available if U-Boot is configured with 298 299 CONFIG_BLK=y 300 CONFIG_PARTITIONS=y 301 302## TODOs as of U-Boot 2018.07 303 304* unimplemented or incompletely implemented boot services 305 * Exit - call unload function, unload applications only 306 * ProtocolRegisterNotify 307 * UnloadImage 308 309* unimplemented or incompletely implemented runtime services 310 * SetVariable() ignores attribute EFI_VARIABLE_APPEND_WRITE 311 * GetNextVariableName is not implemented 312 * QueryVariableInfo is not implemented 313 314* unimplemented events 315 * EVT_RUNTIME 316 * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE 317 * event groups 318 319* data model 320 * manage events in a linked list 321 * manage configuration tables in a linked list 322 323* UEFI drivers 324 * support DisconnectController for UEFI block devices. 325 326* support for CONFIG_EFI_LOADER in the sandbox (CONFIG_SANDBOX=y) 327 328* UEFI variables 329 * persistence 330 * runtime support 331 332* support bootefi booting ARMv7 in non-secure mode (CONFIG_ARMV7_NONSEC=y) 333 334## Links 335 336* [1](http://uefi.org/specifications) 337 http://uefi.org/specifications - UEFI specifications 338* [2](./driver-model/README.txt) doc/driver-model/README.txt - Driver model 339* [3](./README.iscsi) doc/README.iscsi - iSCSI booting with U-Boot and iPXE 340