[U-Boot] [PATCH v2 0/2][for v2018.03] efi_loader: provide new doc/README.efi

[U-Boot] [PATCH v2 0/2][for v2018.03] efi_loader: provide new doc/README.efi

[Heinrich Schuchardt]

Provides information about

- usage of the bootefi command
- overview of UEFI
- interaction between U-Boot and EFI drivers

---
v2
	split the patch in two: one deleteing all old lines, the other
	adding the new ones
	update README contents
---

Heinrich Schuchardt (2):
  efi_loader: delete doc/README.efi
  efi_loader: provide new doc/README.efi

 doc/README.efi | 353 +++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 295 insertions(+), 58 deletions(-)

-- 
2.14.2

[U-Boot] [PATCH v2 1/2][for v2018.03] efi_loader: delete doc/README.efi

[Heinrich Schuchardt]

Delete README.efi. It is replaced by a further patch.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
 doc/README.efi | 86 ----------------------------------------------------------
 1 file changed, 86 deletions(-)

diff --git a/doc/README.efi b/doc/README.efi
index 956f5bfa0c6..e69de29bb2d 100644
--- a/doc/README.efi
+++ b/doc/README.efi
@@ -1,86 +0,0 @@
-#
-# Copyright (C) 2015 Google, Inc
-#
-# SPDX-License-Identifier:	GPL-2.0+
-#
-
-EFI on U-Boot
-=============
-This document provides information about the implementation of the UEFI API [1]
-in U-Boot.
-
-
-=========== Table of Contents ===========
-
-Motivation
-How do I get it?
-Status
-Future work
-
-
-Motivation
-----------
-
-With this API support in place, you can run any UEFI payload (such as the Linux
-kernel, grub2 or gummiboot) on U-Boot. This dramatically simplifies boot loader
-configuration, as U-Boot based systems now look and feel (almost) the same way
-as TianoCore based systems.
-
-How do I get it?
-----------------
-
-EFI support for 32bit ARM and AArch64 is already included in U-Boot. All you
-need to do is enable
-
-  CONFIG_CMD_BOOTEFI=y
-  CONFIG_EFI_LOADER=y
-
-in your .config file and you will automatically get a bootefi command to run
-an efi application as well as snippet in the default distro boot script that
-scans for removable media efi binaries as fallback.
-
-Status
-------
-
-I am successfully able to run grub2 and Linux EFI binaries with this code on
-ARMv7 as well as AArch64 systems.
-
-When enabled, the resulting U-Boot binary only grows by ~10KB, so it's very
-light weight.
-
-All storage devices are directly accessible from the uEFI payload
-
-Removable media booting (search for /efi/boot/boota{a64,arm}.efi) is supported.
-
-Simple use cases like "Plug this SD card into my ARM device and it just
-boots into grub which boots into Linux", work very well.
-
-
-Running HelloWord.efi
----------------------
-
-You can run a simple 'hello world' EFI program in U-Boot.
-Enable the option CONFIG_CMD_BOOTEFI_HELLO.
-
-Then you can boot into U-Boot and type:
-
-   > bootefi hello
-
-The 'hello world EFI' program will then run, print a message and exit.
-
-
-Future work
------------
-
-Of course, there are still a few things one could do on top:
-
-   - Improve disk media detection (don't scan, use what information we
-have)
-   - Add EFI variable support using NVRAM
-   - Add GFX support
-   - Make EFI Shell work
-   - Network device support
-   - Support for payload exit
-   - Payload Watchdog support
-
-[1] http://uefi.org/
-- 
2.14.2

