Re: [U-Boot] Fwd: [PATCH v2 2/2][for v2018.03] efi_loader: provide new doc/README.efi
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@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
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@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
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@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
participants (2)
-
Heinrich Schuchardt -
Leif Lindholm