u-boot/doc/README.efi

4 # SPDX-License-Identifier:	GPL-2.0+
9   1  U-Boot on EFI
15   1.6  EFI Application
19   1.10 32/64-bit
23   2  EFI on U-Boot
29 U-Boot on EFI
31 This document provides information about U-Boot running on top of EFI, either
32 as an application or just as a means of getting U-Boot onto a new platform.
36 -------------------
39 - You have EFI running on a board but U-Boot does not natively support it
40 fully yet. You can boot into U-Boot from EFI and use that until U-Boot is
43 - You need to use an EFI implementation (e.g. UEFI) because your vendor
46 - You plan to use coreboot to boot into U-Boot but coreboot support does
47 not currently exist for your platform. In the meantime you can use U-Boot
48 on EFI and then move to U-Boot on coreboot when ready
50 - You use EFI but want to experiment with a simpler alternative like U-Boot
54 ------
59 U-Boot supports running as an EFI application for 32-bit EFI only. This is
63 More usefully, U-Boot supports building itself as a payload for either 32-bit
64 or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once
65 started, U-Boot changes to 32-bit mode (currently) and takes over the
70 ------------------
72 for that board. It will be either 32-bit or 64-bit. Alternatively, you can
75 To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI
76 and CONFIG_EFI_APP. The efi-x86 config (efi-x86_defconfig) is set up for this.
77 Just build U-Boot as normal, e.g.
79    make efi-x86_defconfig
82 To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust an
83 existing config (like qemu-x86_defconfig) to enable CONFIG_EFI, CONFIG_EFI_STUB
85 boolean Kconfig options. Then build U-Boot as normal, e.g.
87    make qemu-x86_defconfig
92    u-boot-app.efi      - U-Boot EFI application
93    u-boot-payload.efi  - U-Boot EFI payload application
97 -------------
103    cp /path/to/u-boot*.efi /tmp/efi
104    qemu-system-x86_64 -bios bios.bin -hda fat:/tmp/efi/
106 Add -nographic if you want to use the terminal for output. Once it starts
107 type 'fs0:u-boot-payload.efi' to run the payload or 'fs0:u-boot-app.efi' to
108 run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a
111 To try it on real hardware, put u-boot-app.efi on a suitable boot medium,
114    fs0:u-boot-payload.efi
116 (or fs0:u-boot-app.efi for the application)
118 This will start the payload, copy U-Boot into RAM and start U-Boot. Note
119 that EFI does not support booting a 64-bit application from a 32-bit
126 Here follow a few implementation notes for those who want to fiddle with
129 The application and payload approaches sound similar but are in fact
132 EFI Application
133 ---------------
134 For the application the whole of U-Boot is built as a shared library. The
136 functions with efi_init(), sets up U-Boot global_data, allocates memory for
137 U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f()
140 Since U-Boot limits its memory access to the allocated regions very little
151 consoles will be active. Even though U-Boot does the same thing normally,
152 These are features of EFI, not U-Boot.
154 Very little code is involved in implementing the EFI application feature.
155 U-Boot is highly portable. Most of the difficulty is in modifying the
157 little x86-specific code involved - you can find most of it in
164 -----------
166 U-Boot exactly as normal for your target board, then adding the entire
167 image (including device tree) into a small EFI stub application responsible
168 for booting it. The stub application is built as a normal EFI application
171 The stub application is implemented in lib/efi/efi_stub.c. The efi_main()
172 function is called by EFI. It is responsible for copying U-Boot from its
174 U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc.
176 The stub application is architecture-dependent. At present it has some
177 x86-specific code and a comment at the top of efi_stub.c describes this.
179 While the stub application does allocate some memory from EFI this is not
180 used by U-Boot (the payload). In fact when U-Boot starts it has all of the
185 ------
186 The payload can pass information to U-Boot in the form of EFI tables. At
189 display this list. U-Boot uses the list to work out where to relocate
192 Although U-Boot can use any memory it likes, EFI marks some memory as used
193 by 'run-time services', code that hangs around while U-Boot is running and
196 fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It
201 ----------
202 U-Boot drivers typically don't use interrupts. Since EFI enables interrupts
203 it is possible that an interrupt will fire that U-Boot cannot handle. This
204 seems to cause problems. For this reason the U-Boot payload runs with
207 32/64-bit
208 ---------
209 While the EFI application can in principle be built as either 32- or 64-bit,
210 only 32-bit is currently supported. This means that the application can only
211 be used with 32-bit EFI.
213 The payload stub can be build as either 32- or 64-bits. Only a small amount
214 of code is built this way (see the extra- line in lib/efi/Makefile).
215 Everything else is built as a normal U-Boot, so is always 32-bit on x86 at
219 -----------
222 - Add a generic x86 EFI payload configuration. At present you need to modify
223 an existing one, but mostly the low-level x86 code is disabled when booting
227 - Add ARM support
229 - Add 64-bit application support
231 - Figure out how to solve the interrupt problem
233 - Add more drivers to the application side (e.g. video, block devices, USB,
237 - Avoid turning off boot services in the stub. Instead allow U-Boot to make
242 ------------------
244 	payload stub, application, support code. Mostly arch-neutral
251 	x86 support code for running as an EFI application
253 board/efi/efi-x86/efi.c
254 	x86 board code for running as an EFI application
259 --
267 -------------------------------------------------------------------------------
269 EFI on U-Boot
272 In addition to support for running U-Boot as a UEFI application, U-Boot itself
277 -------------------
280 kernel, grub2 or gummiboot) on U-Boot. This dramatically simplifies boot loader
281 configuration, as U-Boot based systems now look and feel (almost) the same way
285 ----------------
287 EFI support for 32bit ARM and AArch64 is already included in U-Boot. All you
294 an efi application as well as snippet in the default distro boot script that
298 ------
303 When enabled, the resulting U-Boot binary only grows by ~10KB, so it's very
315 ---------------------
317 You can run a simple 'hello world' EFI program in U-Boot.
320 Then you can boot into U-Boot and type:
328 -----------
332    - Improve disk media detection (don't scan, use what information we
334    - Add EFI variable support using NVRAM
335    - Add GFX support
336    - Make EFI Shell work
337    - Network device support
338    - Support for payload exit
339    - Payload Watchdog support