u-boot/doc/README.u-boot_on_efi

1 # SPDX-License-Identifier: GPL-2.0+
5 U-Boot on EFI
7 This document provides information about U-Boot running on top of EFI, either
8 as an application or just as a means of getting U-Boot onto a new platform.
18 EFI Application
22 32/64-bit
28 ----------
29 Running U-Boot on EFI is useful in several situations:
31 - You have EFI running on a board but U-Boot does not natively support it
32 fully yet. You can boot into U-Boot from EFI and use that until U-Boot is
35 - You need to use an EFI implementation (e.g. UEFI) because your vendor
38 - You plan to use coreboot to boot into U-Boot but coreboot support does
39 not currently exist for your platform. In the meantime you can use U-Boot
40 on EFI and then move to U-Boot on coreboot when ready
42 - You use EFI but want to experiment with a simpler alternative like U-Boot
46 ------
51 U-Boot supports running as an EFI application for 32-bit EFI only. This is
55 More usefully, U-Boot supports building itself as a payload for either 32-bit
56 or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once
57 started, U-Boot changes to 32-bit mode (currently) and takes over the
62 ------------------
64 for that board. It will be either 32-bit or 64-bit. Alternatively, you can
67 To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI
68 and CONFIG_EFI_APP. The efi-x86_app config (efi-x86_app_defconfig) is set up
69 for this. Just build U-Boot as normal, e.g.
71    make efi-x86_app_defconfig
74 To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable
76 CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig
77 and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as
80    make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig)
85    u-boot-app.efi      - U-Boot EFI application
86    u-boot-payload.efi  - U-Boot EFI payload application
90 -------------
96    cp /path/to/u-boot*.efi /tmp/efi
97    qemu-system-x86_64 -bios bios.bin -hda fat:/tmp/efi/
99 Add -nographic if you want to use the terminal for output. Once it starts
100 type 'fs0:u-boot-payload.efi' to run the payload or 'fs0:u-boot-app.efi' to
101 run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a
104 To try it on real hardware, put u-boot-app.efi on a suitable boot medium,
107    fs0:u-boot-payload.efi
109 (or fs0:u-boot-app.efi for the application)
111 This will start the payload, copy U-Boot into RAM and start U-Boot. Note
112 that EFI does not support booting a 64-bit application from a 32-bit
119 Here follow a few implementation notes for those who want to fiddle with
122 The application and payload approaches sound similar but are in fact
125 EFI Application
126 ---------------
127 For the application the whole of U-Boot is built as a shared library. The
129 functions with efi_init(), sets up U-Boot global_data, allocates memory for
130 U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f()
133 Since U-Boot limits its memory access to the allocated regions very little
144 consoles will be active. Even though U-Boot does the same thing normally,
145 These are features of EFI, not U-Boot.
147 Very little code is involved in implementing the EFI application feature.
148 U-Boot is highly portable. Most of the difficulty is in modifying the
150 little x86-specific code involved - you can find most of it in
157 -----------
159 U-Boot exactly as normal for your target board, then adding the entire
160 image (including device tree) into a small EFI stub application responsible
161 for booting it. The stub application is built as a normal EFI application
164 The stub application is implemented in lib/efi/efi_stub.c. The efi_main()
165 function is called by EFI. It is responsible for copying U-Boot from its
167 U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc.
169 The stub application is architecture-dependent. At present it has some
170 x86-specific code and a comment at the top of efi_stub.c describes this.
172 While the stub application does allocate some memory from EFI this is not
173 used by U-Boot (the payload). In fact when U-Boot starts it has all of the
178 ------
179 The payload can pass information to U-Boot in the form of EFI tables. At
182 display this list. U-Boot uses the list to work out where to relocate
185 Although U-Boot can use any memory it likes, EFI marks some memory as used
186 by 'run-time services', code that hangs around while U-Boot is running and
189 fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It
194 ----------
195 U-Boot drivers typically don't use interrupts. Since EFI enables interrupts
196 it is possible that an interrupt will fire that U-Boot cannot handle. This
197 seems to cause problems. For this reason the U-Boot payload runs with
200 32/64-bit
201 ---------
202 While the EFI application can in principle be built as either 32- or 64-bit,
203 only 32-bit is currently supported. This means that the application can only
204 be used with 32-bit EFI.
206 The payload stub can be build as either 32- or 64-bits. Only a small amount
207 of code is built this way (see the extra- line in lib/efi/Makefile).
208 Everything else is built as a normal U-Boot, so is always 32-bit on x86 at
212 -----------
215 - Add ARM support
217 - Add 64-bit application support
219 - Figure out how to solve the interrupt problem
221 - Add more drivers to the application side (e.g. video, block devices, USB,
225 - Avoid turning off boot services in the stub. Instead allow U-Boot to make
230 ------------------
232 	payload stub, application, support code. Mostly arch-neutral
235 	x86 support code for running as an EFI application and payload
237 board/efi/efi-x86_app/efi.c
238 	x86 board code for running as an EFI application
240 board/efi/efi-x86_payload
246 --