1 <!-- 2 SPDX-License-Identifier: GPL-2.0+ 3 4 Copyright (c) 2018 Heinrich Schuchardt 5 --> 6 7 # UEFI on U-Boot 8 9 The Unified Extensible Firmware Interface Specification (UEFI) [1] has become 10 the default for booting on AArch64 and x86 systems. It provides a stable API for 11 the interaction of drivers and applications with the firmware. The API comprises 12 access to block storage, network, and console to name a few. The Linux kernel 13 and boot loaders like GRUB or the FreeBSD loader can be executed. 14 15 ## Building for UEFI 16 17 The UEFI standard supports only little endian systems. The UEFI support can be 18 activated for ARM and x86 by specifying 19 20 CONFIG_CMD_BOOTEFI=y 21 CONFIG_EFI_LOADER=y 22 23 in the .config file. 24 25 Support for attaching virtual block devices, e.g. iSCSI drives connected by the 26 loaded UEFI application [3], requires 27 28 CONFIG_BLK=y 29 CONFIG_PARTITIONS=y 30 31 ### Executing a UEFI binary 32 33 The bootefi command is used to start UEFI applications or to install UEFI 34 drivers. 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 41 Below 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 50 The environment variable 'bootargs' is passed as load options in the UEFI system 51 table. The Linux kernel EFI stub uses the load options as command line 52 arguments. 53 54 ### Executing the boot manager 55 56 The UEFI specfication foresees to define boot entries and boot sequence via UEFI 57 variables. Booting according to these variables is possible via 58 59 bootefi bootmgr [fdt address] 60 61 As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at 62 runtime. 63 64 ### Executing the built in hello world application 65 66 A hello world UEFI application can be built with 67 68 CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y 69 70 It can be embedded into the U-Boot binary with 71 72 CONFIG_CMD_BOOTEFI_HELLO=y 73 74 The bootefi command is used to start the embedded hello world application. 75 76 bootefi hello [fdt address] 77 78 Below 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 90 The environment variable fdtcontroladdr points to U-Boot's internal device tree 91 (if available). 92 93 ### Executing the built-in selftest 94 95 An UEFI selftest suite can be embedded in U-Boot by building with 96 97 CONFIG_CMD_BOOTEFI_SELFTEST=y 98 99 For testing the UEFI implementation the bootefi command can be used to start the 100 selftest. 101 102 bootefi selftest [fdt address] 103 104 The environment variable 'efi_selftest' can be used to select a single test. If 105 it is not provided all tests are executed except those marked as 'on request'. 106 If the environment variable is set to 'list' a list of all tests is shown. 107 108 Below 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 129 After the U-Boot platform has been initialized the UEFI API provides two kinds 130 of services 131 132 * boot services and 133 * runtime services. 134 135 The API can be extended by loading UEFI drivers which come in two variants 136 137 * boot drivers and 138 * runtime drivers. 139 140 UEFI drivers are installed with U-Boot's bootefi command. With the same command 141 UEFI applications can be executed. 142 143 Loaded images of UEFI drivers stay in memory after returning to U-Boot while 144 loaded images of applications are removed from memory. 145 146 An UEFI application (e.g. an operating system) that wants to take full control 147 of the system calls ExitBootServices. After a UEFI application calls 148 ExitBootServices 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 155 So this is a point of no return. Afterwards the UEFI application can only return 156 to U-Boot by rebooting. 157 158 ## The UEFI object model 159 160 UEFI offers a flexible and expandable object model. The objects in the UEFI API 161 are devices, drivers, and loaded images. These objects are referenced by 162 handles. 163 164 The interfaces implemented by the objects are referred to as protocols. These 165 are identified by GUIDs. They can be installed and uninstalled by calling the 166 appropriate boot services. 167 168 Handles are created by the InstallProtocolInterface or the 169 InstallMultipleProtocolinterfaces service if NULL is passed as handle. 170 171 Handles are deleted when the last protocol has been removed with the 172 UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. 173 174 Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation 175 of device nodes. By their device paths all devices of a system are arranged in a 176 tree. 177 178 Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect 179 a driver to devices (which are referenced as controllers in this context). 180 181 Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta 182 information about the image and a pointer to the unload callback function. 183 184 ## The UEFI events 185 186 In the UEFI terminology an event is a data object referencing a notification 187 function which is queued for calling when the event is signaled. The following 188 types 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 199 Events can be created with the CreateEvent service and deleted with CloseEvent 200 service. 201 202 Events can be assigned to an event group. If any of the events in a group is 203 signaled, all other events in the group are also set to the signaled state. 204 205 ## The UEFI driver model 206 207 A driver is specific for a single protocol installed on a device. To install a 208 driver on a device the ConnectController service is called. In this context 209 controller refers to the device for which the driver is installed. 210 211 The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This 212 protocol 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 219 The driver may create child controllers (child devices). E.g. a driver for block 220 IO devices will create the device handles for the partitions. The child 221 controllers will open the supported protocol with the attribute 222 EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 223 224 A driver can be detached from a device using the DisconnectController service. 225 226 ## U-Boot devices mapped as UEFI devices 227 228 Some of the U-Boot devices are mapped as UEFI devices 229 230 * block IO devices 231 * console 232 * graphical output 233 * network adapter 234 235 As of U-Boot 2018.03 the logic for doing this is hard coded. 236 237 The development target is to integrate the setup of these UEFI devices with the 238 U-Boot driver model. So when a U-Boot device is discovered a handle should be 239 created and the device path protocol and the relevant IO protocol should be 240 installed. The UEFI driver then would be attached by calling ConnectController. 241 When a U-Boot device is removed DisconnectController should be called. 242 243 ## UEFI devices mapped as U-Boot devices 244 245 UEFI drivers binaries and applications may create new (virtual) devices, install 246 a protocol and call the ConnectController service. Now the matching UEFI driver 247 is determined by iterating over the implementations of the 248 EFI_DRIVER_BINDING_PROTOCOL. 249 250 It is the task of the UEFI driver to create a corresponding U-Boot device and to 251 proxy calls for this U-Boot device to the controller. 252 253 In U-Boot 2018.03 this has only been implemented for block IO devices. 254 255 ### UEFI uclass 256 257 An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that 258 takes care of initializing the UEFI drivers and providing the 259 EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. 260 261 A linker created list is used to keep track of the UEFI drivers. To create an 262 entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying 263 UCLASS_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 272 The 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 280 When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the 281 uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. 282 In the start() function the bind() function of the UEFI driver is called after 283 checking the GUID. 284 The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child 285 controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 286 this is not yet completely implemented.) 287 288 ### UEFI block IO driver 289 290 The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. 291 292 When connected it creates a new U-Boot block IO device with interface type 293 IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the 294 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the 295 software iPXE to boot from iSCSI network drives [3]. 296 297 This 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
