# SPDX-License-Identifier: GPL-2.0+
#
+=========== Table of Contents ===========
+
+ 1 U-Boot on EFI
+ 1.1 In God's Name, Why?
+ 1.2 Status
+ 1.3 Build Instructions
+ 1.4 Trying it out
+ 1.5 Inner workings
+ 1.6 EFI Application
+ 1.7 EFI Payload
+ 1.8 Tables
+ 1.9 Interrupts
+ 1.10 32/64-bit
+ 1.11 Future work
+ 1.12 Where is the code?
+
+ 2 EFI on U-Boot
+ 2.1 In God's Name, Why?
+ 2.2 How do I get it?
+ 2.3 Status
+ 2.4 Future work
+
U-Boot on EFI
=============
This document provides information about U-Boot running on top of EFI, either
Build Instructions
------------------
First choose a board that has EFI support and obtain an EFI implementation
-for that board. It will be either 32-bit or 64-bit.
+for that board. It will be either 32-bit or 64-bit. Alternatively, you can
+opt for using QEMU [1] and the OVMF [2], as detailed below.
-To build U-Boot as an EFI application (32-bit EFI required), enable
-CONFIG_EFI and CONFIG_EFI_APP. The efi-x86 config is set up for this.
+To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI
+and CONFIG_EFI_APP. The efi-x86 config (efi-x86_defconfig) is set up for this.
+Just build U-Boot as normal, e.g.
-To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust
-an existing config to enable CONFIG_EFI, CONFIG_EFI_STUB and either
-CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT.
+ make efi-x86_defconfig
+ make
-Then build U-Boot as normal, e.g.
+To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust an
+existing config (like qemu-x86_defconfig) to enable CONFIG_EFI, CONFIG_EFI_STUB
+and either CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT. All of these are
+boolean Kconfig options. Then build U-Boot as normal, e.g.
make qemu-x86_defconfig
- make menuconfig (or make xconfig if you prefer)
- # change the settings as above
make
-You will end up with one of these files:
+You will end up with one of these files depending on what you build for:
u-boot-app.efi - U-Boot EFI application
u-boot-payload.efi - U-Boot EFI payload application
Trying it out
-------------
-Qemu is an emulator and it can emulate an x86 machine. You can run the
-payload with something like this:
+QEMU is an emulator and it can emulate an x86 machine. Please make sure your
+QEMU version is 2.3.0 or above to test this. You can run the payload with
+something like this:
mkdir /tmp/efi
cp /path/to/u-boot*.efi /tmp/efi
Add -nographic if you want to use the terminal for output. Once it starts
type 'fs0:u-boot-payload.efi' to run the payload or 'fs0:u-boot-app.efi' to
-run the application. 'bios.bin' is the EFI 'BIOS'.
+run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a
+prebuilt EFI BIOS for QEMU or you can build one from source as well.
To try it on real hardware, put u-boot-app.efi on a suitable boot medium,
such as a USB stick. Then you can type something like this to start it:
common/cmd_efi.c
the 'efi' command
-
--
Ben Stoltz, Simon Glass
Google, Inc
July 2015
+
+[1] http://www.qemu.org
+[2] http://www.tianocore.org/ovmf/
+
+-------------------------------------------------------------------------------
+
+EFI on U-Boot
+=============
+
+In addition to support for running U-Boot as a UEFI application, U-Boot itself
+can also expose the UEFI interfaces and thus allow UEFI payloads to run under
+it.
+
+In God's Name, Why?
+-------------------
+
+With this support in place, you can run any UEFI payload (such as the Linux
+kernel, grub2 or gummiboot) on U-Boot. This dramatically simplifies boot loader
+configuration, as U-Boot based systems now look and feel (almost) the same way
+as TianoCore based systems.
+
+How do I get it?
+----------------
+
+EFI support for 32bit ARM and AArch64 is already included in U-Boot. All you
+need to do is enable
+
+ CONFIG_CMD_BOOTEFI=y
+ CONFIG_EFI_LOADER=y
+
+in your .config file and you will automatically get a bootefi command to run
+an efi application as well as snippet in the default distro boot script that
+scans for removable media efi binaries as fallback.
+
+Status
+------
+
+I am successfully able to run grub2 and Linux EFI binaries with this code on
+ARMv7 as well as AArch64 systems.
+
+When enabled, the resulting U-Boot binary only grows by ~10KB, so it's very
+light weight.
+
+All storage devices are directly accessible from the uEFI payload
+
+Removable media booting (search for /efi/boot/boota{a64,arm}.efi) is supported.
+
+Simple use cases like "Plug this SD card into my ARM device and it just
+boots into grub which boots into Linux", work very well.
+
+
+Running HelloWord.efi
+---------------------
+
+You can run a simple 'hello world' EFI program in U-Boot.
+Enable the option CONFIG_CMD_BOOTEFI_HELLO.
+
+Then you can boot into U-Boot and type:
+
+ > bootefi hello
+
+The 'hello world EFI' program will then run, print a message and exit.
+
+
+Future work
+-----------
+
+Of course, there are still a few things one could do on top:
+
+ - Improve disk media detection (don't scan, use what information we
+have)
+ - Add EFI variable support using NVRAM
+ - Add GFX support
+ - Make EFI Shell work
+ - Network device support
+ - Support for payload exit
+ - Payload Watchdog support