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