* [U-Boot] [PATCH 1/1] doc: integrate UEFI documentation into Sphinx toctree
@ 2019-07-26 4:56 Heinrich Schuchardt
2019-07-26 6:36 ` Bin Meng
0 siblings, 1 reply; 2+ messages in thread
From: Heinrich Schuchardt @ 2019-07-26 4:56 UTC (permalink / raw)
To: u-boot
Change the UEFI documentation to Sphinx style and integrate it into the
rest of the Sphinx generated documentation.
Remove the inaccurate TODO list in doc/uefi/uefi.rst.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
MAINTAINERS | 4 +-
doc/README.iscsi | 170 ------------------
doc/README.u-boot_on_efi | 252 --------------------------
doc/README.uefi | 352 -------------------------------------
doc/index.rst | 13 ++
doc/uefi/index.rst | 11 ++
doc/uefi/iscsi.rst | 180 +++++++++++++++++++
doc/uefi/u-boot_on_efi.rst | 235 +++++++++++++++++++++++++
doc/uefi/uefi.rst | 334 +++++++++++++++++++++++++++++++++++
9 files changed, 774 insertions(+), 777 deletions(-)
delete mode 100644 doc/README.iscsi
delete mode 100644 doc/README.u-boot_on_efi
delete mode 100644 doc/README.uefi
create mode 100644 doc/uefi/index.rst
create mode 100644 doc/uefi/iscsi.rst
create mode 100644 doc/uefi/u-boot_on_efi.rst
create mode 100644 doc/uefi/uefi.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index a72ccd0b58..12ad127adc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -477,9 +477,7 @@ M: Heinrich Schuchardt <xypron.glpk@gmx.de>
R: Alexander Graf <agraf@csgraf.de>
S: Maintained
T: git https://gitlab.denx.de/u-boot/custodians/u-boot-efi.git
-F: doc/README.uefi
-F: doc/README.iscsi
-F: doc/efi.rst
+F: doc/uefi/*
F: include/capitalization.h
F: include/charset.h
F: include/cp1250.h
diff --git a/doc/README.iscsi b/doc/README.iscsi
deleted file mode 100644
index 3a12438f90..0000000000
--- a/doc/README.iscsi
+++ /dev/null
@@ -1,170 +0,0 @@
-# iSCSI booting with U-Boot and iPXE
-
-## Motivation
-
-U-Boot has only a reduced set of supported network protocols. The focus for
-network booting has been on UDP based protocols. A TCP stack and HTTP support
-are expected to be integrated in 2018 together with a wget command.
-
-For booting a diskless computer this leaves us with BOOTP or DHCP to get the
-address of a boot script. TFTP or NFS can be used to load the boot script, the
-operating system kernel and the initial file system (initrd).
-
-These protocols are insecure. The client cannot validate the authenticity
-of the contacted servers. And the server cannot verify the identity of the
-client.
-
-Furthermore the services providing the operating system loader or kernel are
-not the ones that the operating system typically will use. Especially in a SAN
-environment this makes updating the operating system a hassle. After installing
-a new kernel version the boot files have to be copied to the TFTP server
-directory.
-
-The HTTPS protocol provides certificate based validation of servers. Sensitive
-data like passwords can be securely transmitted.
-
-The iSCSI protocol is used for connecting storage attached networks. It
-provides mutual authentication using the CHAP protocol. It typically runs on
-a TCP transport.
-
-Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script
-via HTTPS and to download any other files needed for booting via iSCSI from the
-same target where the operating system is installed.
-
-An alternative to implementing these protocols in U-Boot is to use an existing
-software that can run on top of U-Boot. iPXE[1] is the "swiss army knife" of
-network booting. It supports both HTTPS and iSCSI. It has a scripting engine for
-fine grained control of the boot process and can provide a command shell.
-
-iPXE can be built as an EFI application (named snp.efi) which can be loaded and
-run by U-Boot.
-
-## Boot sequence
-
-U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This
-application has network access via the simple network protocol offered by
-U-Boot.
-
-iPXE executes its internal script. This script may optionally chain load a
-secondary boot script via HTTPS or open a shell.
-
-For the further boot process iPXE connects to the iSCSI server. This includes
-the mutual authentication using the CHAP protocol. After the authentication iPXE
-has access to the iSCSI targets.
-
-For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It
-uses the ConnectController boot service of U-Boot to request U-Boot to connect a
-file system driver. U-Boot reads from the iSCSI drive via the block IO protocol
-offered by iPXE. It creates the partition handles and installs the simple file
-protocol. Now iPXE can call the simple file protocol to load GRUB[2]. U-Boot
-uses the block IO protocol offered by iPXE to fulfill the request.
-
-Once GRUB is started it uses the same block IO protocol to load Linux. Via
-the EFI stub Linux is called as an EFI application::
-
- +--------+ +--------+
- | | Runs | |
- | U-Boot |========>| iPXE |
- | EFI | | snp.efi|
- +--------+ | | DHCP | |
- | |<===|********|<========| |
- | DHCP | | | Get IP | |
- | Server | | | Address | |
- | |===>|********|========>| |
- +--------+ | | Response| |
- | | | |
- | | | |
- +--------+ | | HTTPS | |
- | |<===|********|<========| |
- | HTTPS | | | Load | |
- | Server | | | Script | |
- | |===>|********|========>| |
- +--------+ | | | |
- | | | |
- | | | |
- +--------+ | | iSCSI | |
- | |<===|********|<========| |
- | iSCSI | | | Auth | |
- | Server |===>|********|========>| |
- | | | | | |
- | | | | Loads | |
- | |<===|********|<========| | +--------+
- | | | | GRUB | | Runs | |
- | |===>|********|========>| |======>| GRUB |
- | | | | | | | |
- | | | | | | | |
- | | | | | | Loads | |
- | |<===|********|<========|********|<======| | +--------+
- | | | | | | Linux | | Runs | |
- | |===>|********|========>|********|======>| |=====>| Linux |
- | | | | | | | | | |
- +--------+ +--------+ +--------+ +--------+ | |
- | |
- | |
- | ~ ~ ~ ~|
-
-## Security
-
-The iSCSI protocol is not encrypted. The traffic could be secured using IPsec
-but neither U-Boot nor iPXE does support this. So we should at least separate
-the iSCSI traffic from all other network traffic. This can be achieved using a
-virtual local area network (VLAN).
-
-## Configuration
-
-### iPXE
-
-For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed::
-
- git clone http://git.ipxe.org/ipxe.git
- cd ipxe/src
- make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe
-
-The available commands for the boot script are documented at:
-
-http://ipxe.org/cmd
-
-Credentials are managed as environment variables. These are described here:
-
-http://ipxe.org/cfg
-
-iPXE by default will put the CPU to rest when waiting for input. U-Boot does
-not wake it up due to missing interrupt support. To avoid this behavior create
-file src/config/local/nap.h::
-
- /* nap.h */
- #undef NAP_EFIX86
- #undef NAP_EFIARM
- #define NAP_NULL
-
-The supported commands in iPXE are controlled by an include, too. Putting the
-following into src/config/local/general.h is sufficient for most use cases::
-
- /* general.h */
- #define NSLOOKUP_CMD /* Name resolution command */
- #define PING_CMD /* Ping command */
- #define NTP_CMD /* NTP commands */
- #define VLAN_CMD /* VLAN commands */
- #define IMAGE_EFI /* EFI image support */
- #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */
- #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */
- #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */
- #define DOWNLOAD_PROTO_FILE /* Local file system access */
-
-### Open-iSCSI
-
-When the root file system is on an iSCSI drive you should disable pings and set
-the replacement timer to a high value [3]:
-
- node.conn[0].timeo.noop_out_interval = 0
- node.conn[0].timeo.noop_out_timeout = 0
- node.session.timeo.replacement_timeout = 86400
-
-## Links
-
-* [1](https://ipxe.org) https://ipxe.org - iPXE open source boot firmware
-* [2](https://www.gnu.org/software/grub/) https://www.gnu.org/software/grub/ -
- GNU GRUB (Grand Unified Bootloader)
-* [3](https://github.com/open-iscsi/open-iscsi/blob/master/README)
- https://github.com/open-iscsi/open-iscsi/blob/master/README -
- Open-iSCSI README
diff --git a/doc/README.u-boot_on_efi b/doc/README.u-boot_on_efi
deleted file mode 100644
index e12dd4e3e6..0000000000
--- a/doc/README.u-boot_on_efi
+++ /dev/null
@@ -1,252 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0+
-#
-# Copyright (C) 2015 Google, Inc
-
-U-Boot on EFI
-=============
-This document provides information about U-Boot running on top of EFI, either
-as an application or just as a means of getting U-Boot onto a new platform.
-
-
-=========== Table of Contents ===========
-
-Motivation
-Status
-Build Instructions
-Trying it out
-Inner workings
-EFI Application
-EFI Payload
-Tables
-Interrupts
-32/64-bit
-Future work
-Where is the code?
-
-
-Motivation
-----------
-Running U-Boot on EFI is useful in several situations:
-
-- You have EFI running on a board but U-Boot does not natively support it
-fully yet. You can boot into U-Boot from EFI and use that until U-Boot is
-fully ported
-
-- You need to use an EFI implementation (e.g. UEFI) because your vendor
-requires it in order to provide support
-
-- You plan to use coreboot to boot into U-Boot but coreboot support does
-not currently exist for your platform. In the meantime you can use U-Boot
-on EFI and then move to U-Boot on coreboot when ready
-
-- You use EFI but want to experiment with a simpler alternative like U-Boot
-
-
-Status
-------
-Only x86 is supported at present. If you are using EFI on another architecture
-you may want to reconsider. However, much of the code is generic so could be
-ported.
-
-U-Boot supports running as an EFI application for 32-bit EFI only. This is
-not very useful since only a serial port is provided. You can look around at
-memory and type 'help' but that is about it.
-
-More usefully, U-Boot supports building itself as a payload for either 32-bit
-or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once
-started, U-Boot changes to 32-bit mode (currently) and takes over the
-machine. You can use devices, boot a kernel, etc.
-
-
-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. 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_app config (efi-x86_app_defconfig) is set up
-for this. Just build U-Boot as normal, e.g.
-
- make efi-x86_app_defconfig
- make
-
-To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable
-CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or
-CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig
-and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as
-normal, e.g.
-
- make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig)
- make
-
-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. 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
- qemu-system-x86_64 -bios bios.bin -hda fat:/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'. 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:
-
- fs0:u-boot-payload.efi
-
-(or fs0:u-boot-app.efi for the application)
-
-This will start the payload, copy U-Boot into RAM and start U-Boot. Note
-that EFI does not support booting a 64-bit application from a 32-bit
-EFI (or vice versa). Also it will often fail to print an error message if
-you get this wrong.
-
-
-Inner workings
-==============
-Here follow a few implementation notes for those who want to fiddle with
-this and perhaps contribute patches.
-
-The application and payload approaches sound similar but are in fact
-implemented completely differently.
-
-EFI Application
----------------
-For the application the whole of U-Boot is built as a shared library. The
-efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI
-functions with efi_init(), sets up U-Boot global_data, allocates memory for
-U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f()
-and board_init_r()).
-
-Since U-Boot limits its memory access to the allocated regions very little
-special code is needed. The CONFIG_EFI_APP option controls a few things
-that need to change so 'git grep CONFIG_EFI_APP' may be instructive.
-The CONFIG_EFI option controls more general EFI adjustments.
-
-The only available driver is the serial driver. This calls back into EFI
-'boot services' to send and receive characters. Although it is implemented
-as a serial driver the console device is not necessarilly serial. If you
-boot EFI with video output then the 'serial' device will operate on your
-target devices's display instead and the device's USB keyboard will also
-work if connected. If you have both serial and video output, then both
-consoles will be active. Even though U-Boot does the same thing normally,
-These are features of EFI, not U-Boot.
-
-Very little code is involved in implementing the EFI application feature.
-U-Boot is highly portable. Most of the difficulty is in modifying the
-Makefile settings to pass the right build flags. In particular there is very
-little x86-specific code involved - you can find most of it in
-arch/x86/cpu. Porting to ARM (which can also use EFI if you are brave
-enough) should be straightforward.
-
-Use the 'reset' command to get back to EFI.
-
-EFI Payload
------------
-The payload approach is a different kettle of fish. It works by building
-U-Boot exactly as normal for your target board, then adding the entire
-image (including device tree) into a small EFI stub application responsible
-for booting it. The stub application is built as a normal EFI application
-except that it has a lot of data attached to it.
-
-The stub application is implemented in lib/efi/efi_stub.c. The efi_main()
-function is called by EFI. It is responsible for copying U-Boot from its
-original location into memory, disabling EFI boot services and starting
-U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc.
-
-The stub application is architecture-dependent. At present it has some
-x86-specific code and a comment at the top of efi_stub.c describes this.
-
-While the stub application does allocate some memory from EFI this is not
-used by U-Boot (the payload). In fact when U-Boot starts it has all of the
-memory available to it and can operate as it pleases (but see the next
-section).
-
-Tables
-------
-The payload can pass information to U-Boot in the form of EFI tables. At
-present this feature is used to pass the EFI memory map, an inordinately
-large list of memory regions. You can use the 'efi mem all' command to
-display this list. U-Boot uses the list to work out where to relocate
-itself.
-
-Although U-Boot can use any memory it likes, EFI marks some memory as used
-by 'run-time services', code that hangs around while U-Boot is running and
-is even present when Linux is running. This is common on x86 and provides
-a way for Linux to call back into the firmware to control things like CPU
-fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It
-will relocate itself to the top of the largest block of memory it can find
-below 4GB.
-
-Interrupts
-----------
-U-Boot drivers typically don't use interrupts. Since EFI enables interrupts
-it is possible that an interrupt will fire that U-Boot cannot handle. This
-seems to cause problems. For this reason the U-Boot payload runs with
-interrupts disabled at present.
-
-32/64-bit
----------
-While the EFI application can in principle be built as either 32- or 64-bit,
-only 32-bit is currently supported. This means that the application can only
-be used with 32-bit EFI.
-
-The payload stub can be build as either 32- or 64-bits. Only a small amount
-of code is built this way (see the extra- line in lib/efi/Makefile).
-Everything else is built as a normal U-Boot, so is always 32-bit on x86 at
-present.
-
-Future work
------------
-This work could be extended in a number of ways:
-
-- Add ARM support
-
-- Add 64-bit application support
-
-- Figure out how to solve the interrupt problem
-
-- Add more drivers to the application side (e.g. video, block devices, USB,
-environment access). This would mostly be an academic exercise as a strong
-use case is not readily apparent, but it might be fun.
-
-- Avoid turning off boot services in the stub. Instead allow U-Boot to make
-use of boot services in case it wants to. It is unclear what it might want
-though.
-
-Where is the code?
-------------------
-lib/efi
- payload stub, application, support code. Mostly arch-neutral
-
-arch/x86/cpu/efi
- x86 support code for running as an EFI application and payload
-
-board/efi/efi-x86_app/efi.c
- x86 board code for running as an EFI application
-
-board/efi/efi-x86_payload
- generic x86 EFI payload board support code
-
-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/
diff --git a/doc/README.uefi b/doc/README.uefi
deleted file mode 100644
index 1d1039a6ae..0000000000
--- a/doc/README.uefi
+++ /dev/null
@@ -1,352 +0,0 @@
-<!--
-SPDX-License-Identifier: GPL-2.0+
-
-Copyright (c) 2018 Heinrich Schuchardt
--->
-
-# UEFI on U-Boot
-
-The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
-the default for booting on AArch64 and x86 systems. It provides a stable API for
-the interaction of drivers and applications with the firmware. The API comprises
-access to block storage, network, and console to name a few. The Linux kernel
-and boot loaders like GRUB or the FreeBSD loader can be executed.
-
-## Development target
-
-The implementation of UEFI in U-Boot strives to reach the requirements described
-in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0"
-[4]. The "Server Base Boot Requirements System Software on ARM Platforms" [5]
-describes a superset of the EBBR specification and may be used as further
-reference.
-
-A full blown UEFI implementation would contradict the U-Boot design principle
-"keep it small".
-
-## Building for UEFI
-
-The UEFI standard supports only little-endian systems. The UEFI support can be
-activated for ARM and x86 by specifying
-
- CONFIG_CMD_BOOTEFI=y
- CONFIG_EFI_LOADER=y
-
-in the .config file.
-
-Support for attaching virtual block devices, e.g. iSCSI drives connected by the
-loaded UEFI application [3], requires
-
- CONFIG_BLK=y
- CONFIG_PARTITIONS=y
-
-### Executing a UEFI binary
-
-The bootefi command is used to start UEFI applications or to install UEFI
-drivers. It takes two parameters
-
- bootefi <image address> [fdt address]
-
-* image address - the memory address of the UEFI binary
-* fdt address - the memory address of the flattened device tree
-
-Below you find the output of an example session starting GRUB.
-
- => load mmc 0:2 ${fdt_addr_r} boot/dtb
- 29830 bytes read in 14 ms (2 MiB/s)
- => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
- reading efi/debian/grubaa64.efi
- 120832 bytes read in 7 ms (16.5 MiB/s)
- => bootefi ${kernel_addr_r} ${fdt_addr_r}
-
-The environment variable 'bootargs' is passed as load options in the UEFI system
-table. The Linux kernel EFI stub uses the load options as command line
-arguments.
-
-### Executing the boot manager
-
-The UEFI specification foresees to define boot entries and boot sequence via UEFI
-variables. Booting according to these variables is possible via
-
- bootefi bootmgr [fdt address]
-
-As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at
-runtime.
-
-### Executing the built in hello world application
-
-A hello world UEFI application can be built with
-
- CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
-
-It can be embedded into the U-Boot binary with
-
- CONFIG_CMD_BOOTEFI_HELLO=y
-
-The bootefi command is used to start the embedded hello world application.
-
- bootefi hello [fdt address]
-
-Below you find the output of an example session.
-
- => bootefi hello ${fdtcontroladdr}
- ## Starting EFI application at 01000000 ...
- WARNING: using memory device/image path, this may confuse some payloads!
- Hello, world!
- Running on UEFI 2.7
- Have SMBIOS table
- Have device tree
- Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
- ## Application terminated, r = 0
-
-The environment variable fdtcontroladdr points to U-Boot's internal device tree
-(if available).
-
-### Executing the built-in self-test
-
-An UEFI self-test suite can be embedded in U-Boot by building with
-
- CONFIG_CMD_BOOTEFI_SELFTEST=y
-
-For testing the UEFI implementation the bootefi command can be used to start the
-self-test.
-
- bootefi selftest [fdt address]
-
-The environment variable 'efi_selftest' can be used to select a single test. If
-it is not provided all tests are executed except those marked as 'on request'.
-If the environment variable is set to 'list' a list of all tests is shown.
-
-Below you can find the output of an example session.
-
- => setenv efi_selftest simple network protocol
- => bootefi selftest
- Testing EFI API implementation
- Selected test: 'simple network protocol'
- Setting up 'simple network protocol'
- Setting up 'simple network protocol' succeeded
- Executing 'simple network protocol'
- DHCP Discover
- DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02)
- as broadcast message.
- Executing 'simple network protocol' succeeded
- Tearing down 'simple network protocol'
- Tearing down 'simple network protocol' succeeded
- Boot services terminated
- Summary: 0 failures
- Preparing for reset. Press any key.
-
-## The UEFI life cycle
-
-After the U-Boot platform has been initialized the UEFI API provides two kinds
-of services
-
-* boot services and
-* runtime services.
-
-The API can be extended by loading UEFI drivers which come in two variants
-
-* boot drivers and
-* runtime drivers.
-
-UEFI drivers are installed with U-Boot's bootefi command. With the same command
-UEFI applications can be executed.
-
-Loaded images of UEFI drivers stay in memory after returning to U-Boot while
-loaded images of applications are removed from memory.
-
-An UEFI application (e.g. an operating system) that wants to take full control
-of the system calls ExitBootServices. After a UEFI application calls
-ExitBootServices
-
-* boot services are not available anymore
-* timer events are stopped
-* the memory used by U-Boot except for runtime services is released
-* the memory used by boot time drivers is released
-
-So this is a point of no return. Afterwards the UEFI application can only return
-to U-Boot by rebooting.
-
-## The UEFI object model
-
-UEFI offers a flexible and expandable object model. The objects in the UEFI API
-are devices, drivers, and loaded images. These objects are referenced by
-handles.
-
-The interfaces implemented by the objects are referred to as protocols. These
-are identified by GUIDs. They can be installed and uninstalled by calling the
-appropriate boot services.
-
-Handles are created by the InstallProtocolInterface or the
-InstallMultipleProtocolinterfaces service if NULL is passed as handle.
-
-Handles are deleted when the last protocol has been removed with the
-UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service.
-
-Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation
-of device nodes. By their device paths all devices of a system are arranged in a
-tree.
-
-Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect
-a driver to devices (which are referenced as controllers in this context).
-
-Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta
-information about the image and a pointer to the unload callback function.
-
-## The UEFI events
-
-In the UEFI terminology an event is a data object referencing a notification
-function which is queued for calling when the event is signaled. The following
-types of events exist:
-
-* periodic and single shot timer events
-* exit boot services events, triggered by calling the ExitBootServices() service
-* virtual address change events
-* memory map change events
-* read to boot events
-* reset system events
-* system table events
-* events that are only triggered programmatically
-
-Events can be created with the CreateEvent service and deleted with CloseEvent
-service.
-
-Events can be assigned to an event group. If any of the events in a group is
-signaled, all other events in the group are also set to the signaled state.
-
-## The UEFI driver model
-
-A driver is specific for a single protocol installed on a device. To install a
-driver on a device the ConnectController service is called. In this context
-controller refers to the device for which the driver is installed.
-
-The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This
-protocol has has three functions:
-
-* supported - determines if the driver is compatible with the device
-* start - installs the driver by opening the relevant protocol with
- attribute EFI_OPEN_PROTOCOL_BY_DRIVER
-* stop - uninstalls the driver
-
-The driver may create child controllers (child devices). E.g. a driver for block
-IO devices will create the device handles for the partitions. The child
-controllers will open the supported protocol with the attribute
-EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
-
-A driver can be detached from a device using the DisconnectController service.
-
-## U-Boot devices mapped as UEFI devices
-
-Some of the U-Boot devices are mapped as UEFI devices
-
-* block IO devices
-* console
-* graphical output
-* network adapter
-
-As of U-Boot 2018.03 the logic for doing this is hard coded.
-
-The development target is to integrate the setup of these UEFI devices with the
-U-Boot driver model. So when a U-Boot device is discovered a handle should be
-created and the device path protocol and the relevant IO protocol should be
-installed. The UEFI driver then would be attached by calling ConnectController.
-When a U-Boot device is removed DisconnectController should be called.
-
-## UEFI devices mapped as U-Boot devices
-
-UEFI drivers binaries and applications may create new (virtual) devices, install
-a protocol and call the ConnectController service. Now the matching UEFI driver
-is determined by iterating over the implementations of the
-EFI_DRIVER_BINDING_PROTOCOL.
-
-It is the task of the UEFI driver to create a corresponding U-Boot device and to
-proxy calls for this U-Boot device to the controller.
-
-In U-Boot 2018.03 this has only been implemented for block IO devices.
-
-### UEFI uclass
-
-An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
-takes care of initializing the UEFI drivers and providing the
-EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers.
-
-A linker created list is used to keep track of the UEFI drivers. To create an
-entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying
-UCLASS_EFI as the ID of its uclass, e.g.
-
- /* Identify as UEFI driver */
- U_BOOT_DRIVER(efi_block) = {
- .name = "EFI block driver",
- .id = UCLASS_EFI,
- .ops = &driver_ops,
- };
-
-The available operations are defined via the structure struct efi_driver_ops.
-
- struct efi_driver_ops {
- const efi_guid_t *protocol;
- const efi_guid_t *child_protocol;
- int (*bind)(efi_handle_t handle, void *interface);
- };
-
-When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the
-uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver.
-In the start() function the bind() function of the UEFI driver is called after
-checking the GUID.
-The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child
-controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03
-this is not yet completely implemented.)
-
-### UEFI block IO driver
-
-The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL.
-
-When connected it creates a new U-Boot block IO device with interface type
-IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the
-EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the
-software iPXE to boot from iSCSI network drives [3].
-
-This driver is only available if U-Boot is configured with
-
- CONFIG_BLK=y
- CONFIG_PARTITIONS=y
-
-## TODOs as of U-Boot 2019.04
-
-* unimplemented or incompletely implemented boot services
- * Exit - call unload function, unload applications only
- * ProtocolRegisterNotify
- * UnloadImage
-
-* unimplemented or incompletely implemented runtime services
- * SetVariable() ignores attribute EFI_VARIABLE_APPEND_WRITE
- * QueryVariableInfo is not implemented
-
-* unimplemented events
- * EVT_RUNTIME
- * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
-
-* data model
- * manage configuration tables in a linked list
-
-* UEFI drivers
- * support DisconnectController for UEFI block devices.
-
-* support for CONFIG_EFI_LOADER in the sandbox (CONFIG_SANDBOX=y)
-
-* UEFI variables
- * persistence
- * runtime support
-
-* incompletely implemented protocols
- * support version 0x00020000 of the EFI file protocol
-
-## Links
-
-* [1](http://uefi.org/specifications)
- http://uefi.org/specifications - UEFI specifications
-* [2](./driver-model/README.txt) doc/driver-model/README.txt - Driver model
-* [3](./README.iscsi) doc/README.iscsi - iSCSI booting with U-Boot and iPXE
-* [4](https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf)
- Embedded Base Boot Requirements (EBBR) Specification - Release v1.0
-* [5](https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11)
- Server Base Boot Requirements System Software on ARM Platforms - Version 1.1
diff --git a/doc/index.rst b/doc/index.rst
index 9ae2e167bc..458f0d2d0e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,8 +15,21 @@ if you want to help out.
.. toctree::
:maxdepth: 2
+Unified Extensible Firmware (UEFI)
+----------------------------------
+
+U-Boot provides an implementation of the UEFI API allowing to run UEFI
+compliant software like Linux, GRUB, and iPXE. Furthermore U-Boot itself
+can be run an UEFI payload.
+
+.. toctree::
+ :maxdepth: 2
+
+ uefi/index
+
Driver-Model documentation
--------------------------
+
The following holds information on the U-Boot device driver framework:
driver-model, including the design details of itself and several driver
subsystems.
diff --git a/doc/uefi/index.rst b/doc/uefi/index.rst
new file mode 100644
index 0000000000..b790a91f17
--- /dev/null
+++ b/doc/uefi/index.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Unified Extensible Firmware (UEFI)
+==================================
+
+.. toctree::
+ :maxdepth: 2
+
+ uefi.rst
+ u-boot_on_efi.rst
+ iscsi.rst
diff --git a/doc/uefi/iscsi.rst b/doc/uefi/iscsi.rst
new file mode 100644
index 0000000000..aa844a7cc3
--- /dev/null
+++ b/doc/uefi/iscsi.rst
@@ -0,0 +1,180 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2018 Heinrich Schuchardt
+
+iSCSI booting with U-Boot and iPXE
+==================================
+
+Motivation
+----------
+
+U-Boot has only a reduced set of supported network protocols. The focus for
+network booting has been on UDP based protocols. A TCP stack and HTTP support
+are expected to be integrated in 2018 together with a wget command.
+
+For booting a diskless computer this leaves us with BOOTP or DHCP to get the
+address of a boot script. TFTP or NFS can be used to load the boot script, the
+operating system kernel and the initial file system (initrd).
+
+These protocols are insecure. The client cannot validate the authenticity
+of the contacted servers. And the server cannot verify the identity of the
+client.
+
+Furthermore the services providing the operating system loader or kernel are
+not the ones that the operating system typically will use. Especially in a SAN
+environment this makes updating the operating system a hassle. After installing
+a new kernel version the boot files have to be copied to the TFTP server
+directory.
+
+The HTTPS protocol provides certificate based validation of servers. Sensitive
+data like passwords can be securely transmitted.
+
+The iSCSI protocol is used for connecting storage attached networks. It
+provides mutual authentication using the CHAP protocol. It typically runs on
+a TCP transport.
+
+Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script
+via HTTPS and to download any other files needed for booting via iSCSI from the
+same target where the operating system is installed.
+
+An alternative to implementing these protocols in U-Boot is to use an existing
+software that can run on top of U-Boot. iPXE[1] is the "swiss army knife" of
+network booting. It supports both HTTPS and iSCSI. It has a scripting engine for
+fine grained control of the boot process and can provide a command shell.
+
+iPXE can be built as an EFI application (named snp.efi) which can be loaded and
+run by U-Boot.
+
+Boot sequence
+-------------
+
+U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This
+application has network access via the simple network protocol offered by
+U-Boot.
+
+iPXE executes its internal script. This script may optionally chain load a
+secondary boot script via HTTPS or open a shell.
+
+For the further boot process iPXE connects to the iSCSI server. This includes
+the mutual authentication using the CHAP protocol. After the authentication iPXE
+has access to the iSCSI targets.
+
+For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It
+uses the ConnectController boot service of U-Boot to request U-Boot to connect a
+file system driver. U-Boot reads from the iSCSI drive via the block IO protocol
+offered by iPXE. It creates the partition handles and installs the simple file
+protocol. Now iPXE can call the simple file protocol to load GRUB[2]. U-Boot
+uses the block IO protocol offered by iPXE to fulfill the request.
+
+Once GRUB is started it uses the same block IO protocol to load Linux. Via
+the EFI stub Linux is called as an EFI application::
+
+ +--------+ +--------+
+ | | Runs | |
+ | U-Boot |========>| iPXE |
+ | EFI | | snp.efi|
+ +--------+ | | DHCP | |
+ | |<===|********|<========| |
+ | DHCP | | | Get IP | |
+ | Server | | | Address | |
+ | |===>|********|========>| |
+ +--------+ | | Response| |
+ | | | |
+ | | | |
+ +--------+ | | HTTPS | |
+ | |<===|********|<========| |
+ | HTTPS | | | Load | |
+ | Server | | | Script | |
+ | |===>|********|========>| |
+ +--------+ | | | |
+ | | | |
+ | | | |
+ +--------+ | | iSCSI | |
+ | |<===|********|<========| |
+ | iSCSI | | | Auth | |
+ | Server |===>|********|========>| |
+ | | | | | |
+ | | | | Loads | |
+ | |<===|********|<========| | +--------+
+ | | | | GRUB | | Runs | |
+ | |===>|********|========>| |======>| GRUB |
+ | | | | | | | |
+ | | | | | | | |
+ | | | | | | Loads | |
+ | |<===|********|<========|********|<======| | +--------+
+ | | | | | | Linux | | Runs | |
+ | |===>|********|========>|********|======>| |=====>| Linux |
+ | | | | | | | | | |
+ +--------+ +--------+ +--------+ +--------+ | |
+ | |
+ | |
+ | ~ ~ ~ ~|
+
+Security
+--------
+
+The iSCSI protocol is not encrypted. The traffic could be secured using IPsec
+but neither U-Boot nor iPXE does support this. So we should at least separate
+the iSCSI traffic from all other network traffic. This can be achieved using a
+virtual local area network (VLAN).
+
+Configuration
+-------------
+
+iPXE
+~~~~
+
+For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed::
+
+ git clone http://git.ipxe.org/ipxe.git
+ cd ipxe/src
+ make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe
+
+The available commands for the boot script are documented at:
+
+http://ipxe.org/cmd
+
+Credentials are managed as environment variables. These are described here:
+
+http://ipxe.org/cfg
+
+iPXE by default will put the CPU to rest when waiting for input. U-Boot does
+not wake it up due to missing interrupt support. To avoid this behavior create
+file src/config/local/nap.h::
+
+ /* nap.h */
+ #undef NAP_EFIX86
+ #undef NAP_EFIARM
+ #define NAP_NULL
+
+The supported commands in iPXE are controlled by an include, too. Putting the
+following into src/config/local/general.h is sufficient for most use cases::
+
+ /* general.h */
+ #define NSLOOKUP_CMD /* Name resolution command */
+ #define PING_CMD /* Ping command */
+ #define NTP_CMD /* NTP commands */
+ #define VLAN_CMD /* VLAN commands */
+ #define IMAGE_EFI /* EFI image support */
+ #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */
+ #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */
+ #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */
+ #define DOWNLOAD_PROTO_FILE /* Local file system access */
+
+Open-iSCSI
+~~~~~~~~~~
+
+When the root file system is on an iSCSI drive you should disable pings and set
+the replacement timer to a high value [3]:
+
+ node.conn[0].timeo.noop_out_interval = 0
+ node.conn[0].timeo.noop_out_timeout = 0
+ node.session.timeo.replacement_timeout = 86400
+
+Links
+-----
+
+* [1] https://ipxe.org - iPXE open source boot firmware
+* [2] https://www.gnu.org/software/grub/ -
+ GNU GRUB (Grand Unified Bootloader)
+* [3] https://github.com/open-iscsi/open-iscsi/blob/master/README -
+ Open-iSCSI README
diff --git a/doc/uefi/u-boot_on_efi.rst b/doc/uefi/u-boot_on_efi.rst
new file mode 100644
index 0000000000..139173bc7a
--- /dev/null
+++ b/doc/uefi/u-boot_on_efi.rst
@@ -0,0 +1,235 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2015 Google, Inc
+
+U-Boot on EFI
+=============
+This document provides information about U-Boot running on top of EFI, either
+as an application or just as a means of getting U-Boot onto a new platform.
+
+
+Motivation
+----------
+Running U-Boot on EFI is useful in several situations:
+
+- You have EFI running on a board but U-Boot does not natively support it
+ fully yet. You can boot into U-Boot from EFI and use that until U-Boot is
+ fully ported
+
+- You need to use an EFI implementation (e.g. UEFI) because your vendor
+ requires it in order to provide support
+
+- You plan to use coreboot to boot into U-Boot but coreboot support does
+ not currently exist for your platform. In the meantime you can use U-Boot
+ on EFI and then move to U-Boot on coreboot when ready
+
+- You use EFI but want to experiment with a simpler alternative like U-Boot
+
+
+Status
+------
+Only x86 is supported at present. If you are using EFI on another architecture
+you may want to reconsider. However, much of the code is generic so could be
+ported.
+
+U-Boot supports running as an EFI application for 32-bit EFI only. This is
+not very useful since only a serial port is provided. You can look around at
+memory and type 'help' but that is about it.
+
+More usefully, U-Boot supports building itself as a payload for either 32-bit
+or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once
+started, U-Boot changes to 32-bit mode (currently) and takes over the
+machine. You can use devices, boot a kernel, etc.
+
+
+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. 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_app config (efi-x86_app_defconfig) is set up
+for this. Just build U-Boot as normal, e.g.
+
+ make efi-x86_app_defconfig
+ make
+
+To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable
+CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or
+CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig
+and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as
+normal, e.g.
+
+ make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig)
+ make
+
+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. 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
+ qemu-system-x86_64 -bios bios.bin -hda fat:/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'. 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:
+
+ fs0:u-boot-payload.efi
+
+(or fs0:u-boot-app.efi for the application)
+
+This will start the payload, copy U-Boot into RAM and start U-Boot. Note
+that EFI does not support booting a 64-bit application from a 32-bit
+EFI (or vice versa). Also it will often fail to print an error message if
+you get this wrong.
+
+
+Inner workings
+--------------
+Here follow a few implementation notes for those who want to fiddle with
+this and perhaps contribute patches.
+
+The application and payload approaches sound similar but are in fact
+implemented completely differently.
+
+EFI Application
+~~~~~~~~~~~~~~~
+For the application the whole of U-Boot is built as a shared library. The
+efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI
+functions with efi_init(), sets up U-Boot global_data, allocates memory for
+U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f()
+and board_init_r()).
+
+Since U-Boot limits its memory access to the allocated regions very little
+special code is needed. The CONFIG_EFI_APP option controls a few things
+that need to change so 'git grep CONFIG_EFI_APP' may be instructive.
+The CONFIG_EFI option controls more general EFI adjustments.
+
+The only available driver is the serial driver. This calls back into EFI
+'boot services' to send and receive characters. Although it is implemented
+as a serial driver the console device is not necessarilly serial. If you
+boot EFI with video output then the 'serial' device will operate on your
+target devices's display instead and the device's USB keyboard will also
+work if connected. If you have both serial and video output, then both
+consoles will be active. Even though U-Boot does the same thing normally,
+These are features of EFI, not U-Boot.
+
+Very little code is involved in implementing the EFI application feature.
+U-Boot is highly portable. Most of the difficulty is in modifying the
+Makefile settings to pass the right build flags. In particular there is very
+little x86-specific code involved - you can find most of it in
+arch/x86/cpu. Porting to ARM (which can also use EFI if you are brave
+enough) should be straightforward.
+
+Use the 'reset' command to get back to EFI.
+
+EFI Payload
+~~~~~~~~~~~
+The payload approach is a different kettle of fish. It works by building
+U-Boot exactly as normal for your target board, then adding the entire
+image (including device tree) into a small EFI stub application responsible
+for booting it. The stub application is built as a normal EFI application
+except that it has a lot of data attached to it.
+
+The stub application is implemented in lib/efi/efi_stub.c. The efi_main()
+function is called by EFI. It is responsible for copying U-Boot from its
+original location into memory, disabling EFI boot services and starting
+U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc.
+
+The stub application is architecture-dependent. At present it has some
+x86-specific code and a comment at the top of efi_stub.c describes this.
+
+While the stub application does allocate some memory from EFI this is not
+used by U-Boot (the payload). In fact when U-Boot starts it has all of the
+memory available to it and can operate as it pleases (but see the next
+section).
+
+Tables
+~~~~~~
+The payload can pass information to U-Boot in the form of EFI tables. At
+present this feature is used to pass the EFI memory map, an inordinately
+large list of memory regions. You can use the 'efi mem all' command to
+display this list. U-Boot uses the list to work out where to relocate
+itself.
+
+Although U-Boot can use any memory it likes, EFI marks some memory as used
+by 'run-time services', code that hangs around while U-Boot is running and
+is even present when Linux is running. This is common on x86 and provides
+a way for Linux to call back into the firmware to control things like CPU
+fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It
+will relocate itself to the top of the largest block of memory it can find
+below 4GB.
+
+Interrupts
+~~~~~~~~~~
+U-Boot drivers typically don't use interrupts. Since EFI enables interrupts
+it is possible that an interrupt will fire that U-Boot cannot handle. This
+seems to cause problems. For this reason the U-Boot payload runs with
+interrupts disabled at present.
+
+32/64-bit
+~~~~~~~~~
+While the EFI application can in principle be built as either 32- or 64-bit,
+only 32-bit is currently supported. This means that the application can only
+be used with 32-bit EFI.
+
+The payload stub can be build as either 32- or 64-bits. Only a small amount
+of code is built this way (see the extra- line in lib/efi/Makefile).
+Everything else is built as a normal U-Boot, so is always 32-bit on x86 at
+present.
+
+Future work
+-----------
+This work could be extended in a number of ways:
+
+- Add ARM support
+
+- Add 64-bit application support
+
+- Figure out how to solve the interrupt problem
+
+- Add more drivers to the application side (e.g. video, block devices, USB,
+ environment access). This would mostly be an academic exercise as a strong
+ use case is not readily apparent, but it might be fun.
+
+- Avoid turning off boot services in the stub. Instead allow U-Boot to make
+ use of boot services in case it wants to. It is unclear what it might want
+ though.
+
+Where is the code?
+------------------
+lib/efi
+ payload stub, application, support code. Mostly arch-neutral
+
+arch/x86/cpu/efi
+ x86 support code for running as an EFI application and payload
+
+board/efi/efi-x86_app/efi.c
+ x86 board code for running as an EFI application
+
+board/efi/efi-x86_payload
+ generic x86 EFI payload board support code
+
+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/
diff --git a/doc/uefi/uefi.rst b/doc/uefi/uefi.rst
new file mode 100644
index 0000000000..476117bfc5
--- /dev/null
+++ b/doc/uefi/uefi.rst
@@ -0,0 +1,334 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2018 Heinrich Schuchardt
+
+UEFI on U-Boot
+==============
+
+The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
+the default for booting on AArch64 and x86 systems. It provides a stable API for
+the interaction of drivers and applications with the firmware. The API comprises
+access to block storage, network, and console to name a few. The Linux kernel
+and boot loaders like GRUB or the FreeBSD loader can be executed.
+
+Development target
+------------------
+
+The implementation of UEFI in U-Boot strives to reach the requirements described
+in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0"
+[4]. The "Server Base Boot Requirements System Software on ARM Platforms" [5]
+describes a superset of the EBBR specification and may be used as further
+reference.
+
+A full blown UEFI implementation would contradict the U-Boot design principle
+"keep it small".
+
+Building U-Boot for UEFI
+------------------------
+
+The UEFI standard supports only little-endian systems. The UEFI support can be
+activated for ARM and x86 by specifying::
+
+ CONFIG_CMD_BOOTEFI=y
+ CONFIG_EFI_LOADER=y
+
+in the .config file.
+
+Support for attaching virtual block devices, e.g. iSCSI drives connected by the
+loaded UEFI application [3], requires::
+
+ CONFIG_BLK=y
+ CONFIG_PARTITIONS=y
+
+Executing a UEFI binary
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The bootefi command is used to start UEFI applications or to install UEFI
+drivers. It takes two parameters::
+
+ bootefi <image address> [fdt address]
+
+* image address - the memory address of the UEFI binary
+* fdt address - the memory address of the flattened device tree
+
+Below you find the output of an example session starting GRUB::
+
+ => load mmc 0:2 ${fdt_addr_r} boot/dtb
+ 29830 bytes read in 14 ms (2 MiB/s)
+ => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
+ reading efi/debian/grubaa64.efi
+ 120832 bytes read in 7 ms (16.5 MiB/s)
+ => bootefi ${kernel_addr_r} ${fdt_addr_r}
+
+The environment variable 'bootargs' is passed as load options in the UEFI system
+table. The Linux kernel EFI stub uses the load options as command line
+arguments.
+
+Executing the boot manager
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The UEFI specification foresees to define boot entries and boot sequence via UEFI
+variables. Booting according to these variables is possible via::
+
+ bootefi bootmgr [fdt address]
+
+As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at
+runtime.
+
+Executing the built in hello world application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A hello world UEFI application can be built with::
+
+ CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
+
+It can be embedded into the U-Boot binary with::
+
+ CONFIG_CMD_BOOTEFI_HELLO=y
+
+The bootefi command is used to start the embedded hello world application::
+
+ bootefi hello [fdt address]
+
+Below you find the output of an example session::
+
+ => bootefi hello ${fdtcontroladdr}
+ ## Starting EFI application at 01000000 ...
+ WARNING: using memory device/image path, this may confuse some payloads!
+ Hello, world!
+ Running on UEFI 2.7
+ Have SMBIOS table
+ Have device tree
+ Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
+ ## Application terminated, r = 0
+
+The environment variable fdtcontroladdr points to U-Boot's internal device tree
+(if available).
+
+Executing the built-in self-test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An UEFI self-test suite can be embedded in U-Boot by building with::
+
+ CONFIG_CMD_BOOTEFI_SELFTEST=y
+
+For testing the UEFI implementation the bootefi command can be used to start the
+self-test::
+
+ bootefi selftest [fdt address]
+
+The environment variable 'efi_selftest' can be used to select a single test. If
+it is not provided all tests are executed except those marked as 'on request'.
+If the environment variable is set to 'list' a list of all tests is shown.
+
+Below you can find the output of an example session::
+
+ => setenv efi_selftest simple network protocol
+ => bootefi selftest
+ Testing EFI API implementation
+ Selected test: 'simple network protocol'
+ Setting up 'simple network protocol'
+ Setting up 'simple network protocol' succeeded
+ Executing 'simple network protocol'
+ DHCP Discover
+ DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02)
+ as broadcast message.
+ Executing 'simple network protocol' succeeded
+ Tearing down 'simple network protocol'
+ Tearing down 'simple network protocol' succeeded
+ Boot services terminated
+ Summary: 0 failures
+ Preparing for reset. Press any key.
+
+The UEFI life cycle
+-------------------
+
+After the U-Boot platform has been initialized the UEFI API provides two kinds
+of services
+
+* boot services and
+* runtime services.
+
+The API can be extended by loading UEFI drivers which come in two variants
+
+* boot drivers and
+* runtime drivers.
+
+UEFI drivers are installed with U-Boot's bootefi command. With the same command
+UEFI applications can be executed.
+
+Loaded images of UEFI drivers stay in memory after returning to U-Boot while
+loaded images of applications are removed from memory.
+
+An UEFI application (e.g. an operating system) that wants to take full control
+of the system calls ExitBootServices. After a UEFI application calls
+ExitBootServices
+
+* boot services are not available anymore
+* timer events are stopped
+* the memory used by U-Boot except for runtime services is released
+* the memory used by boot time drivers is released
+
+So this is a point of no return. Afterwards the UEFI application can only return
+to U-Boot by rebooting.
+
+The UEFI object model
+---------------------
+
+UEFI offers a flexible and expandable object model. The objects in the UEFI API
+are devices, drivers, and loaded images. These objects are referenced by
+handles.
+
+The interfaces implemented by the objects are referred to as protocols. These
+are identified by GUIDs. They can be installed and uninstalled by calling the
+appropriate boot services.
+
+Handles are created by the InstallProtocolInterface or the
+InstallMultipleProtocolinterfaces service if NULL is passed as handle.
+
+Handles are deleted when the last protocol has been removed with the
+UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service.
+
+Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation
+of device nodes. By their device paths all devices of a system are arranged in a
+tree.
+
+Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect
+a driver to devices (which are referenced as controllers in this context).
+
+Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta
+information about the image and a pointer to the unload callback function.
+
+The UEFI events
+---------------
+
+In the UEFI terminology an event is a data object referencing a notification
+function which is queued for calling when the event is signaled. The following
+types of events exist:
+
+* periodic and single shot timer events
+* exit boot services events, triggered by calling the ExitBootServices() service
+* virtual address change events
+* memory map change events
+* read to boot events
+* reset system events
+* system table events
+* events that are only triggered programmatically
+
+Events can be created with the CreateEvent service and deleted with CloseEvent
+service.
+
+Events can be assigned to an event group. If any of the events in a group is
+signaled, all other events in the group are also set to the signaled state.
+
+The UEFI driver model
+---------------------
+
+A driver is specific for a single protocol installed on a device. To install a
+driver on a device the ConnectController service is called. In this context
+controller refers to the device for which the driver is installed.
+
+The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This
+protocol has has three functions:
+
+* supported - determines if the driver is compatible with the device
+* start - installs the driver by opening the relevant protocol with
+ attribute EFI_OPEN_PROTOCOL_BY_DRIVER
+* stop - uninstalls the driver
+
+The driver may create child controllers (child devices). E.g. a driver for block
+IO devices will create the device handles for the partitions. The child
+controllers will open the supported protocol with the attribute
+EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
+
+A driver can be detached from a device using the DisconnectController service.
+
+U-Boot devices mapped as UEFI devices
+-------------------------------------
+
+Some of the U-Boot devices are mapped as UEFI devices
+
+* block IO devices
+* console
+* graphical output
+* network adapter
+
+As of U-Boot 2018.03 the logic for doing this is hard coded.
+
+The development target is to integrate the setup of these UEFI devices with the
+U-Boot driver model. So when a U-Boot device is discovered a handle should be
+created and the device path protocol and the relevant IO protocol should be
+installed. The UEFI driver then would be attached by calling ConnectController.
+When a U-Boot device is removed DisconnectController should be called.
+
+UEFI devices mapped as U-Boot devices
+-------------------------------------
+
+UEFI drivers binaries and applications may create new (virtual) devices, install
+a protocol and call the ConnectController service. Now the matching UEFI driver
+is determined by iterating over the implementations of the
+EFI_DRIVER_BINDING_PROTOCOL.
+
+It is the task of the UEFI driver to create a corresponding U-Boot device and to
+proxy calls for this U-Boot device to the controller.
+
+In U-Boot 2018.03 this has only been implemented for block IO devices.
+
+UEFI uclass
+~~~~~~~~~~~
+
+An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
+takes care of initializing the UEFI drivers and providing the
+EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers.
+
+A linker created list is used to keep track of the UEFI drivers. To create an
+entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying
+UCLASS_EFI as the ID of its uclass, e.g::
+
+ /* Identify as UEFI driver */
+ U_BOOT_DRIVER(efi_block) = {
+ .name = "EFI block driver",
+ .id = UCLASS_EFI,
+ .ops = &driver_ops,
+ };
+
+The available operations are defined via the structure struct efi_driver_ops::
+
+ struct efi_driver_ops {
+ const efi_guid_t *protocol;
+ const efi_guid_t *child_protocol;
+ int (*bind)(efi_handle_t handle, void *interface);
+ };
+
+When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the
+uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver.
+In the start() function the bind() function of the UEFI driver is called after
+checking the GUID.
+The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child
+controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03
+this is not yet completely implemented.)
+
+UEFI block IO driver
+~~~~~~~~~~~~~~~~~~~~
+
+The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL.
+
+When connected it creates a new U-Boot block IO device with interface type
+IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the
+EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the
+software iPXE to boot from iSCSI network drives [3].
+
+This driver is only available if U-Boot is configured with
+
+ CONFIG_BLK=y
+ CONFIG_PARTITIONS=y
+
+Links
+-----
+
+* [1] http://uefi.org/specifications - UEFI specifications
+* [2] :doc:`../driver-model/index`
+* [3] :doc:`iscsi`
+* [4] https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf -
+ Embedded Base Boot Requirements (EBBR) Specification - Release v1.0
+* [5] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 -
+ Server Base Boot Requirements System Software on ARM Platforms - Version 1.1
--
2.20.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* [U-Boot] [PATCH 1/1] doc: integrate UEFI documentation into Sphinx toctree
2019-07-26 4:56 [U-Boot] [PATCH 1/1] doc: integrate UEFI documentation into Sphinx toctree Heinrich Schuchardt
@ 2019-07-26 6:36 ` Bin Meng
0 siblings, 0 replies; 2+ messages in thread
From: Bin Meng @ 2019-07-26 6:36 UTC (permalink / raw)
To: u-boot
Hi Heinrich,
On Fri, Jul 26, 2019 at 12:56 PM Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> Change the UEFI documentation to Sphinx style and integrate it into the
> rest of the Sphinx generated documentation.
>
> Remove the inaccurate TODO list in doc/uefi/uefi.rst.
>
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> ---
> MAINTAINERS | 4 +-
> doc/README.iscsi | 170 ------------------
> doc/README.u-boot_on_efi | 252 --------------------------
> doc/README.uefi | 352 -------------------------------------
> doc/index.rst | 13 ++
> doc/uefi/index.rst | 11 ++
> doc/uefi/iscsi.rst | 180 +++++++++++++++++++
> doc/uefi/u-boot_on_efi.rst | 235 +++++++++++++++++++++++++
> doc/uefi/uefi.rst | 334 +++++++++++++++++++++++++++++++++++
> 9 files changed, 774 insertions(+), 777 deletions(-)
> delete mode 100644 doc/README.iscsi
> delete mode 100644 doc/README.u-boot_on_efi
> delete mode 100644 doc/README.uefi
> create mode 100644 doc/uefi/index.rst
> create mode 100644 doc/uefi/iscsi.rst
> create mode 100644 doc/uefi/u-boot_on_efi.rst
> create mode 100644 doc/uefi/uefi.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a72ccd0b58..12ad127adc 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -477,9 +477,7 @@ M: Heinrich Schuchardt <xypron.glpk@gmx.de>
> R: Alexander Graf <agraf@csgraf.de>
> S: Maintained
> T: git https://gitlab.denx.de/u-boot/custodians/u-boot-efi.git
> -F: doc/README.uefi
> -F: doc/README.iscsi
> -F: doc/efi.rst
> +F: doc/uefi/*
> F: include/capitalization.h
> F: include/charset.h
> F: include/cp1250.h
> diff --git a/doc/README.iscsi b/doc/README.iscsi
> deleted file mode 100644
> index 3a12438f90..0000000000
> --- a/doc/README.iscsi
> +++ /dev/null
> @@ -1,170 +0,0 @@
> -# iSCSI booting with U-Boot and iPXE
> -
> -## Motivation
> -
> -U-Boot has only a reduced set of supported network protocols. The focus for
> -network booting has been on UDP based protocols. A TCP stack and HTTP support
> -are expected to be integrated in 2018 together with a wget command.
> -
> -For booting a diskless computer this leaves us with BOOTP or DHCP to get the
> -address of a boot script. TFTP or NFS can be used to load the boot script, the
> -operating system kernel and the initial file system (initrd).
> -
> -These protocols are insecure. The client cannot validate the authenticity
> -of the contacted servers. And the server cannot verify the identity of the
> -client.
> -
> -Furthermore the services providing the operating system loader or kernel are
> -not the ones that the operating system typically will use. Especially in a SAN
> -environment this makes updating the operating system a hassle. After installing
> -a new kernel version the boot files have to be copied to the TFTP server
> -directory.
> -
> -The HTTPS protocol provides certificate based validation of servers. Sensitive
> -data like passwords can be securely transmitted.
> -
> -The iSCSI protocol is used for connecting storage attached networks. It
> -provides mutual authentication using the CHAP protocol. It typically runs on
> -a TCP transport.
> -
> -Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script
> -via HTTPS and to download any other files needed for booting via iSCSI from the
> -same target where the operating system is installed.
> -
> -An alternative to implementing these protocols in U-Boot is to use an existing
> -software that can run on top of U-Boot. iPXE[1] is the "swiss army knife" of
> -network booting. It supports both HTTPS and iSCSI. It has a scripting engine for
> -fine grained control of the boot process and can provide a command shell.
> -
> -iPXE can be built as an EFI application (named snp.efi) which can be loaded and
> -run by U-Boot.
> -
> -## Boot sequence
> -
> -U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This
> -application has network access via the simple network protocol offered by
> -U-Boot.
> -
> -iPXE executes its internal script. This script may optionally chain load a
> -secondary boot script via HTTPS or open a shell.
> -
> -For the further boot process iPXE connects to the iSCSI server. This includes
> -the mutual authentication using the CHAP protocol. After the authentication iPXE
> -has access to the iSCSI targets.
> -
> -For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It
> -uses the ConnectController boot service of U-Boot to request U-Boot to connect a
> -file system driver. U-Boot reads from the iSCSI drive via the block IO protocol
> -offered by iPXE. It creates the partition handles and installs the simple file
> -protocol. Now iPXE can call the simple file protocol to load GRUB[2]. U-Boot
> -uses the block IO protocol offered by iPXE to fulfill the request.
> -
> -Once GRUB is started it uses the same block IO protocol to load Linux. Via
> -the EFI stub Linux is called as an EFI application::
> -
> - +--------+ +--------+
> - | | Runs | |
> - | U-Boot |========>| iPXE |
> - | EFI | | snp.efi|
> - +--------+ | | DHCP | |
> - | |<===|********|<========| |
> - | DHCP | | | Get IP | |
> - | Server | | | Address | |
> - | |===>|********|========>| |
> - +--------+ | | Response| |
> - | | | |
> - | | | |
> - +--------+ | | HTTPS | |
> - | |<===|********|<========| |
> - | HTTPS | | | Load | |
> - | Server | | | Script | |
> - | |===>|********|========>| |
> - +--------+ | | | |
> - | | | |
> - | | | |
> - +--------+ | | iSCSI | |
> - | |<===|********|<========| |
> - | iSCSI | | | Auth | |
> - | Server |===>|********|========>| |
> - | | | | | |
> - | | | | Loads | |
> - | |<===|********|<========| | +--------+
> - | | | | GRUB | | Runs | |
> - | |===>|********|========>| |======>| GRUB |
> - | | | | | | | |
> - | | | | | | | |
> - | | | | | | Loads | |
> - | |<===|********|<========|********|<======| | +--------+
> - | | | | | | Linux | | Runs | |
> - | |===>|********|========>|********|======>| |=====>| Linux |
> - | | | | | | | | | |
> - +--------+ +--------+ +--------+ +--------+ | |
> - | |
> - | |
> - | ~ ~ ~ ~|
> -
> -## Security
> -
> -The iSCSI protocol is not encrypted. The traffic could be secured using IPsec
> -but neither U-Boot nor iPXE does support this. So we should at least separate
> -the iSCSI traffic from all other network traffic. This can be achieved using a
> -virtual local area network (VLAN).
> -
> -## Configuration
> -
> -### iPXE
> -
> -For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed::
> -
> - git clone http://git.ipxe.org/ipxe.git
> - cd ipxe/src
> - make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe
> -
> -The available commands for the boot script are documented at:
> -
> -http://ipxe.org/cmd
> -
> -Credentials are managed as environment variables. These are described here:
> -
> -http://ipxe.org/cfg
> -
> -iPXE by default will put the CPU to rest when waiting for input. U-Boot does
> -not wake it up due to missing interrupt support. To avoid this behavior create
> -file src/config/local/nap.h::
> -
> - /* nap.h */
> - #undef NAP_EFIX86
> - #undef NAP_EFIARM
> - #define NAP_NULL
> -
> -The supported commands in iPXE are controlled by an include, too. Putting the
> -following into src/config/local/general.h is sufficient for most use cases::
> -
> - /* general.h */
> - #define NSLOOKUP_CMD /* Name resolution command */
> - #define PING_CMD /* Ping command */
> - #define NTP_CMD /* NTP commands */
> - #define VLAN_CMD /* VLAN commands */
> - #define IMAGE_EFI /* EFI image support */
> - #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */
> - #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */
> - #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */
> - #define DOWNLOAD_PROTO_FILE /* Local file system access */
> -
> -### Open-iSCSI
> -
> -When the root file system is on an iSCSI drive you should disable pings and set
> -the replacement timer to a high value [3]:
> -
> - node.conn[0].timeo.noop_out_interval = 0
> - node.conn[0].timeo.noop_out_timeout = 0
> - node.session.timeo.replacement_timeout = 86400
> -
> -## Links
> -
> -* [1](https://ipxe.org) https://ipxe.org - iPXE open source boot firmware
> -* [2](https://www.gnu.org/software/grub/) https://www.gnu.org/software/grub/ -
> - GNU GRUB (Grand Unified Bootloader)
> -* [3](https://github.com/open-iscsi/open-iscsi/blob/master/README)
> - https://github.com/open-iscsi/open-iscsi/blob/master/README -
> - Open-iSCSI README
> diff --git a/doc/README.u-boot_on_efi b/doc/README.u-boot_on_efi
> deleted file mode 100644
> index e12dd4e3e6..0000000000
> --- a/doc/README.u-boot_on_efi
> +++ /dev/null
> @@ -1,252 +0,0 @@
> -# SPDX-License-Identifier: GPL-2.0+
> -#
> -# Copyright (C) 2015 Google, Inc
> -
> -U-Boot on EFI
> -=============
> -This document provides information about U-Boot running on top of EFI, either
> -as an application or just as a means of getting U-Boot onto a new platform.
> -
> -
> -=========== Table of Contents ===========
> -
> -Motivation
> -Status
> -Build Instructions
> -Trying it out
> -Inner workings
> -EFI Application
> -EFI Payload
> -Tables
> -Interrupts
> -32/64-bit
> -Future work
> -Where is the code?
> -
> -
> -Motivation
> -----------
> -Running U-Boot on EFI is useful in several situations:
> -
> -- You have EFI running on a board but U-Boot does not natively support it
> -fully yet. You can boot into U-Boot from EFI and use that until U-Boot is
> -fully ported
> -
> -- You need to use an EFI implementation (e.g. UEFI) because your vendor
> -requires it in order to provide support
> -
> -- You plan to use coreboot to boot into U-Boot but coreboot support does
> -not currently exist for your platform. In the meantime you can use U-Boot
> -on EFI and then move to U-Boot on coreboot when ready
> -
> -- You use EFI but want to experiment with a simpler alternative like U-Boot
> -
> -
> -Status
> -------
> -Only x86 is supported at present. If you are using EFI on another architecture
> -you may want to reconsider. However, much of the code is generic so could be
> -ported.
> -
> -U-Boot supports running as an EFI application for 32-bit EFI only. This is
> -not very useful since only a serial port is provided. You can look around at
> -memory and type 'help' but that is about it.
> -
> -More usefully, U-Boot supports building itself as a payload for either 32-bit
> -or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once
> -started, U-Boot changes to 32-bit mode (currently) and takes over the
> -machine. You can use devices, boot a kernel, etc.
> -
> -
> -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. 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_app config (efi-x86_app_defconfig) is set up
> -for this. Just build U-Boot as normal, e.g.
> -
> - make efi-x86_app_defconfig
> - make
> -
> -To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable
> -CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or
> -CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig
> -and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as
> -normal, e.g.
> -
> - make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig)
> - make
> -
> -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. 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
> - qemu-system-x86_64 -bios bios.bin -hda fat:/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'. 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:
> -
> - fs0:u-boot-payload.efi
> -
> -(or fs0:u-boot-app.efi for the application)
> -
> -This will start the payload, copy U-Boot into RAM and start U-Boot. Note
> -that EFI does not support booting a 64-bit application from a 32-bit
> -EFI (or vice versa). Also it will often fail to print an error message if
> -you get this wrong.
> -
> -
> -Inner workings
> -==============
> -Here follow a few implementation notes for those who want to fiddle with
> -this and perhaps contribute patches.
> -
> -The application and payload approaches sound similar but are in fact
> -implemented completely differently.
> -
> -EFI Application
> ----------------
> -For the application the whole of U-Boot is built as a shared library. The
> -efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI
> -functions with efi_init(), sets up U-Boot global_data, allocates memory for
> -U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f()
> -and board_init_r()).
> -
> -Since U-Boot limits its memory access to the allocated regions very little
> -special code is needed. The CONFIG_EFI_APP option controls a few things
> -that need to change so 'git grep CONFIG_EFI_APP' may be instructive.
> -The CONFIG_EFI option controls more general EFI adjustments.
> -
> -The only available driver is the serial driver. This calls back into EFI
> -'boot services' to send and receive characters. Although it is implemented
> -as a serial driver the console device is not necessarilly serial. If you
> -boot EFI with video output then the 'serial' device will operate on your
> -target devices's display instead and the device's USB keyboard will also
> -work if connected. If you have both serial and video output, then both
> -consoles will be active. Even though U-Boot does the same thing normally,
> -These are features of EFI, not U-Boot.
> -
> -Very little code is involved in implementing the EFI application feature.
> -U-Boot is highly portable. Most of the difficulty is in modifying the
> -Makefile settings to pass the right build flags. In particular there is very
> -little x86-specific code involved - you can find most of it in
> -arch/x86/cpu. Porting to ARM (which can also use EFI if you are brave
> -enough) should be straightforward.
> -
> -Use the 'reset' command to get back to EFI.
> -
> -EFI Payload
> ------------
> -The payload approach is a different kettle of fish. It works by building
> -U-Boot exactly as normal for your target board, then adding the entire
> -image (including device tree) into a small EFI stub application responsible
> -for booting it. The stub application is built as a normal EFI application
> -except that it has a lot of data attached to it.
> -
> -The stub application is implemented in lib/efi/efi_stub.c. The efi_main()
> -function is called by EFI. It is responsible for copying U-Boot from its
> -original location into memory, disabling EFI boot services and starting
> -U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc.
> -
> -The stub application is architecture-dependent. At present it has some
> -x86-specific code and a comment at the top of efi_stub.c describes this.
> -
> -While the stub application does allocate some memory from EFI this is not
> -used by U-Boot (the payload). In fact when U-Boot starts it has all of the
> -memory available to it and can operate as it pleases (but see the next
> -section).
> -
> -Tables
> -------
> -The payload can pass information to U-Boot in the form of EFI tables. At
> -present this feature is used to pass the EFI memory map, an inordinately
> -large list of memory regions. You can use the 'efi mem all' command to
> -display this list. U-Boot uses the list to work out where to relocate
> -itself.
> -
> -Although U-Boot can use any memory it likes, EFI marks some memory as used
> -by 'run-time services', code that hangs around while U-Boot is running and
> -is even present when Linux is running. This is common on x86 and provides
> -a way for Linux to call back into the firmware to control things like CPU
> -fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It
> -will relocate itself to the top of the largest block of memory it can find
> -below 4GB.
> -
> -Interrupts
> -----------
> -U-Boot drivers typically don't use interrupts. Since EFI enables interrupts
> -it is possible that an interrupt will fire that U-Boot cannot handle. This
> -seems to cause problems. For this reason the U-Boot payload runs with
> -interrupts disabled at present.
> -
> -32/64-bit
> ----------
> -While the EFI application can in principle be built as either 32- or 64-bit,
> -only 32-bit is currently supported. This means that the application can only
> -be used with 32-bit EFI.
> -
> -The payload stub can be build as either 32- or 64-bits. Only a small amount
> -of code is built this way (see the extra- line in lib/efi/Makefile).
> -Everything else is built as a normal U-Boot, so is always 32-bit on x86 at
> -present.
> -
> -Future work
> ------------
> -This work could be extended in a number of ways:
> -
> -- Add ARM support
> -
> -- Add 64-bit application support
> -
> -- Figure out how to solve the interrupt problem
> -
> -- Add more drivers to the application side (e.g. video, block devices, USB,
> -environment access). This would mostly be an academic exercise as a strong
> -use case is not readily apparent, but it might be fun.
> -
> -- Avoid turning off boot services in the stub. Instead allow U-Boot to make
> -use of boot services in case it wants to. It is unclear what it might want
> -though.
> -
> -Where is the code?
> -------------------
> -lib/efi
> - payload stub, application, support code. Mostly arch-neutral
> -
> -arch/x86/cpu/efi
> - x86 support code for running as an EFI application and payload
> -
> -board/efi/efi-x86_app/efi.c
> - x86 board code for running as an EFI application
> -
> -board/efi/efi-x86_payload
> - generic x86 EFI payload board support code
> -
> -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/
> diff --git a/doc/README.uefi b/doc/README.uefi
> deleted file mode 100644
> index 1d1039a6ae..0000000000
> --- a/doc/README.uefi
> +++ /dev/null
> @@ -1,352 +0,0 @@
> -<!--
> -SPDX-License-Identifier: GPL-2.0+
> -
> -Copyright (c) 2018 Heinrich Schuchardt
> --->
> -
> -# UEFI on U-Boot
> -
> -The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
> -the default for booting on AArch64 and x86 systems. It provides a stable API for
> -the interaction of drivers and applications with the firmware. The API comprises
> -access to block storage, network, and console to name a few. The Linux kernel
> -and boot loaders like GRUB or the FreeBSD loader can be executed.
> -
> -## Development target
> -
> -The implementation of UEFI in U-Boot strives to reach the requirements described
> -in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0"
> -[4]. The "Server Base Boot Requirements System Software on ARM Platforms" [5]
> -describes a superset of the EBBR specification and may be used as further
> -reference.
> -
> -A full blown UEFI implementation would contradict the U-Boot design principle
> -"keep it small".
> -
> -## Building for UEFI
> -
> -The UEFI standard supports only little-endian systems. The UEFI support can be
> -activated for ARM and x86 by specifying
> -
> - CONFIG_CMD_BOOTEFI=y
> - CONFIG_EFI_LOADER=y
> -
> -in the .config file.
> -
> -Support for attaching virtual block devices, e.g. iSCSI drives connected by the
> -loaded UEFI application [3], requires
> -
> - CONFIG_BLK=y
> - CONFIG_PARTITIONS=y
> -
> -### Executing a UEFI binary
> -
> -The bootefi command is used to start UEFI applications or to install UEFI
> -drivers. It takes two parameters
> -
> - bootefi <image address> [fdt address]
> -
> -* image address - the memory address of the UEFI binary
> -* fdt address - the memory address of the flattened device tree
> -
> -Below you find the output of an example session starting GRUB.
> -
> - => load mmc 0:2 ${fdt_addr_r} boot/dtb
> - 29830 bytes read in 14 ms (2 MiB/s)
> - => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
> - reading efi/debian/grubaa64.efi
> - 120832 bytes read in 7 ms (16.5 MiB/s)
> - => bootefi ${kernel_addr_r} ${fdt_addr_r}
> -
> -The environment variable 'bootargs' is passed as load options in the UEFI system
> -table. The Linux kernel EFI stub uses the load options as command line
> -arguments.
> -
> -### Executing the boot manager
> -
> -The UEFI specification foresees to define boot entries and boot sequence via UEFI
> -variables. Booting according to these variables is possible via
> -
> - bootefi bootmgr [fdt address]
> -
> -As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at
> -runtime.
> -
> -### Executing the built in hello world application
> -
> -A hello world UEFI application can be built with
> -
> - CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
> -
> -It can be embedded into the U-Boot binary with
> -
> - CONFIG_CMD_BOOTEFI_HELLO=y
> -
> -The bootefi command is used to start the embedded hello world application.
> -
> - bootefi hello [fdt address]
> -
> -Below you find the output of an example session.
> -
> - => bootefi hello ${fdtcontroladdr}
> - ## Starting EFI application at 01000000 ...
> - WARNING: using memory device/image path, this may confuse some payloads!
> - Hello, world!
> - Running on UEFI 2.7
> - Have SMBIOS table
> - Have device tree
> - Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
> - ## Application terminated, r = 0
> -
> -The environment variable fdtcontroladdr points to U-Boot's internal device tree
> -(if available).
> -
> -### Executing the built-in self-test
> -
> -An UEFI self-test suite can be embedded in U-Boot by building with
> -
> - CONFIG_CMD_BOOTEFI_SELFTEST=y
> -
> -For testing the UEFI implementation the bootefi command can be used to start the
> -self-test.
> -
> - bootefi selftest [fdt address]
> -
> -The environment variable 'efi_selftest' can be used to select a single test. If
> -it is not provided all tests are executed except those marked as 'on request'.
> -If the environment variable is set to 'list' a list of all tests is shown.
> -
> -Below you can find the output of an example session.
> -
> - => setenv efi_selftest simple network protocol
> - => bootefi selftest
> - Testing EFI API implementation
> - Selected test: 'simple network protocol'
> - Setting up 'simple network protocol'
> - Setting up 'simple network protocol' succeeded
> - Executing 'simple network protocol'
> - DHCP Discover
> - DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02)
> - as broadcast message.
> - Executing 'simple network protocol' succeeded
> - Tearing down 'simple network protocol'
> - Tearing down 'simple network protocol' succeeded
> - Boot services terminated
> - Summary: 0 failures
> - Preparing for reset. Press any key.
> -
> -## The UEFI life cycle
> -
> -After the U-Boot platform has been initialized the UEFI API provides two kinds
> -of services
> -
> -* boot services and
> -* runtime services.
> -
> -The API can be extended by loading UEFI drivers which come in two variants
> -
> -* boot drivers and
> -* runtime drivers.
> -
> -UEFI drivers are installed with U-Boot's bootefi command. With the same command
> -UEFI applications can be executed.
> -
> -Loaded images of UEFI drivers stay in memory after returning to U-Boot while
> -loaded images of applications are removed from memory.
> -
> -An UEFI application (e.g. an operating system) that wants to take full control
> -of the system calls ExitBootServices. After a UEFI application calls
> -ExitBootServices
> -
> -* boot services are not available anymore
> -* timer events are stopped
> -* the memory used by U-Boot except for runtime services is released
> -* the memory used by boot time drivers is released
> -
> -So this is a point of no return. Afterwards the UEFI application can only return
> -to U-Boot by rebooting.
> -
> -## The UEFI object model
> -
> -UEFI offers a flexible and expandable object model. The objects in the UEFI API
> -are devices, drivers, and loaded images. These objects are referenced by
> -handles.
> -
> -The interfaces implemented by the objects are referred to as protocols. These
> -are identified by GUIDs. They can be installed and uninstalled by calling the
> -appropriate boot services.
> -
> -Handles are created by the InstallProtocolInterface or the
> -InstallMultipleProtocolinterfaces service if NULL is passed as handle.
> -
> -Handles are deleted when the last protocol has been removed with the
> -UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service.
> -
> -Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation
> -of device nodes. By their device paths all devices of a system are arranged in a
> -tree.
> -
> -Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect
> -a driver to devices (which are referenced as controllers in this context).
> -
> -Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta
> -information about the image and a pointer to the unload callback function.
> -
> -## The UEFI events
> -
> -In the UEFI terminology an event is a data object referencing a notification
> -function which is queued for calling when the event is signaled. The following
> -types of events exist:
> -
> -* periodic and single shot timer events
> -* exit boot services events, triggered by calling the ExitBootServices() service
> -* virtual address change events
> -* memory map change events
> -* read to boot events
> -* reset system events
> -* system table events
> -* events that are only triggered programmatically
> -
> -Events can be created with the CreateEvent service and deleted with CloseEvent
> -service.
> -
> -Events can be assigned to an event group. If any of the events in a group is
> -signaled, all other events in the group are also set to the signaled state.
> -
> -## The UEFI driver model
> -
> -A driver is specific for a single protocol installed on a device. To install a
> -driver on a device the ConnectController service is called. In this context
> -controller refers to the device for which the driver is installed.
> -
> -The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This
> -protocol has has three functions:
> -
> -* supported - determines if the driver is compatible with the device
> -* start - installs the driver by opening the relevant protocol with
> - attribute EFI_OPEN_PROTOCOL_BY_DRIVER
> -* stop - uninstalls the driver
> -
> -The driver may create child controllers (child devices). E.g. a driver for block
> -IO devices will create the device handles for the partitions. The child
> -controllers will open the supported protocol with the attribute
> -EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
> -
> -A driver can be detached from a device using the DisconnectController service.
> -
> -## U-Boot devices mapped as UEFI devices
> -
> -Some of the U-Boot devices are mapped as UEFI devices
> -
> -* block IO devices
> -* console
> -* graphical output
> -* network adapter
> -
> -As of U-Boot 2018.03 the logic for doing this is hard coded.
> -
> -The development target is to integrate the setup of these UEFI devices with the
> -U-Boot driver model. So when a U-Boot device is discovered a handle should be
> -created and the device path protocol and the relevant IO protocol should be
> -installed. The UEFI driver then would be attached by calling ConnectController.
> -When a U-Boot device is removed DisconnectController should be called.
> -
> -## UEFI devices mapped as U-Boot devices
> -
> -UEFI drivers binaries and applications may create new (virtual) devices, install
> -a protocol and call the ConnectController service. Now the matching UEFI driver
> -is determined by iterating over the implementations of the
> -EFI_DRIVER_BINDING_PROTOCOL.
> -
> -It is the task of the UEFI driver to create a corresponding U-Boot device and to
> -proxy calls for this U-Boot device to the controller.
> -
> -In U-Boot 2018.03 this has only been implemented for block IO devices.
> -
> -### UEFI uclass
> -
> -An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
> -takes care of initializing the UEFI drivers and providing the
> -EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers.
> -
> -A linker created list is used to keep track of the UEFI drivers. To create an
> -entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying
> -UCLASS_EFI as the ID of its uclass, e.g.
> -
> - /* Identify as UEFI driver */
> - U_BOOT_DRIVER(efi_block) = {
> - .name = "EFI block driver",
> - .id = UCLASS_EFI,
> - .ops = &driver_ops,
> - };
> -
> -The available operations are defined via the structure struct efi_driver_ops.
> -
> - struct efi_driver_ops {
> - const efi_guid_t *protocol;
> - const efi_guid_t *child_protocol;
> - int (*bind)(efi_handle_t handle, void *interface);
> - };
> -
> -When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the
> -uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver.
> -In the start() function the bind() function of the UEFI driver is called after
> -checking the GUID.
> -The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child
> -controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03
> -this is not yet completely implemented.)
> -
> -### UEFI block IO driver
> -
> -The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL.
> -
> -When connected it creates a new U-Boot block IO device with interface type
> -IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the
> -EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the
> -software iPXE to boot from iSCSI network drives [3].
> -
> -This driver is only available if U-Boot is configured with
> -
> - CONFIG_BLK=y
> - CONFIG_PARTITIONS=y
> -
> -## TODOs as of U-Boot 2019.04
> -
> -* unimplemented or incompletely implemented boot services
> - * Exit - call unload function, unload applications only
> - * ProtocolRegisterNotify
> - * UnloadImage
> -
> -* unimplemented or incompletely implemented runtime services
> - * SetVariable() ignores attribute EFI_VARIABLE_APPEND_WRITE
> - * QueryVariableInfo is not implemented
> -
> -* unimplemented events
> - * EVT_RUNTIME
> - * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
> -
> -* data model
> - * manage configuration tables in a linked list
> -
> -* UEFI drivers
> - * support DisconnectController for UEFI block devices.
> -
> -* support for CONFIG_EFI_LOADER in the sandbox (CONFIG_SANDBOX=y)
> -
> -* UEFI variables
> - * persistence
> - * runtime support
> -
> -* incompletely implemented protocols
> - * support version 0x00020000 of the EFI file protocol
> -
> -## Links
> -
> -* [1](http://uefi.org/specifications)
> - http://uefi.org/specifications - UEFI specifications
> -* [2](./driver-model/README.txt) doc/driver-model/README.txt - Driver model
> -* [3](./README.iscsi) doc/README.iscsi - iSCSI booting with U-Boot and iPXE
> -* [4](https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf)
> - Embedded Base Boot Requirements (EBBR) Specification - Release v1.0
> -* [5](https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11)
> - Server Base Boot Requirements System Software on ARM Platforms - Version 1.1
> diff --git a/doc/index.rst b/doc/index.rst
> index 9ae2e167bc..458f0d2d0e 100644
> --- a/doc/index.rst
> +++ b/doc/index.rst
> @@ -15,8 +15,21 @@ if you want to help out.
> .. toctree::
> :maxdepth: 2
>
> +Unified Extensible Firmware (UEFI)
> +----------------------------------
> +
> +U-Boot provides an implementation of the UEFI API allowing to run UEFI
> +compliant software like Linux, GRUB, and iPXE. Furthermore U-Boot itself
> +can be run an UEFI payload.
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + uefi/index
> +
> Driver-Model documentation
> --------------------------
> +
> The following holds information on the U-Boot device driver framework:
> driver-model, including the design details of itself and several driver
> subsystems.
> diff --git a/doc/uefi/index.rst b/doc/uefi/index.rst
> new file mode 100644
> index 0000000000..b790a91f17
> --- /dev/null
> +++ b/doc/uefi/index.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Unified Extensible Firmware (UEFI)
> +==================================
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + uefi.rst
> + u-boot_on_efi.rst
> + iscsi.rst
> diff --git a/doc/uefi/iscsi.rst b/doc/uefi/iscsi.rst
> new file mode 100644
> index 0000000000..aa844a7cc3
> --- /dev/null
> +++ b/doc/uefi/iscsi.rst
> @@ -0,0 +1,180 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (c) 2018 Heinrich Schuchardt
> +
> +iSCSI booting with U-Boot and iPXE
> +==================================
> +
> +Motivation
> +----------
> +
> +U-Boot has only a reduced set of supported network protocols. The focus for
> +network booting has been on UDP based protocols. A TCP stack and HTTP support
> +are expected to be integrated in 2018 together with a wget command.
> +
> +For booting a diskless computer this leaves us with BOOTP or DHCP to get the
> +address of a boot script. TFTP or NFS can be used to load the boot script, the
> +operating system kernel and the initial file system (initrd).
> +
> +These protocols are insecure. The client cannot validate the authenticity
> +of the contacted servers. And the server cannot verify the identity of the
> +client.
> +
> +Furthermore the services providing the operating system loader or kernel are
> +not the ones that the operating system typically will use. Especially in a SAN
> +environment this makes updating the operating system a hassle. After installing
> +a new kernel version the boot files have to be copied to the TFTP server
> +directory.
> +
> +The HTTPS protocol provides certificate based validation of servers. Sensitive
> +data like passwords can be securely transmitted.
> +
> +The iSCSI protocol is used for connecting storage attached networks. It
> +provides mutual authentication using the CHAP protocol. It typically runs on
> +a TCP transport.
> +
> +Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script
> +via HTTPS and to download any other files needed for booting via iSCSI from the
> +same target where the operating system is installed.
> +
> +An alternative to implementing these protocols in U-Boot is to use an existing
> +software that can run on top of U-Boot. iPXE[1] is the "swiss army knife" of
> +network booting. It supports both HTTPS and iSCSI. It has a scripting engine for
> +fine grained control of the boot process and can provide a command shell.
> +
> +iPXE can be built as an EFI application (named snp.efi) which can be loaded and
> +run by U-Boot.
> +
> +Boot sequence
> +-------------
> +
> +U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This
> +application has network access via the simple network protocol offered by
> +U-Boot.
> +
> +iPXE executes its internal script. This script may optionally chain load a
> +secondary boot script via HTTPS or open a shell.
> +
> +For the further boot process iPXE connects to the iSCSI server. This includes
> +the mutual authentication using the CHAP protocol. After the authentication iPXE
> +has access to the iSCSI targets.
> +
> +For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It
> +uses the ConnectController boot service of U-Boot to request U-Boot to connect a
> +file system driver. U-Boot reads from the iSCSI drive via the block IO protocol
> +offered by iPXE. It creates the partition handles and installs the simple file
> +protocol. Now iPXE can call the simple file protocol to load GRUB[2]. U-Boot
> +uses the block IO protocol offered by iPXE to fulfill the request.
> +
> +Once GRUB is started it uses the same block IO protocol to load Linux. Via
> +the EFI stub Linux is called as an EFI application::
> +
> + +--------+ +--------+
> + | | Runs | |
> + | U-Boot |========>| iPXE |
> + | EFI | | snp.efi|
> + +--------+ | | DHCP | |
> + | |<===|********|<========| |
> + | DHCP | | | Get IP | |
> + | Server | | | Address | |
> + | |===>|********|========>| |
> + +--------+ | | Response| |
> + | | | |
> + | | | |
> + +--------+ | | HTTPS | |
> + | |<===|********|<========| |
> + | HTTPS | | | Load | |
> + | Server | | | Script | |
> + | |===>|********|========>| |
> + +--------+ | | | |
> + | | | |
> + | | | |
> + +--------+ | | iSCSI | |
> + | |<===|********|<========| |
> + | iSCSI | | | Auth | |
> + | Server |===>|********|========>| |
> + | | | | | |
> + | | | | Loads | |
> + | |<===|********|<========| | +--------+
> + | | | | GRUB | | Runs | |
> + | |===>|********|========>| |======>| GRUB |
> + | | | | | | | |
> + | | | | | | | |
> + | | | | | | Loads | |
> + | |<===|********|<========|********|<======| | +--------+
> + | | | | | | Linux | | Runs | |
> + | |===>|********|========>|********|======>| |=====>| Linux |
> + | | | | | | | | | |
> + +--------+ +--------+ +--------+ +--------+ | |
> + | |
> + | |
> + | ~ ~ ~ ~|
> +
> +Security
> +--------
> +
> +The iSCSI protocol is not encrypted. The traffic could be secured using IPsec
> +but neither U-Boot nor iPXE does support this. So we should at least separate
> +the iSCSI traffic from all other network traffic. This can be achieved using a
> +virtual local area network (VLAN).
> +
> +Configuration
> +-------------
> +
> +iPXE
> +~~~~
> +
> +For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed::
> +
> + git clone http://git.ipxe.org/ipxe.git
> + cd ipxe/src
> + make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe
> +
> +The available commands for the boot script are documented at:
> +
> +http://ipxe.org/cmd
> +
> +Credentials are managed as environment variables. These are described here:
> +
> +http://ipxe.org/cfg
> +
> +iPXE by default will put the CPU to rest when waiting for input. U-Boot does
> +not wake it up due to missing interrupt support. To avoid this behavior create
> +file src/config/local/nap.h::
> +
Instead of using ::, we can use
.. code-block:: c
that can do some language specific keyword highlighting
> + /* nap.h */
> + #undef NAP_EFIX86
> + #undef NAP_EFIARM
> + #define NAP_NULL
> +
> +The supported commands in iPXE are controlled by an include, too. Putting the
> +following into src/config/local/general.h is sufficient for most use cases::
> +
ditto
> + /* general.h */
> + #define NSLOOKUP_CMD /* Name resolution command */
> + #define PING_CMD /* Ping command */
> + #define NTP_CMD /* NTP commands */
> + #define VLAN_CMD /* VLAN commands */
> + #define IMAGE_EFI /* EFI image support */
> + #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */
> + #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */
> + #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */
> + #define DOWNLOAD_PROTO_FILE /* Local file system access */
> +
> +Open-iSCSI
> +~~~~~~~~~~
> +
> +When the root file system is on an iSCSI drive you should disable pings and set
> +the replacement timer to a high value [3]:
> +
Missing .. code-block:: c
> + node.conn[0].timeo.noop_out_interval = 0
> + node.conn[0].timeo.noop_out_timeout = 0
> + node.session.timeo.replacement_timeout = 86400
> +
> +Links
> +-----
> +
> +* [1] https://ipxe.org - iPXE open source boot firmware
> +* [2] https://www.gnu.org/software/grub/ -
> + GNU GRUB (Grand Unified Bootloader)
> +* [3] https://github.com/open-iscsi/open-iscsi/blob/master/README -
> + Open-iSCSI README
> diff --git a/doc/uefi/u-boot_on_efi.rst b/doc/uefi/u-boot_on_efi.rst
> new file mode 100644
> index 0000000000..139173bc7a
> --- /dev/null
> +++ b/doc/uefi/u-boot_on_efi.rst
> @@ -0,0 +1,235 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (C) 2015 Google, Inc
> +
> +U-Boot on EFI
> +=============
> +This document provides information about U-Boot running on top of EFI, either
> +as an application or just as a means of getting U-Boot onto a new platform.
> +
> +
> +Motivation
> +----------
> +Running U-Boot on EFI is useful in several situations:
> +
> +- You have EFI running on a board but U-Boot does not natively support it
> + fully yet. You can boot into U-Boot from EFI and use that until U-Boot is
> + fully ported
> +
> +- You need to use an EFI implementation (e.g. UEFI) because your vendor
> + requires it in order to provide support
> +
> +- You plan to use coreboot to boot into U-Boot but coreboot support does
> + not currently exist for your platform. In the meantime you can use U-Boot
> + on EFI and then move to U-Boot on coreboot when ready
> +
> +- You use EFI but want to experiment with a simpler alternative like U-Boot
> +
> +
> +Status
> +------
> +Only x86 is supported at present. If you are using EFI on another architecture
> +you may want to reconsider. However, much of the code is generic so could be
> +ported.
> +
> +U-Boot supports running as an EFI application for 32-bit EFI only. This is
> +not very useful since only a serial port is provided. You can look around at
> +memory and type 'help' but that is about it.
> +
> +More usefully, U-Boot supports building itself as a payload for either 32-bit
> +or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once
> +started, U-Boot changes to 32-bit mode (currently) and takes over the
> +machine. You can use devices, boot a kernel, etc.
> +
> +
> +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. 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_app config (efi-x86_app_defconfig) is set up
> +for this. Just build U-Boot as normal, e.g.
> +
The above should be in preformatting blocks, by adding :: after e.g.
> + make efi-x86_app_defconfig
> + make
> +
> +To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable
> +CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or
> +CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig
> +and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as
> +normal, e.g.
> +
ditto
> + make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig)
> + make
> +
> +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
> +
The above are poorly formatted
> +
> +Trying it out
> +-------------
> +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:
> +
adding one more : to make the following pre-formatted
> + mkdir /tmp/efi
> + cp /path/to/u-boot*.efi /tmp/efi
> + qemu-system-x86_64 -bios bios.bin -hda fat:/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'. 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:
> +
ditto
> + fs0:u-boot-payload.efi
> +
> +(or fs0:u-boot-app.efi for the application)
> +
> +This will start the payload, copy U-Boot into RAM and start U-Boot. Note
> +that EFI does not support booting a 64-bit application from a 32-bit
> +EFI (or vice versa). Also it will often fail to print an error message if
> +you get this wrong.
> +
> +
> +Inner workings
> +--------------
> +Here follow a few implementation notes for those who want to fiddle with
> +this and perhaps contribute patches.
> +
> +The application and payload approaches sound similar but are in fact
> +implemented completely differently.
> +
> +EFI Application
> +~~~~~~~~~~~~~~~
> +For the application the whole of U-Boot is built as a shared library. The
> +efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI
> +functions with efi_init(), sets up U-Boot global_data, allocates memory for
> +U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f()
> +and board_init_r()).
> +
> +Since U-Boot limits its memory access to the allocated regions very little
> +special code is needed. The CONFIG_EFI_APP option controls a few things
> +that need to change so 'git grep CONFIG_EFI_APP' may be instructive.
> +The CONFIG_EFI option controls more general EFI adjustments.
> +
> +The only available driver is the serial driver. This calls back into EFI
> +'boot services' to send and receive characters. Although it is implemented
> +as a serial driver the console device is not necessarilly serial. If you
> +boot EFI with video output then the 'serial' device will operate on your
> +target devices's display instead and the device's USB keyboard will also
> +work if connected. If you have both serial and video output, then both
> +consoles will be active. Even though U-Boot does the same thing normally,
> +These are features of EFI, not U-Boot.
> +
> +Very little code is involved in implementing the EFI application feature.
> +U-Boot is highly portable. Most of the difficulty is in modifying the
> +Makefile settings to pass the right build flags. In particular there is very
> +little x86-specific code involved - you can find most of it in
> +arch/x86/cpu. Porting to ARM (which can also use EFI if you are brave
> +enough) should be straightforward.
> +
> +Use the 'reset' command to get back to EFI.
> +
> +EFI Payload
> +~~~~~~~~~~~
> +The payload approach is a different kettle of fish. It works by building
> +U-Boot exactly as normal for your target board, then adding the entire
> +image (including device tree) into a small EFI stub application responsible
> +for booting it. The stub application is built as a normal EFI application
> +except that it has a lot of data attached to it.
> +
> +The stub application is implemented in lib/efi/efi_stub.c. The efi_main()
> +function is called by EFI. It is responsible for copying U-Boot from its
> +original location into memory, disabling EFI boot services and starting
> +U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc.
> +
> +The stub application is architecture-dependent. At present it has some
> +x86-specific code and a comment at the top of efi_stub.c describes this.
> +
> +While the stub application does allocate some memory from EFI this is not
> +used by U-Boot (the payload). In fact when U-Boot starts it has all of the
> +memory available to it and can operate as it pleases (but see the next
> +section).
> +
> +Tables
> +~~~~~~
> +The payload can pass information to U-Boot in the form of EFI tables. At
> +present this feature is used to pass the EFI memory map, an inordinately
> +large list of memory regions. You can use the 'efi mem all' command to
> +display this list. U-Boot uses the list to work out where to relocate
> +itself.
> +
> +Although U-Boot can use any memory it likes, EFI marks some memory as used
> +by 'run-time services', code that hangs around while U-Boot is running and
> +is even present when Linux is running. This is common on x86 and provides
> +a way for Linux to call back into the firmware to control things like CPU
> +fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It
> +will relocate itself to the top of the largest block of memory it can find
> +below 4GB.
> +
> +Interrupts
> +~~~~~~~~~~
> +U-Boot drivers typically don't use interrupts. Since EFI enables interrupts
> +it is possible that an interrupt will fire that U-Boot cannot handle. This
> +seems to cause problems. For this reason the U-Boot payload runs with
> +interrupts disabled at present.
> +
> +32/64-bit
> +~~~~~~~~~
> +While the EFI application can in principle be built as either 32- or 64-bit,
> +only 32-bit is currently supported. This means that the application can only
> +be used with 32-bit EFI.
> +
> +The payload stub can be build as either 32- or 64-bits. Only a small amount
> +of code is built this way (see the extra- line in lib/efi/Makefile).
> +Everything else is built as a normal U-Boot, so is always 32-bit on x86 at
> +present.
> +
> +Future work
> +-----------
> +This work could be extended in a number of ways:
> +
> +- Add ARM support
> +
> +- Add 64-bit application support
> +
> +- Figure out how to solve the interrupt problem
> +
> +- Add more drivers to the application side (e.g. video, block devices, USB,
> + environment access). This would mostly be an academic exercise as a strong
> + use case is not readily apparent, but it might be fun.
> +
> +- Avoid turning off boot services in the stub. Instead allow U-Boot to make
> + use of boot services in case it wants to. It is unclear what it might want
> + though.
> +
> +Where is the code?
> +------------------
> +lib/efi
> + payload stub, application, support code. Mostly arch-neutral
> +
> +arch/x86/cpu/efi
> + x86 support code for running as an EFI application and payload
> +
> +board/efi/efi-x86_app/efi.c
> + x86 board code for running as an EFI application
> +
> +board/efi/efi-x86_payload
> + generic x86 EFI payload board support code
> +
> +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/
A bullet should be added before [1] and [2]
> diff --git a/doc/uefi/uefi.rst b/doc/uefi/uefi.rst
> new file mode 100644
> index 0000000000..476117bfc5
> --- /dev/null
> +++ b/doc/uefi/uefi.rst
> @@ -0,0 +1,334 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (c) 2018 Heinrich Schuchardt
> +
> +UEFI on U-Boot
> +==============
> +
> +The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
> +the default for booting on AArch64 and x86 systems. It provides a stable API for
> +the interaction of drivers and applications with the firmware. The API comprises
> +access to block storage, network, and console to name a few. The Linux kernel
> +and boot loaders like GRUB or the FreeBSD loader can be executed.
> +
> +Development target
> +------------------
> +
> +The implementation of UEFI in U-Boot strives to reach the requirements described
> +in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0"
> +[4]. The "Server Base Boot Requirements System Software on ARM Platforms" [5]
> +describes a superset of the EBBR specification and may be used as further
> +reference.
> +
> +A full blown UEFI implementation would contradict the U-Boot design principle
> +"keep it small".
> +
> +Building U-Boot for UEFI
> +------------------------
> +
> +The UEFI standard supports only little-endian systems. The UEFI support can be
> +activated for ARM and x86 by specifying::
> +
> + CONFIG_CMD_BOOTEFI=y
> + CONFIG_EFI_LOADER=y
> +
> +in the .config file.
> +
> +Support for attaching virtual block devices, e.g. iSCSI drives connected by the
> +loaded UEFI application [3], requires::
> +
> + CONFIG_BLK=y
> + CONFIG_PARTITIONS=y
> +
> +Executing a UEFI binary
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The bootefi command is used to start UEFI applications or to install UEFI
> +drivers. It takes two parameters::
> +
> + bootefi <image address> [fdt address]
> +
> +* image address - the memory address of the UEFI binary
> +* fdt address - the memory address of the flattened device tree
> +
> +Below you find the output of an example session starting GRUB::
> +
> + => load mmc 0:2 ${fdt_addr_r} boot/dtb
> + 29830 bytes read in 14 ms (2 MiB/s)
> + => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
> + reading efi/debian/grubaa64.efi
> + 120832 bytes read in 7 ms (16.5 MiB/s)
> + => bootefi ${kernel_addr_r} ${fdt_addr_r}
> +
> +The environment variable 'bootargs' is passed as load options in the UEFI system
> +table. The Linux kernel EFI stub uses the load options as command line
> +arguments.
> +
> +Executing the boot manager
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The UEFI specification foresees to define boot entries and boot sequence via UEFI
> +variables. Booting according to these variables is possible via::
> +
> + bootefi bootmgr [fdt address]
> +
> +As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at
> +runtime.
> +
> +Executing the built in hello world application
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +A hello world UEFI application can be built with::
> +
> + CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
> +
> +It can be embedded into the U-Boot binary with::
> +
> + CONFIG_CMD_BOOTEFI_HELLO=y
> +
> +The bootefi command is used to start the embedded hello world application::
> +
> + bootefi hello [fdt address]
> +
> +Below you find the output of an example session::
> +
> + => bootefi hello ${fdtcontroladdr}
> + ## Starting EFI application at 01000000 ...
> + WARNING: using memory device/image path, this may confuse some payloads!
> + Hello, world!
> + Running on UEFI 2.7
> + Have SMBIOS table
> + Have device tree
> + Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
> + ## Application terminated, r = 0
> +
> +The environment variable fdtcontroladdr points to U-Boot's internal device tree
> +(if available).
> +
> +Executing the built-in self-test
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +An UEFI self-test suite can be embedded in U-Boot by building with::
> +
> + CONFIG_CMD_BOOTEFI_SELFTEST=y
> +
> +For testing the UEFI implementation the bootefi command can be used to start the
> +self-test::
> +
> + bootefi selftest [fdt address]
> +
> +The environment variable 'efi_selftest' can be used to select a single test. If
> +it is not provided all tests are executed except those marked as 'on request'.
> +If the environment variable is set to 'list' a list of all tests is shown.
> +
> +Below you can find the output of an example session::
> +
> + => setenv efi_selftest simple network protocol
> + => bootefi selftest
> + Testing EFI API implementation
> + Selected test: 'simple network protocol'
> + Setting up 'simple network protocol'
> + Setting up 'simple network protocol' succeeded
> + Executing 'simple network protocol'
> + DHCP Discover
> + DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02)
> + as broadcast message.
> + Executing 'simple network protocol' succeeded
> + Tearing down 'simple network protocol'
> + Tearing down 'simple network protocol' succeeded
> + Boot services terminated
> + Summary: 0 failures
> + Preparing for reset. Press any key.
> +
> +The UEFI life cycle
> +-------------------
> +
> +After the U-Boot platform has been initialized the UEFI API provides two kinds
> +of services
> +
> +* boot services and
nits: remove and
> +* runtime services.
nits: remove the ending period
> +
> +The API can be extended by loading UEFI drivers which come in two variants
> +
> +* boot drivers and
nits: remove and
> +* runtime drivers.
nits: remove the ending period
> +
> +UEFI drivers are installed with U-Boot's bootefi command. With the same command
> +UEFI applications can be executed.
> +
> +Loaded images of UEFI drivers stay in memory after returning to U-Boot while
> +loaded images of applications are removed from memory.
> +
> +An UEFI application (e.g. an operating system) that wants to take full control
> +of the system calls ExitBootServices. After a UEFI application calls
> +ExitBootServices
> +
> +* boot services are not available anymore
> +* timer events are stopped
> +* the memory used by U-Boot except for runtime services is released
> +* the memory used by boot time drivers is released
> +
> +So this is a point of no return. Afterwards the UEFI application can only return
> +to U-Boot by rebooting.
> +
> +The UEFI object model
> +---------------------
> +
> +UEFI offers a flexible and expandable object model. The objects in the UEFI API
> +are devices, drivers, and loaded images. These objects are referenced by
> +handles.
> +
> +The interfaces implemented by the objects are referred to as protocols. These
> +are identified by GUIDs. They can be installed and uninstalled by calling the
> +appropriate boot services.
> +
> +Handles are created by the InstallProtocolInterface or the
> +InstallMultipleProtocolinterfaces service if NULL is passed as handle.
> +
> +Handles are deleted when the last protocol has been removed with the
> +UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service.
> +
> +Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation
> +of device nodes. By their device paths all devices of a system are arranged in a
> +tree.
> +
> +Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect
> +a driver to devices (which are referenced as controllers in this context).
> +
> +Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta
> +information about the image and a pointer to the unload callback function.
> +
> +The UEFI events
> +---------------
> +
> +In the UEFI terminology an event is a data object referencing a notification
> +function which is queued for calling when the event is signaled. The following
> +types of events exist:
> +
> +* periodic and single shot timer events
> +* exit boot services events, triggered by calling the ExitBootServices() service
> +* virtual address change events
> +* memory map change events
> +* read to boot events
> +* reset system events
> +* system table events
> +* events that are only triggered programmatically
> +
> +Events can be created with the CreateEvent service and deleted with CloseEvent
> +service.
> +
> +Events can be assigned to an event group. If any of the events in a group is
> +signaled, all other events in the group are also set to the signaled state.
> +
> +The UEFI driver model
> +---------------------
> +
> +A driver is specific for a single protocol installed on a device. To install a
> +driver on a device the ConnectController service is called. In this context
> +controller refers to the device for which the driver is installed.
> +
> +The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This
> +protocol has has three functions:
> +
> +* supported - determines if the driver is compatible with the device
> +* start - installs the driver by opening the relevant protocol with
> + attribute EFI_OPEN_PROTOCOL_BY_DRIVER
> +* stop - uninstalls the driver
> +
> +The driver may create child controllers (child devices). E.g. a driver for block
> +IO devices will create the device handles for the partitions. The child
> +controllers will open the supported protocol with the attribute
> +EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
> +
> +A driver can be detached from a device using the DisconnectController service.
> +
> +U-Boot devices mapped as UEFI devices
> +-------------------------------------
> +
> +Some of the U-Boot devices are mapped as UEFI devices
> +
> +* block IO devices
> +* console
> +* graphical output
> +* network adapter
> +
> +As of U-Boot 2018.03 the logic for doing this is hard coded.
> +
> +The development target is to integrate the setup of these UEFI devices with the
> +U-Boot driver model. So when a U-Boot device is discovered a handle should be
> +created and the device path protocol and the relevant IO protocol should be
> +installed. The UEFI driver then would be attached by calling ConnectController.
> +When a U-Boot device is removed DisconnectController should be called.
> +
> +UEFI devices mapped as U-Boot devices
> +-------------------------------------
> +
> +UEFI drivers binaries and applications may create new (virtual) devices, install
> +a protocol and call the ConnectController service. Now the matching UEFI driver
> +is determined by iterating over the implementations of the
> +EFI_DRIVER_BINDING_PROTOCOL.
> +
> +It is the task of the UEFI driver to create a corresponding U-Boot device and to
> +proxy calls for this U-Boot device to the controller.
> +
> +In U-Boot 2018.03 this has only been implemented for block IO devices.
> +
> +UEFI uclass
> +~~~~~~~~~~~
> +
> +An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
> +takes care of initializing the UEFI drivers and providing the
> +EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers.
> +
> +A linker created list is used to keep track of the UEFI drivers. To create an
> +entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying
> +UCLASS_EFI as the ID of its uclass, e.g::
> +
> + /* Identify as UEFI driver */
> + U_BOOT_DRIVER(efi_block) = {
> + .name = "EFI block driver",
> + .id = UCLASS_EFI,
> + .ops = &driver_ops,
> + };
> +
> +The available operations are defined via the structure struct efi_driver_ops::
> +
> + struct efi_driver_ops {
> + const efi_guid_t *protocol;
> + const efi_guid_t *child_protocol;
> + int (*bind)(efi_handle_t handle, void *interface);
> + };
> +
> +When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the
> +uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver.
> +In the start() function the bind() function of the UEFI driver is called after
> +checking the GUID.
> +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child
> +controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03
> +this is not yet completely implemented.)
> +
> +UEFI block IO driver
> +~~~~~~~~~~~~~~~~~~~~
> +
> +The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL.
> +
> +When connected it creates a new U-Boot block IO device with interface type
> +IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the
> +EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the
> +software iPXE to boot from iSCSI network drives [3].
> +
> +This driver is only available if U-Boot is configured with
> +
> + CONFIG_BLK=y
> + CONFIG_PARTITIONS=y
> +
> +Links
> +-----
> +
> +* [1] http://uefi.org/specifications - UEFI specifications
> +* [2] :doc:`../driver-model/index`
Looks this is not referenced anywhere in the documentation.
> +* [3] :doc:`iscsi`
> +* [4] https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf -
> + Embedded Base Boot Requirements (EBBR) Specification - Release v1.0
> +* [5] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 -
> + Server Base Boot Requirements System Software on ARM Platforms - Version 1.1
nits: these docs are not referenced in their orders, eg: [1] [4] [5] [3]
> --
Regards,
Bin
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2019-07-26 6:36 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-26 4:56 [U-Boot] [PATCH 1/1] doc: integrate UEFI documentation into Sphinx toctree Heinrich Schuchardt
2019-07-26 6:36 ` Bin Meng
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.