[U-Boot,v3,2/2] efi_loader: provide new doc/README.uefi

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>
---
v3
	rename README.efi to README.uefi
	use UEFI instead of EFI where applicable
v2
	split the patch in two: one deleteing all old lines, the other
	adding the new ones
	update README contents
---
 MAINTAINERS     |   2 +-
 doc/README.efi  |   0
 doc/README.uefi | 332 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 333 insertions(+), 1 deletion(-)
 delete mode 100644 doc/README.efi
 create mode 100644 doc/README.uefi

On Fri, Mar 02, 2018 at 07:58:50PM +0100, Heinrich Schuchardt wrote:
> 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>

Well, from my point of view:
Reviewed-by: Leif Lindholm <leif.lindholm@linaro.org>
or
Acked-by: Leif Lindholm <leif.lindholm@linaro.org>
(whichever makes more sense).

Many thanks!

/
    Leif

> ---
> v3
> 	rename README.efi to README.uefi
> 	use UEFI instead of EFI where applicable
> v2
> 	split the patch in two: one deleteing all old lines, the other
> 	adding the new ones
> 	update README contents
> ---
>  MAINTAINERS     |   2 +-
>  doc/README.efi  |   0
>  doc/README.uefi | 332 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 333 insertions(+), 1 deletion(-)
>  delete mode 100644 doc/README.efi
>  create mode 100644 doc/README.uefi
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 077828cf1d4..da799b551d9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -290,7 +290,7 @@ EFI PAYLOAD
>  M:	Alexander Graf <agraf@suse.de>
>  S:	Maintained
>  T:	git git://github.com/agraf/u-boot.git
> -F:	doc/README.efi
> +F:	doc/README.uefi
>  F:	doc/README.iscsi
>  F:	include/efi*
>  F:	include/pe.h
> diff --git a/doc/README.efi b/doc/README.efi
> deleted file mode 100644
> index e69de29bb2d..00000000000
> diff --git a/doc/README.uefi b/doc/README.uefi
> new file mode 100644
> index 00000000000..7403be36146
> --- /dev/null
> +++ b/doc/README.uefi
> @@ -0,0 +1,332 @@
> +<!--
> +    Copyright (c) 2018 Heinrich Schuchardt
> +
> +    SPDX-License-Identifier:     GPL-2.0+
> +-->
> +
> +# 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.
> +
> +## 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 specfication 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 selftest
> +
> +An UEFI selftest 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
> +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 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 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
> +
> +* UEFI drivers
> +  * support DisconnectController for UEFI block devices.
> +
> +* support for CONFIG_EFI_LOADER in the sandbox (CONFIG_SANDBOX=y)
> +
> +* UEFI variables
> +  * persistence
> +  * runtime support
> +
> +## 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.16.1
>