[U-Boot] [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi

[Heinrich Schuchardt]

Provides information about

- usage of the bootefi command
- overview of UEFI
- interaction between U-Boot and EFI drivers

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
 doc/README.efi | 323 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 323 insertions(+)

diff --git a/doc/README.efi b/doc/README.efi
index e69de29bb2d..92f7587a1af 100644
--- a/doc/README.efi
+++ b/doc/README.efi
@@ -0,0 +1,323 @@
+<!--
+    Copyright (c) 2018 Heinrich Schuchardt
+
+    SPDX-License-Identifier:     GPL-2.0+
+-->
+
+# EFI 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.
+
+## Building for EFI
+
+The UEFI standard supports only little endian systems. The EFI 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 EFI application [3], requires
+
+    CONFIG_BLK=y
+    CONFIG_PARTITIONS=y
+
+### Executing an EFI binary
+
+The bootefi command is used to start EFI applications or to install EFI drivers.
+It takes two parameters
+
+    bootefi <image address> [fdt address]
+
+* image address - the memory address of the EFI 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 EFI system
+table. The Linux kernel EFI stub uses the load options as command line
+arguments.
+
+### Executing the boot manager
+
+The UEFI specfication foresees to define boot entries and boot sequence via EFI
+variables. Booting according to these variables is possible via
+
+    bootefi bootmgr [fdt address]
+
+As of U-Boot v2018.03 EFI variables are not persisted and cannot be set at
+runtime.
+
+### Executing the built in hello world application
+
+A hello world EFI 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-Boots internal device tree
+(if available).
+
+### Executing the built-in selftest
+
+An EFI selftest suite can be embedded in U-Boot by building with
+
+    CONFIG_SELFTEST=y
+
+For testing the EFI implementation the bootefi command can be used to start the
+selftest.
+
+    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 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 EFI 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 EFI drivers which come in two variants
+
+* boot drivers and
+* runtime drivers.
+
+EFI drivers are installed with U-Boot's bootefi command. With the same command
+EFI applications can be executed.
+
+Loaded images of EFI drivers stay in memory after returning to U-Boot while
+loaded images of applications are removed from memory.
+
+An EFI application (e.g. an operating system) that wants to take full control
+of the system calls ExitBootServices. After an EFI 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 EFI application can only return
+to U-Boot by rebooting.
+
+## The EFI object model
+
+EFI offers a flexible and expandable object model. The objects in the EFI 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 EFI 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 (not yet implemented in U-Boot)
+* events that are only triggered programmatically
+
+Events can be created with the CreateEvent service and deleted with CloseEvent
+service.
+
+## The EFI 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 EFI devices
+
+Some of the U-Boot devices are mapped as EFI 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 EFI 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 EFI driver then would be attached by calling ConnectController.
+When a U-Boot device is removed DisconnectController should be called.
+
+## EFI devices mapped as U-Boot devices
+
+EFI drivers binaries and applications may create new (virtual) devices, install
+a protocol and call the ConnectController service. Now the matching EFI driver
+is determined by iterating over the implementations of the
+EFI_DRIVER_BINDING_PROTOCOL.
+
+It is the task of the EFI 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.
+
+### EFI uclass
+
+An EFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
+takes care of initializing the EFI drivers and providing the
+EFI_DRIVER_BINDING_PROTOCOL implementation for the EFI drivers.
+
+A linker created list is used to keep track of the EFI drivers. To create an
+entry in the list the EFI driver uses the U_BOOT_DRIVER macro specifying
+UCLASS_EFI as the ID of its uclass, e.g.
+
+    /* Identify as EFI 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 EFI driver.
+In the start() function the bind() function of the EFI driver is called after
+checking the GUID.
+The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child
+controllers created by the EFI driver and the EFI driver. (In U-Boot v2013.03
+this is not yet completely implemented.)
+
+### EFI block IO driver
+
+The EFI 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
+
+## Open issues as of U-Boot 2018.03
+
+* unimplemented or incompletely implemented boot services
+  * Exit - call unload function, unload applications only
+  * ReinstallProtocolInterface
+  * UnloadImage
+
+* unimplemented events
+  * EVT_RUNTIME
+  * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
+  * event groups
+
+* data model
+  * manage events in a linked list
+  * manage configuration tables in a linked list
+
+* EFI drivers
+  * support DisconnectController for EFI block devices.
+
+* Sandbox support for CONFIG_EFI_LOADER
+
+* persisted EFI variables
+
+## 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
-- 
2.14.2

[U-Boot] Fwd: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi

[Leif Lindholm]

Apologies for formatting.

On Mon, Feb 26, 2018 at 04:01:39PM +0100, Alexander Graf wrote:
> -------- Forwarded Message --------
> Subject: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi
> Date: Fri, 16 Feb 2018 12:44:27 +0100
> From: Heinrich Schuchardt <xypron.glpk@gmx.de>
> To: Alexander Graf <agraf@suse.de>
> CC: Simon Glass <sjg@chromium.org>, u-boot at lists.denx.de, Heinrich
> Schuchardt <xypron.glpk@gmx.de>
> 
> Provides information about
> 
> - usage of the bootefi command
> - overview of UEFI
> - interaction between U-Boot and EFI drivers

So I'll mention it once and then forever hold my peace:

Any specification supporting other that IA-64, (32-bit) ix86
is UEFI (released 12 years ago).
The last release of _EFI_ was in 2002.
The support in Linux actually dates back to those days.

> 
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> ---
>  doc/README.efi | 323
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 323 insertions(+)
> 
> diff --git a/doc/README.efi b/doc/README.efi
> index e69de29bb2d..92f7587a1af 100644
> --- a/doc/README.efi
> +++ b/doc/README.efi
> @@ -0,0 +1,323 @@
> +<!--
> +    Copyright (c) 2018 Heinrich Schuchardt
> +
> +    SPDX-License-Identifier:     GPL-2.0+
> +-->
> +
> +# EFI 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.

If you care about capitalisation, it should be GRUB.

> +
> +## Building for EFI
> +
> +The UEFI standard supports only little endian systems. The EFI 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 EFI application [3], requires
> +
> +    CONFIG_BLK=y
> +    CONFIG_PARTITIONS=y
> +
> +### Executing an EFI binary
> +
> +The bootefi command is used to start EFI applications or to install EFI
> drivers.
> +It takes two parameters
> +
> +    bootefi <image address> [fdt address]
> +
> +* image address - the memory address of the EFI 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
> EFI system
> +table. The Linux kernel EFI stub uses the load options as command line
> +arguments.
> +
> +### Executing the boot manager
> +
> +The UEFI specfication foresees to define boot entries and boot sequence
> via EFI
> +variables. Booting according to these variables is possible via
> +
> +    bootefi bootmgr [fdt address]
> +
> +As of U-Boot v2018.03 EFI variables are not persisted and cannot be set at
> +runtime.

So SetVariable is not supported even non-persistently?
That would be useful to add to "open issues" section below.

> +
> +### Executing the built in hello world application
> +
> +A hello world EFI 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-Boots internal
> device tree
> +(if available).
> +
> +### Executing the built-in selftest
> +
> +An EFI selftest suite can be embedded in U-Boot by building with
> +
> +    CONFIG_SELFTEST=y
> +
> +For testing the EFI implementation the bootefi command can be used to
> start the
> +selftest.
> +
> +    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 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 EFI 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 EFI drivers which come in two variants
> +
> +* boot drivers and
> +* runtime drivers.
> +
> +EFI drivers are installed with U-Boot's bootefi command. With the same
> command
> +EFI applications can be executed.
> +
> +Loaded images of EFI drivers stay in memory after returning to U-Boot while
> +loaded images of applications are removed from memory.
> +
> +An EFI application (e.g. an operating system) that wants to take full
> control
> +of the system calls ExitBootServices. After an EFI 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

Philosophical comment: my view is more that this memory becomes
available to use, rather than being released. After ExitBootServices,
the only agent in the system is the one that executed
ExitBootServices, and it gets to decide which memory is allocated or
not (and if needs to respect and protect regions in the memory map
that it is not supposed to access).

> +
> +So this is a point of no return. Afterwards the EFI application can
> only return
> +to U-Boot by rebooting.
> +
> +## The EFI object model
> +
> +EFI offers a flexible and expandable object model. The objects in the
> EFI 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 EFI 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 (not yet implemented in U-Boot)
> +* events that are only triggered programmatically
> +
> +Events can be created with the CreateEvent service and deleted with
> CloseEvent
> +service.
> +
> +## The EFI 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 EFI devices
> +
> +Some of the U-Boot devices are mapped as EFI 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 EFI 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 EFI driver then would be attached by calling
> ConnectController.
> +When a U-Boot device is removed DisconnectController should be called.
> +
> +## EFI devices mapped as U-Boot devices
> +
> +EFI drivers binaries and applications may create new (virtual) devices,
> install
> +a protocol and call the ConnectController service. Now the matching EFI
> driver
> +is determined by iterating over the implementations of the
> +EFI_DRIVER_BINDING_PROTOCOL.
> +
> +It is the task of the EFI 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.
> +
> +### EFI uclass
> +
> +An EFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
> +takes care of initializing the EFI drivers and providing the
> +EFI_DRIVER_BINDING_PROTOCOL implementation for the EFI drivers.
> +
> +A linker created list is used to keep track of the EFI drivers. To
> create an
> +entry in the list the EFI driver uses the U_BOOT_DRIVER macro specifying
> +UCLASS_EFI as the ID of its uclass, e.g.
> +
> +    /* Identify as EFI 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 EFI
> driver.
> +In the start() function the bind() function of the EFI driver is called
> after
> +checking the GUID.
> +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the
> child
> +controllers created by the EFI driver and the EFI driver. (In U-Boot
> v2013.03
> +this is not yet completely implemented.)
> +
> +### EFI block IO driver
> +
> +The EFI 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
> +
> +## Open issues as of U-Boot 2018.03

Does open issues hold some specific semantic meaning for u-boot?
Because I could add a few things not currently supported, but I think
that would make for quite tedious reading.
Isn't this more of a TODO-list?

> +
> +* unimplemented or incompletely implemented boot services
> +  * Exit - call unload function, unload applications only
> +  * ReinstallProtocolInterface
> +  * UnloadImage
> +
> +* unimplemented events
> +  * EVT_RUNTIME
> +  * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
> +  * event groups
> +
> +* data model
> +  * manage events in a linked list
> +  * manage configuration tables in a linked list
> +
> +* EFI drivers
> +  * support DisconnectController for EFI block devices.
> +
> +* Sandbox support for CONFIG_EFI_LOADER

What exactly is Sandbox support?

/
    Leif

> +
> +* persisted EFI variables
> +
> +## 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
> -- 
> 2.14.2
> 

[U-Boot] Fwd: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi

[Heinrich Schuchardt]

On 02/26/2018 06:38 PM, Leif Lindholm wrote:
> Apologies for formatting.
> 
> On Mon, Feb 26, 2018 at 04:01:39PM +0100, Alexander Graf wrote:
>> -------- Forwarded Message --------
>> Subject: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi
>> Date: Fri, 16 Feb 2018 12:44:27 +0100
>> From: Heinrich Schuchardt <xypron.glpk@gmx.de>
>> To: Alexander Graf <agraf@suse.de>
>> CC: Simon Glass <sjg@chromium.org>, u-boot at lists.denx.de, Heinrich
>> Schuchardt <xypron.glpk@gmx.de>
>>
>> Provides information about
>>
>> - usage of the bootefi command
>> - overview of UEFI
>> - interaction between U-Boot and EFI drivers
> 
> So I'll mention it once and then forever hold my peace:
> 
> Any specification supporting other that IA-64, (32-bit) ix86
> is UEFI (released 12 years ago).
> The last release of _EFI_ was in 2002.
> The support in Linux actually dates back to those days.

Hello Leif,

thanks for reviewing.

The UEFI spec itself is comfortable to use the term EFI again and again 
even for new items added in 2017, e.g.

- Add new data type to EFI Supplicant Protocol
- Add EFI HTTP Boot Callback Protocol
- EFI regular expression syntax type definitions
- 4.7.4 EFI Driver Model Example

What is the change you suggest?

> 
>>
>> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
>> ---
>>   doc/README.efi | 323
>> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 323 insertions(+)
>>
>> diff --git a/doc/README.efi b/doc/README.efi
>> index e69de29bb2d..92f7587a1af 100644
>> --- a/doc/README.efi
>> +++ b/doc/README.efi
>> @@ -0,0 +1,323 @@
>> +<!--
>> +    Copyright (c) 2018 Heinrich Schuchardt
>> +
>> +    SPDX-License-Identifier:     GPL-2.0+
>> +-->
>> +
>> +# EFI 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.
> 
> If you care about capitalisation, it should be GRUB.

Yes.

> 
>> +
>> +## Building for EFI
>> +
>> +The UEFI standard supports only little endian systems. The EFI 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 EFI application [3], requires
>> +
>> +    CONFIG_BLK=y
>> +    CONFIG_PARTITIONS=y
>> +
>> +### Executing an EFI binary
>> +
>> +The bootefi command is used to start EFI applications or to install EFI
>> drivers.
>> +It takes two parameters
>> +
>> +    bootefi <image address> [fdt address]
>> +
>> +* image address - the memory address of the EFI 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
>> EFI system
>> +table. The Linux kernel EFI stub uses the load options as command line
>> +arguments.
>> +
>> +### Executing the boot manager
>> +
>> +The UEFI specfication foresees to define boot entries and boot sequence
>> via EFI
>> +variables. Booting according to these variables is possible via
>> +
>> +    bootefi bootmgr [fdt address]
>> +
>> +As of U-Boot v2018.03 EFI variables are not persisted and cannot be set at
>> +runtime.
> 
> So SetVariable is not supported even non-persistently?

You can use SetVariable() before ExitBootServices().

> That would be useful to add to "open issues" section below.

Yes.

> 
>> +
>> +### Executing the built in hello world application
>> +
>> +A hello world EFI 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-Boots internal
>> device tree
>> +(if available).
>> +
>> +### Executing the built-in selftest
>> +
>> +An EFI selftest suite can be embedded in U-Boot by building with
>> +
>> +    CONFIG_SELFTEST=y
>> +
>> +For testing the EFI implementation the bootefi command can be used to
>> start the
>> +selftest.
>> +
>> +    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 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 EFI 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 EFI drivers which come in two variants
>> +
>> +* boot drivers and
>> +* runtime drivers.
>> +
>> +EFI drivers are installed with U-Boot's bootefi command. With the same
>> command
>> +EFI applications can be executed.
>> +
>> +Loaded images of EFI drivers stay in memory after returning to U-Boot while
>> +loaded images of applications are removed from memory.
>> +
>> +An EFI application (e.g. an operating system) that wants to take full
>> control
>> +of the system calls ExitBootServices. After an EFI 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
> 
> Philosophical comment: my view is more that this memory becomes
> available to use, rather than being released. After ExitBootServices,
> the only agent in the system is the one that executed
> ExitBootServices, and it gets to decide which memory is allocated or
> not (and if needs to respect and protect regions in the memory map
> that it is not supposed to access).

The firmware decides which memory the OS may use. All memory that is 
marked as EFI_MEMORY_RUNTIME is managed by the firmware at all times.

Concerning the lone agent in the system, I would be happy if you were 
right. Unfortunately other agents like Intel AMT exist which give the 
operating system a subordinate role.

> 
>> +
>> +So this is a point of no return. Afterwards the EFI application can
>> only return
>> +to U-Boot by rebooting.
>> +
>> +## The EFI object model
>> +
>> +EFI offers a flexible and expandable object model. The objects in the
>> EFI 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 EFI 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 (not yet implemented in U-Boot)
>> +* events that are only triggered programmatically
>> +
>> +Events can be created with the CreateEvent service and deleted with
>> CloseEvent
>> +service.
>> +
>> +## The EFI 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 EFI devices
>> +
>> +Some of the U-Boot devices are mapped as EFI 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 EFI 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 EFI driver then would be attached by calling
>> ConnectController.
>> +When a U-Boot device is removed DisconnectController should be called.
>> +
>> +## EFI devices mapped as U-Boot devices
>> +
>> +EFI drivers binaries and applications may create new (virtual) devices,
>> install
>> +a protocol and call the ConnectController service. Now the matching EFI
>> driver
>> +is determined by iterating over the implementations of the
>> +EFI_DRIVER_BINDING_PROTOCOL.
>> +
>> +It is the task of the EFI 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.
>> +
>> +### EFI uclass
>> +
>> +An EFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
>> +takes care of initializing the EFI drivers and providing the
>> +EFI_DRIVER_BINDING_PROTOCOL implementation for the EFI drivers.
>> +
>> +A linker created list is used to keep track of the EFI drivers. To
>> create an
>> +entry in the list the EFI driver uses the U_BOOT_DRIVER macro specifying
>> +UCLASS_EFI as the ID of its uclass, e.g.
>> +
>> +    /* Identify as EFI 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 EFI
>> driver.
>> +In the start() function the bind() function of the EFI driver is called
>> after
>> +checking the GUID.
>> +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the
>> child
>> +controllers created by the EFI driver and the EFI driver. (In U-Boot
>> v2013.03
>> +this is not yet completely implemented.)
>> +
>> +### EFI block IO driver
>> +
>> +The EFI 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
>> +
>> +## Open issues as of U-Boot 2018.03
> 
> Does open issues hold some specific semantic meaning for u-boot?
> Because I could add a few things not currently supported, but I think
> that would make for quite tedious reading.
> Isn't this more of a TODO-list?

Please, send your items.

Would you prefer if this chapter were called TODO list?
Or is your idea we should remove the list from this document?

> 
>> +
>> +* unimplemented or incompletely implemented boot services
>> +  * Exit - call unload function, unload applications only
>> +  * ReinstallProtocolInterface
>> +  * UnloadImage
>> +
>> +* unimplemented events
>> +  * EVT_RUNTIME
>> +  * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
>> +  * event groups
>> +
>> +* data model
>> +  * manage events in a linked list
>> +  * manage configuration tables in a linked list
>> +
>> +* EFI drivers
>> +  * support DisconnectController for EFI block devices.
>> +
>> +* Sandbox support for CONFIG_EFI_LOADER
> 
> What exactly is Sandbox support?

Currently CONFIG_SANDBOX=y and CONFIG_EFI_LOADER cannot go together.

Regards

Heinrich

> 
> /
>      Leif
> 
>> +
>> +* persisted EFI variables
>> +
>> +## 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
>> -- 
>> 2.14.2
>>
> 

[U-Boot] Fwd: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi

[Leif Lindholm]

On Mon, Feb 26, 2018 at 07:37:15PM +0100, Heinrich Schuchardt wrote:
> On 02/26/2018 06:38 PM, Leif Lindholm wrote:
> > Apologies for formatting.
> > 
> > On Mon, Feb 26, 2018 at 04:01:39PM +0100, Alexander Graf wrote:
> > > -------- Forwarded Message --------
> > > Subject: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi
> > > Date: Fri, 16 Feb 2018 12:44:27 +0100
> > > From: Heinrich Schuchardt <xypron.glpk@gmx.de>
> > > To: Alexander Graf <agraf@suse.de>
> > > CC: Simon Glass <sjg@chromium.org>, u-boot at lists.denx.de, Heinrich
> > > Schuchardt <xypron.glpk@gmx.de>
> > > 
> > > Provides information about
> > > 
> > > - usage of the bootefi command
> > > - overview of UEFI
> > > - interaction between U-Boot and EFI drivers
> > 
> > So I'll mention it once and then forever hold my peace:
> > 
> > Any specification supporting other that IA-64, (32-bit) ix86
> > is UEFI (released 12 years ago).
> > The last release of _EFI_ was in 2002.
> > The support in Linux actually dates back to those days.
> 
> Hello Leif,
> 
> thanks for reviewing.
> 
> The UEFI spec itself is comfortable to use the term EFI again and again even
> for new items added in 2017, e.g.
> 
> - Add new data type to EFI Supplicant Protocol
> - Add EFI HTTP Boot Callback Protocol
> - EFI regular expression syntax type definitions
> - 4.7.4 EFI Driver Model Example

Yes, the existing definitions were never renamed, and new ones are
still defined to match the old pattern.

> 
> What is the change you suggest?

Ideally, to use UEFI wherever not referring specifically to an
interface described by the UEFI specification.
For clarity, I will nitpick below. Feel free to include or ignore.

> > 
> > > 
> > > Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> > > ---
> > >   doc/README.efi | 323
> > > +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > >   1 file changed, 323 insertions(+)
> > > 
> > > diff --git a/doc/README.efi b/doc/README.efi
> > > index e69de29bb2d..92f7587a1af 100644
> > > --- a/doc/README.efi
> > > +++ b/doc/README.efi

README.uefi

> > > @@ -0,0 +1,323 @@
> > > +<!--
> > > +    Copyright (c) 2018 Heinrich Schuchardt
> > > +
> > > +    SPDX-License-Identifier:     GPL-2.0+
> > > +-->
> > > +
> > > +# EFI on U-Boot

"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.
> > 
> > If you care about capitalisation, it should be GRUB.
> 
> Yes.
> 
> > 
> > > +
> > > +## Building for EFI

"Building for UEFI"

> > > +
> > > +The UEFI standard supports only little endian systems. The EFI support

"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 EFI application [3], requires

"loaded UEFI application"

> > > +
> > > +    CONFIG_BLK=y
> > > +    CONFIG_PARTITIONS=y
> > > +
> > > +### Executing an EFI binary
> > > +
> > > +The bootefi command is used to start EFI applications or to install EFI

"start UEFI applications or to install UEFI"

> > > drivers.
> > > +It takes two parameters
> > > +
> > > +    bootefi <image address> [fdt address]
> > > +
> > > +* image address - the memory address of the EFI binary

"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
> > > EFI system
> > > +table. The Linux kernel EFI stub uses the load options as command line
> > > +arguments.
> > > +
> > > +### Executing the boot manager
> > > +
> > > +The UEFI specfication foresees to define boot entries and boot sequence
> > > via EFI
> > > +variables. Booting according to these variables is possible via

"UEFI variables"

> > > +
> > > +    bootefi bootmgr [fdt address]
> > > +
> > > +As of U-Boot v2018.03 EFI variables are not persisted and cannot be set at

"UEFI variables"

> > > +runtime.
> > 
> > So SetVariable is not supported even non-persistently?
> 
> You can use SetVariable() before ExitBootServices().

Right. Could you perhaps change this to read "are not persistent and
can only be set before ExitBootServices()"?

> > That would be useful to add to "open issues" section below.
> 
> Yes.
> 
> > 
> > > +
> > > +### Executing the built in hello world application
> > > +
> > > +A hello world EFI 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-Boots
> > > internal

U-Boot's
(Sorry, didn't mention on first response.)

> > > device tree
> > > +(if available).
> > > +
> > > +### Executing the built-in selftest
> > > +
> > > +An EFI selftest suite can be embedded in U-Boot by building with

"A UEFI selftest"

> > > +
> > > +    CONFIG_SELFTEST=y
> > > +
> > > +For testing the EFI implementation the bootefi command can be used to

"For testing the UEFI implementation"

> > > start the
> > > +selftest.
> > > +
> > > +    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 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 EFI life cycle

"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 EFI drivers which come in two variants

"UEFI drivers"

> > > +
> > > +* boot drivers and
> > > +* runtime drivers.
> > > +
> > > +EFI drivers are installed with U-Boot's bootefi command. With the same

"UEFI drivers"

> > > command
> > > +EFI applications can be executed.

"UEFI applications"

> > > +
> > > +Loaded images of EFI drivers stay in memory after returning to U-Boot while

"UEFI drivers"

> > > +loaded images of applications are removed from memory.
> > > +
> > > +An EFI application (e.g. an operating system) that wants to take full

"A UEFI application"

> > > control
> > > +of the system calls ExitBootServices. After an EFI application calls

"a UEFI application"

> > > +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
> > 
> > Philosophical comment: my view is more that this memory becomes
> > available to use, rather than being released. After ExitBootServices,
> > the only agent in the system is the one that executed
> > ExitBootServices, and it gets to decide which memory is allocated or
> > not (and if needs to respect and protect regions in the memory map
> > that it is not supposed to access).
> 
> The firmware decides which memory the OS may use. All memory that is marked
> as EFI_MEMORY_RUNTIME is managed by the firmware at all times.

The firmware no longer has a context at this point - it can only work
on memory it had flagged in the memory map that it needed to use
during runtime, or buffers passed to it via pointers.

> Concerning the lone agent in the system, I would be happy if you were right.
> Unfortunately other agents like Intel AMT exist which give the operating
> system a subordinate role.

That is a relevant point, but not related to UEFI. UEFI has no role in
that other than passing the information on to the operating system
which areas of memory it is not permitted to touch (and would likely
trigger hardware exceptions if the OS didn't obey).
Using virtualization terminology, both UEFI and the operating system
are guests.

> > 
> > > +
> > > +So this is a point of no return. Afterwards the EFI application can

"UEFI application"

> > > only return
> > > +to U-Boot by rebooting.
> > > +
> > > +## The EFI object model

"UEFI object"

> > > +
> > > +EFI offers a flexible and expandable object model. The objects in the

"UEFI offers"

> > > EFI 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 EFI events

"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 (not yet implemented in U-Boot)
> > > +* events that are only triggered programmatically
> > > +
> > > +Events can be created with the CreateEvent service and deleted with
> > > CloseEvent
> > > +service.
> > > +
> > > +## The EFI driver model

"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 EFI devices

"as UEFI devices"

> > > +
> > > +Some of the U-Boot devices are mapped as EFI devices

"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 EFI devices

"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 EFI driver then would be attached by calling
> > > ConnectController.
> > > +When a U-Boot device is removed DisconnectController should be called.
> > > +
> > > +## EFI devices mapped as U-Boot devices

"UEFI devices"

> > > +
> > > +EFI drivers binaries and applications may create new (virtual) devices,

"UEFI drivers"

> > > install
> > > +a protocol and call the ConnectController service. Now the matching EFI
> > > driver

"UEFI drivers"

> > > +is determined by iterating over the implementations of the
> > > +EFI_DRIVER_BINDING_PROTOCOL.
> > > +
> > > +It is the task of the EFI driver to create a corresponding U-Boot

"the UEFI driver"

> > > 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.
> > > +
> > > +### EFI uclass

So, yeah it'd be great if these were all "UEFI uclass", but that would
clearly require code changes at this point...

> > > +
> > > +An EFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that
> > > +takes care of initializing the EFI drivers and providing the

"the UEFI drivers"

> > > +EFI_DRIVER_BINDING_PROTOCOL implementation for the EFI drivers.

"the UEFI drivers"

> > > +
> > > +A linker created list is used to keep track of the EFI drivers. To

"the UEFI drivers"

> > > create an
> > > +entry in the list the EFI driver uses the U_BOOT_DRIVER macro specifying

"the UEFI driver"

> > > +UCLASS_EFI as the ID of its uclass, e.g.
> > > +
> > > +    /* Identify as EFI driver */

"UEFI driver"

> > > +    U_BOOT_DRIVER(efi_block) = {
> > > +    	.name  = "EFI block driver",

"UEFI 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 EFI
> > > driver.

"the UEFI driver"

> > > +In the start() function the bind() function of the EFI driver is called
> > > after

"the UEFI driver"

> > > +checking the GUID.
> > > +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the
> > > child
> > > +controllers created by the EFI driver and the EFI driver. (In U-Boot

"the UEFI driver"
"the UEFI driver"
(although it may flow better as "the UEFI driver and the child
controllers created by it")

> > > v2013.03
> > > +this is not yet completely implemented.)
> > > +
> > > +### EFI block IO driver

"UEFI block"

> > > +
> > > +The EFI 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
> > > +
> > > +## Open issues as of U-Boot 2018.03
> > 
> > Does open issues hold some specific semantic meaning for u-boot?
> > Because I could add a few things not currently supported, but I think
> > that would make for quite tedious reading.
> > Isn't this more of a TODO-list?
> 
> Please, send your items.

Well, ...

> Would you prefer if this chapter were called TODO list?
> Or is your idea we should remove the list from this document?

I think it's excellent as a TODO list.
It's just if it's called "Open issues", that can arguably be extended
to "implement the remainder of the UEFI specification" :)

One thing I would add is non-persistent variable support during
runtime (as mentioned above), separately from implementing persistent
variable support.

> > 
> > > +
> > > +* unimplemented or incompletely implemented boot services
> > > +  * Exit - call unload function, unload applications only
> > > +  * ReinstallProtocolInterface
> > > +  * UnloadImage
> > > +
> > > +* unimplemented events
> > > +  * EVT_RUNTIME
> > > +  * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
> > > +  * event groups
> > > +
> > > +* data model
> > > +  * manage events in a linked list
> > > +  * manage configuration tables in a linked list
> > > +
> > > +* EFI drivers
> > > +  * support DisconnectController for EFI block devices.
> > > +
> > > +* Sandbox support for CONFIG_EFI_LOADER
> > 
> > What exactly is Sandbox support?
> 
> Currently CONFIG_SANDBOX=y and CONFIG_EFI_LOADER cannot go together.

Right, so it's just me being clueless about U-Boot :)
Please ignore.

Regards,

Leif

> Regards
> 
> Heinrich
> 
> > 
> > /
> >      Leif
> > 
> > > +
> > > +* persisted EFI variables
> > > +
> > > +## 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
> > > -- 
> > > 2.14.2
> > > 
> > 
>