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