All,
We have our normal DTE call today. Due to different day light saving
time dates in US vs UK the meeting will be one hour later than usual for
most US people.
When I checked yesterday Frank was not yet ready to talk about the DTB
format changes so I have no ready made agenda today.
We have a DT & SysDT talk and BOF tomorrow at Linaro Connect. Hope to
see you all there.
Attendance is free: https://connect.linaro.org/
Thanks,
Bill
--
Bill Mills
Principal Technical Consultant, Linaro
+1-240-643-0836
TZ: US Eastern
Work Schedule: Tues/Wed/Thur
Hi all,
I'm about ready to tag the first pre-release of EBBR v2.0. Here is the
full changelog as compared to v1.0.1. Once I tag this release I'll be
casting the net wider for comments before the document gets released.
There are lots of little changes to the document, and a few notable big
ones. Big things to look for are:
- Reduced required elements in UEFI requirements
- Firmware shared storage refinements
- Capsule Update is now required
Please let me know if you have any comments. Better yet, open an issue
in github so that it doesn't get forgotten. We'll also be discussing the
release at the EBBR biweekly on Monday 15th March.
https://github.com/ARM-software/ebbr/issues
Here's the full list of changes:
96dbb03 Reference BBR instead of SBBR (not yet merged)
2a6ca89 Fedora needs two more packages
2e3e873 CONTRIBUTING: let wording follow branching
cf29c4c README.rst: Python 2 is long time gone
396abac Fix build warnings:
e5d32ca trivial: remove duplicate SCSI pass through support
98e24fe Merge pull request #73 from glikely/for-next
eb34dbf Require EFI_UPDATE_CAPSULE
139e6c2 Refine RTC requirements
48e1e56 UEFI section 2.6 exceptions for boot services
72f3e2d Override UEFI section 2.6 requirements
58a2a27 Change required services table titles to be more accurate
d4ff44e Minor suggestions to hopefully improve the text
0555e38 Reformat revision history table to render better
5d836bc Refine firmware shared storage requirements.
a89cf43 Add reference to RFC 2119 in conventions
8db9eed Fix ResetSystem() text to describe failure condition
eda36e4 Merge pull request #48 from jbech-linaro/optee-url
c4ef5c7 Update link to OP-TEE secure storage
And here is the full diff:
CONTRIBUTING.rst | 2 +-
README.rst | 15 ++--
source/chapter1-about.rst | 30 ++++---
source/chapter2-uefi.rst | 292
++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
source/chapter4-firmware-media.rst | 72 ++++++++++++----
source/conf.py | 2 +-
source/index.rst | 57 ++++++-------
source/references.rst | 12 ++-
8 files changed, 378 insertions(+), 104 deletions(-)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 7021f0f..be979e0 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,7 +1,7 @@
Contributing
============
-Master copy of this project is hosted on GitHub:
+Main copy of this project is hosted on GitHub:
https://github.com/ARM-software/ebbr
Anyone may contribute to the EBBR project.
diff --git a/README.rst b/README.rst
index 7480dcb..acf6742 100644
--- a/README.rst
+++ b/README.rst
@@ -41,31 +41,28 @@ On Debian and Ubuntu
^^^^^^^^^^^^^^^^^^^^
::
- # apt-get install python-sphinx texlive texlive-latex-extra
libalgorithm-diff-perl \
+ # apt-get install python3-sphinx texlive texlive-latex-extra
libalgorithm-diff-perl \
texlive-humanities texlive-generic-recommended
texlive-generic-extra \
latexmk
If the version of python-sphinx installed is too old, then an additional
new version can be installed with the Python package installer::
- $ apt-get install python-pip
- $ pip install --user --upgrade Sphinx
+ $ apt-get install python3-pip
+ $ pip3 install --user --upgrade Sphinx
$ export SPHINXBUILD=~/.local/bin/sphinx-build
-Export SPHINXBUILD (see above) if Sphinx was installed with pip --user,
then follow Make commands below
+Export SPHINXBUILD (see above) if Sphinx was installed with pip3
--user, then follow Make commands below.
On Fedora
^^^^^^^^^
::
- # dnf install python2-sphinx texlive texlive-capt-of
texlive-draftwatermark \
+ # dnf install python3-sphinx texlive texlive-capt-of
texlive-draftwatermark \
texlive-fncychap texlive-framed texlive-needspace \
texlive-tabulary texlive-titlesec texlive-upquote \
- texlive-wrapfig
-
-It is also possible to use python3-sphinx; this requires
-SPHINXBUILD=sphinx-build-3 to be passed on the Make command line.
+ texlive-wrapfig texinfo latexmk
On Mac OS X
^^^^^^^^^^^
diff --git a/source/chapter1-about.rst b/source/chapter1-about.rst
index 3744d8a..6f69f53 100644
--- a/source/chapter1-about.rst
+++ b/source/chapter1-about.rst
@@ -50,8 +50,8 @@ Vendors have heavy investments in both projects and
are not interested in large
scale changes to their firmware architecture.
The challenge for EBBR is to define a set of boot standards that
reduce the
amount of custom engineering required, make it possible for OS
distributions to
-support embedded platforms, while still preserving the firmware stack
product
-vendors are comfortable with.
+support embedded platforms, while still preserving the firmware stack that
+product vendors are comfortable with.
Or in simpler terms, EBBR is designed to solve the embedded boot mess by
adding a defined standard (UEFI) to the existing firmware projects
(U-Boot).
@@ -146,19 +146,23 @@ including services that are required for
virtualization.
It does not define a standardized abstract virtual machine view for a
Guest
Operating System.
-This specification is similar to the Arm Server Base Boot Requirements
-specification [SBBR]_ in that it defines the firmware interface
presented to an
-operating system.
-SBBR is targeted at the server ecosystem and places strict requirements
on the
-platform to ensure cross vendor interoperability.
-EBBR on the other hand allows more flexibility to support embedded designs
-which do not fit within the SBBR model.
-For example, a platform that isn't SBBR compliant because the SoC is only
-supported using Devicetree could be EBBR compliant, but not SBBR compliant.
-
-By definition, all SBBR compliant systems are also EBBR compliant, but the
+This specification is referenced by the Arm Base Boot Requirements
+Specification [ArmBBR]_ § 4.3.
+The UEFI requirements found in this document are similar but not
identical to
+the requirements found in BBR.
+EBBR provides greater flexibility for support embedded designs which cannot
+easily meet the stricter BBR requirements.
+
+By definition, all BBR compliant systems are also EBBR compliant, but the
converse is not true.
+Conventions Used in this Document
+=================================
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are
to be
+interpreted as described in :rfc:`2119`.
+
Cross References
================
This document cross-references sources that are listed in the References
diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst
index 066fefb..a0b3e8d 100644
--- a/source/chapter2-uefi.rst
+++ b/source/chapter2-uefi.rst
@@ -14,8 +14,179 @@ This document uses version 2.8 Errata A of the UEFI
specification [UEFI]_.
UEFI Compliance
===============
-EBBR compliant platforms shall conform to the requirements in [UEFI]_ §
2.6,
-except where explicit exemptions are provided by this document.
+EBBR compliant platform shall conform to a subset of the [UEFI]_ spec
as listed
+in this section.
+Normally, UEFI compliance would require full compliance with all items
listed
+in UEFI § 2.6.
+However, the EBBR target market has a reduced set of requirements,
+and so some UEFI features are omitted as unnecessary.
+
+Required Elements
+-----------------
+
+This section replaces the list of required elements in [UEFI]_ § 2.6.1.
+All of the following UEFI elements are required for EBBR compliance.
+
+.. list-table:: UEFI Required Elements
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Element
+ - Requirement
+ * - `EFI_SYSTEM_TABLE`
+ - The system table is required to provide required to access UEFI
Boot Services,
+ UEFI Runtime Services, consoles, and other firmware, vendor and
platform
+ information.
+ * - `EFI_BOOT_SERVICES`
+ - All functions defined as boot services must exist.
+ Methods for unsupported or unimplemented behaviour must return
+ an appropriate error code.
+ * - `EFI_RUNTIME_SERVICES`
+ - All functions defined as runtime services must exist.
+ Methods for unsupported or unimplemented behaviour must return
+ an appropriate error code.
+ If any runtime service is unimplemented, it must be indicated
+ via the EFI_RT_PROPERTIES_TABLE.
+ * - `EFI_LOADED_IMAGE_PROTOCOL`
+ - Must be installed for each loaded image
+ * - `EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL`
+ - Must be installed for each loaded image
+ * - `EFI_DEVICE_PATH_PROTOCOL`
+ - An `EFI_DEVICE_PATH_PROTOCOL` must be installed onto all device
+ handles provided by the firmware.
+ * - `EFI_DEVICE_PATH_UTILITIES_PROTOCOL`
+ - Interface for creating and manipulating UEFI device paths
+
+.. list-table:: Notable omissions from UEFI § 2.6.1
+ :header-rows: 1
+
+ * - Element
+ - Note
+ * - `EFI_DECOMPRESS_PROTOCOL`
+ - Native EFI decompression is rarely used and therefore not required.
+
+Required Platform Specific Elements
+-----------------------------------
+
+This section replaces the list of required elements in [UEFI]_ § 2.6.2.
+All of the following UEFI elements are required for EBBR compliance.
+
+.. list-table:: UEFI Platform-Specific Required Elements
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Element
+ - Description
+ * - Console devices
+ - The platform must have at least one console device
+ * - `EFI_SIMPLE_TEXT_INPUT_PROTOCOL`
+ - Needed for console input
+ * - `EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL`
+ - Needed for console input
+ * - `EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL`
+ - Needed for console output
+ * - `EFI_DEVICE_PATH_TO_TEXT_PROTOCOL`
+ - Needed for console output
+ * - `EFI_HII_STRING_PROTOCOL`
+ - Required by EFI shell and for compliance testing
+ * - `EFI_HII_DATABASE_PROTOCOL`
+ - Required by EFI shell and for compliance testing
+ * - `EFI_UNICODE_COLLATION2_PROTOCOL`
+ - Required by EFI shell and for compliance testing
+ * - `EFI_BLOCK_IO_PROTOCOL`
+ - Required for block device access
+ * - `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL`
+ - Required if booting from block device is supported
+ * - `EFI_RNG_PROTOCOL`
+ - Required if the platform has a hardware entropy source
+ * - `EFI_SIMPLE_NETWORK_PROTOCOL`
+ - Required if the platform has a network device.
+ * - HTTP Boot (UEFI § 24.7)
+ - Required if the platform supports network booting
+
+The following table is a list of notable deviations from UEFI § 2.6.2.
+Many of these deviations are because the EBBR use cases do not require
+interface specific UEFI protocols, and so they have been made optional.
+
+.. list-table:: Notable Deviations from UEFI § 2.6.2
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Element
+ - Description of deviation
+ * - `LoadImage()`
+ - The LoadImage() boot service is not required to install an
+ EFI_HII_PACKAGE_LIST_PROTOCOL for an image containing a custom
PE/COFF
+ resource with the type 'HII'. - HII resource images are not
needed to run
+ the UEFI shell or the SCT.
+ * - `ConnectController()`
+ - The ConnectController()` boot service is not required to support the
+ EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL,
+ EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL, and
+ EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL. - These override
protocols are
+ only useful if drivers are loaded as EFI binaries by the firmware.
+ * - `EFI_HII_CONFIG_ACCESS_PROTOCOL`
+ - UEFI requires this for console devices, but it is rarely
necessary in practice.
+ Therefore this protocol is not required.
+ * - `EFI_HII_CONFIG_ROUTING_PROTOCOL`
+ - UEFI requires this for console devices, but it is rarely
necessary in practice.
+ Therefore this protocol is not required.
+ * - Graphical console
+ - Platforms with a graphical device are not required to expose it
as a graphical console.
+ * - `EFI_DISK_IO_PROTOCOL`
+ - Rarely used interface that isn't required for EBBR use cases
+ * - `EFI_PXE_BASE_CODE_PROTOCOL`
+ - Booting via the Preboot Execution Environment (PXE) is insecure.
+ Loading via PXE is typically executed before launching the first
UEFI application.
+ * - Network protocols
+ - A full implementation of the UEFI general purpose networking
ABIs is not required,
+ including `EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL`,
`EFI_MANAGED_NETWORK_PROTOCOL`,
+ `EFI_*_SERVICE_BINDING_PROTOCOL`, or any of the IPv4 or IPv6
protocols.
+ * - Byte stream device support (UART)
+ - UEFI protocols not required
+ * - PCI bus support
+ - UEFI protocols not required
+ * - USB bus support
+ - UEFI protocols not required
+ * - NVMe pass through support
+ - UEFI protocols not required
+ * - SCSI pass through support
+ - UEFI protocols not required
+ * - `EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL`
+ - Not required
+ * - Option ROM support
+ - In many EBBR use cases there is no requirement to generically
support
+ any PCIe add in card at the firmware level.
+ When PCIe devices are used, drivers for the device are often
built into
+ the firmware itself rather than loaded as option ROMs.
+ For this reason EBBR implementations are not required to support
option
+ ROM loading.
+
+Required Global Variables
+-------------------------
+
+EBBR compliant platforms are required to support the following Global
+Variables as found in [UEFI]_ § 3.3.
+
+.. list-table:: Required UEFI Variables
+ :widths: 25 75
+ :header-rows: 1
+
+ * - Variable Name
+ - Description
+ * - `Boot####`
+ - A boot load option. #### is a numerical hex value
+ * - `BootCurrent`
+ - The boot option that was selected for the current boot
+ * - `BootNext`
+ - The boot option that will be used for the next boot only
+ * - `BootOrder`
+ - An ordered list of boot options.
+ Firmware will attempt each Boot#### entry in this order
+ * - `OsIndications`
+ - Method for OS to request features from firmware
+ * - `OsIndicationsSupported`
+ - Variable for firmware to indicate which features can be enabled
Block device partitioning
-------------------------
@@ -53,7 +224,7 @@ a hypervisor or a virtualization aware Operating System.
UEFI Boot at EL1
^^^^^^^^^^^^^^^^
-Booting of UEFI at EL1 is most likely within a hypervisor hosted Guest
+Booting of UEFI at EL1 is most likely employed within a hypervisor
hosted Guest
Operating System environment, to allow the subsequent booting of a
UEFI-compliant Operating System.
In this instance, the UEFI boot-time environment can be provided, as a
@@ -77,7 +248,7 @@ The default RAM allocated attribute must be
EFI_MEMORY_WB.
Configuration Tables
--------------------
-A UEFI system that complies with this specification may provide the
additional
+A UEFI system that complies with this specification may provide additional
tables via the EFI Configuration Table.
Compliant systems are required to provide one, but not both, of the
following
@@ -151,26 +322,55 @@ EFI_UNSUPPORTED.
are required to be implemented during boot services and runtime services.
.. _uefi_runtime_service_requirements:
-.. table:: EFI_RUNTIME_SERVICES Implementation Requirements
-
- ============================== ============= ================
- EFI_RUNTIME_SERVICES function Boot Services Runtime Services
- ============================== ============= ================
- EFI_GET_TIME Optional Optional
- EFI_SET_TIME Optional Optional
- EFI_GET_WAKEUP_TIME Optional Optional
- EFI_SET_WAKEUP_TIME Optional Optional
- EFI_SET_VIRTUAL_ADDRESS_MAP N/A Required
- EFI_CONVERT_POINTER N/A Required
- EFI_GET_VARIABLE Required Optional
- EFI_GET_NEXT_VARIABLE_NAME Required Optional
- EFI_SET_VARIABLE Required Optional
- EFI_GET_NEXT_HIGH_MONO_COUNT N/A Optional
- EFI_RESET_SYSTEM Required Optional
- EFI_UPDATE_CAPSULE Optional Optional
- EFI_QUERY_CAPSULE_CAPABILITIES Optional Optional
- EFI_QUERY_VARIABLE_INFO Optional Optional
- ============================== ============= ================
+.. list-table:: `EFI_RUNTIME_SERVICES` Implementation Requirements
+ :widths: 40 30 30
+ :header-rows: 1
+
+ * - `EFI_RUNTIME_SERVICES` function
+ - Before ExitBootServices()
+ - After ExitBootServices()
+ * - `EFI_GET_TIME`
+ - Required if RTC present
+ - Optional
+ * - `EFI_SET_TIME`
+ - Required if RTC present
+ - Optional
+ * - `EFI_GET_WAKEUP_TIME`
+ - Required if wakeup supported
+ - Optional
+ * - `EFI_SET_WAKEUP_TIME`
+ - Required if wakeup supported
+ - Optional
+ * - `EFI_SET_VIRTUAL_ADDRESS_MAP`
+ - N/A
+ - Required
+ * - `EFI_CONVERT_POINTER`
+ - N/A
+ - Required
+ * - `EFI_GET_VARIABLE`
+ - Required
+ - Optional
+ * - `EFI_GET_NEXT_VARIABLE_NAME`
+ - Required
+ - Optional
+ * - `EFI_SET_VARIABLE`
+ - Required
+ - Optional
+ * - `EFI_GET_NEXT_HIGH_MONO_COUNT`
+ - N/A
+ - Optional
+ * - `EFI_RESET_SYSTEM`
+ - Required
+ - Optional
+ * - `EFI_UPDATE_CAPSULE`
+ - Required for in-band update
+ - Optional
+ * - `EFI_QUERY_CAPSULE_CAPABILITIES`
+ - Optional
+ - Optional
+ * - `EFI_QUERY_VARIABLE_INFO`
+ - Optional
+ - Optional
Runtime Device Mappings
-----------------------
@@ -198,8 +398,11 @@ it may not be possible to access the RTC from
runtime services.
e.g., The RTC may be on a shared I2C bus which runtime services cannot
access
because it will conflict with the OS.
-If firmware does not support access to the RTC, then GetTime() and
-SetTime() shall return EFI_UNSUPPORTED,
+If an RTC is present, then GetTime() and SetTime() must be supported
+before ExitBootServices() is called.
+
+However, if firmware does not support access to the RTC after
+ExitBootServices(), then GetTime() and SetTime() shall return
EFI_UNSUPPORTED
and the OS must use a device driver to control the RTC.
UEFI Reset and Shutdown
@@ -209,9 +412,10 @@ ResetSystem() is required to be implemented in boot
services, but it is
optional for runtime services.
During runtime services, the operating system should first attempt to
use ResetSystem() to reset the system.
-If firmware doesn't support ResetSystem() during runtime services,
-then the call will immediately return EFI_UNSUPPORTED, and the OS should
-fall back to an architecture or platform specific reset mechanism.
+
+If firmware doesn't support ResetSystem() during runtime services, then
the call
+will immediately return, and the OS should fall back to an architecture or
+platform specific reset mechanism.
On AArch64 platforms implementing [PSCI]_,
if ResetSystem() is not implemented then the Operating System should fall
@@ -242,6 +446,26 @@ Even when SetVariable() is not supported during
runtime services, firmware
should cache variable names and values in EfiRuntimeServicesData memory so
that GetVariable() and GetNextVeriableName() can behave as specified.
+Firmware Update
+---------------
+
+Being able to update firmware to address security issues is a key
feature of secure platforms.
+EBBR platforms are required to implement either an in-band or an
out-of-band firmware update mechanism.
+
+If firmware update is performed in-band (firmware on the application
processor updates itself),
+then the firmware shall implement EFI_UPDATE_CAPSULE and accept updates
in the
+"Firmware Management Protocol Data Capsule Structure" format as
described in [UEFI]_ § 23.3,
+"Delivering Capsules Containing Updates to Firmware Management
Protocol. [#FMPNote]_
+Firmware is also required to provide an EFI System Resource Table
(ESRT). [UEFI]_ § 23.4
+Every firmware image that is updated in-band must be described in the ESRT.
+
+If firmware update is performed out-of-band (e.g., by an independent
Baseboard
+Management Controller (BMC), or firmware is provided by a hypervisor),
+then the platform is not required to implement EFI_UPDATE_CAPSULE.
+
+EFI_UPDATE_CAPSULE is only required before ExitBootServices() is called.
+
+
.. [#OPTEESupplicant] It is worth noting that OP-TEE has a similar problem
regarding secure storage.
OP-TEE's chosen solution is to rely on an OS supplicant agent to
perform
@@ -251,4 +475,12 @@ that GetVariable() and GetNextVeriableName() can
behave as specified.
Regardless, EBBR compliance does not require SetVariable() support
during runtime services.
-
https://github.com/OP-TEE/optee_os/blob/master/documentation/secure_storage…
+ https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
+
+.. [#FMPNote] The `EFI_UPDATE_CAPSULE` implementation is expected to be
suitable
+ for use by generic firmware update services like fwupd and Windows
Update.
+ Both fwupd and Windows Update read the ESRT table to determine what
firmware
+ can be updated, and use an EFI helper application to call
`EFI_UPDATE_CAPSULE`
+ before ExitBootServices() is called.
+
+ https://fwupd.org/
diff --git a/source/chapter4-firmware-media.rst
b/source/chapter4-firmware-media.rst
index fc71274..cfcc8bd 100644
--- a/source/chapter4-firmware-media.rst
+++ b/source/chapter4-firmware-media.rst
@@ -47,13 +47,19 @@ conflict with normal usage of the media by an OS.
Partitioning of Shared Storage
==============================
-A shared storage device shall use GPT partitioning unless it is
incompatible
-with the platform boot sequence.
-In which case, MBR partitioning shall be used. [#MBRReqExample]_
-
-.. [#MBRReqExample] For example, if the boot ROM doesn't understand GPT
- partitioning, and will only work with an MBR, then the storage must be
- partitioned using an MBR.
+The shared storage device must use the GUID Partition Table (GPT) disk
+layout as defined in [UEFI]_ § 5.3, unless the platform boot sequence is
+fundamentally incompatible with the GPT disk layout.
+In which case, a legacy Master Boot Recored (MBR) must be used.
+[#MBRReqExample]_
+
+.. [#MBRReqExample] For example, if the SoC boot ROM requires an MBR to
+ find the next stage firmware image, then it is incompatible with
+ the GPT boot layout.
+ Similarly, if the boot ROM expects the next stage firmware to be located
+ at LBA1 (the location of the GPT Header), then it is incompatible with
+ the GPT disk layout.
+ In both cases the shared storage device must use legacy MBR
partitioning.
.. warning::
@@ -62,7 +68,8 @@ In which case, MBR partitioning shall be used.
[#MBRReqExample]_
GPT partitioning supports a much larger number of partitions, and
has built in resiliency.
- A future issue of this specification will remove the MBR allowance.
+ A future issue of this specification will disallow the use of MBR
+ partitioning.
Firmware images and data in shared storage should be contained
in partitions described by the GPT or MBR.
@@ -71,15 +78,14 @@ the partition(s) containing firmware.
However, some SoCs load firmware from a fixed offset into the storage
media.
In this case, to protect against partitioning tools overwriting
firmware, the
-firmware image shall either reside entirely within the first 1MiB of
storage,
-or should be covered by a protective partition entry in the partition
table as
+partition table must be formed in a way to protect the firmware image(s) as
described in sections :ref:`section-gpt-parts` and
:ref:`section-mbr-parts`.
-Automatic partitioning tools (e.g. an OS installer) must not create
-partitions within the first 1MiB of storage, or delete, move, or modify
-protective partition entries.
+Automatic partitioning tools (e.g. an OS installer) must not
+delete the protective information in the partition table, or
+delete, move, or modify protective partition entries.
Manual partitioning tools should provide warnings when modifying
-protective partitions or creating partitions within the first 1MiB.
+protective partitions.
.. warning::
@@ -95,19 +101,49 @@ GPT partitioning
----------------
The partition table must strictly conform to the UEFI specification
and include
-a protective MBR authored exactly as described in [UEFI]_ § 5 (hybrid
+a protective MBR authored exactly as described in [UEFI]_ § 5.3 (hybrid
partitioning schemes are not permitted).
-Protective partitions must have the Platform Required Attribute Flag set.
+Fixed-location firmware images must be protected by creating protective
+partition entries, or by placing GPT data structures away from the LBAs
+occupied by firmware,
+
+Protective partitions are entries in the partition table that cover the
+LBA region occupied by firmware and have the 'Required Partition' attribute
+set.
+A protective partition must use a `PartitionTypeGUID` that identifies it
+as a firmware protective partition. (e.g., don't reuse a GUID used by
+non-protective partitions).
+There are no requirements on the contents or layout of the firmware
+protective partition.
+
+Placing GPT data structures away from firmware images can be
accomplished by
+adjusting the GUID Partition Entry array location
+(adjusting the values of `PartitionEntryLBA` and
`NumberOfPartitionEntries`,
+and `SizeOfPartitionEntry`),
+or by specifying the usable LBAs (Choosing `FirstUsableLBA`/`LastUsableLBA`
+to not overlap the fixed firmware location).
+See [UEFI]_ § 5.3.2.
+
+Given the choice, platforms should use protective partitions over
+adjusting the placement of GPT data structures because protective
partitions
+provide explicit information about the protected region.
.. _section-mbr-parts:
MBR partitioning
^^^^^^^^^^^^^^^^
-Protective partitions should have a partition type of 0xF8 unless some
+If firmware is at a fixed location entirely within the first 1MiB of
+storage (<= LBA2047) then no protective partitions are required.
+If firmware resides in a fixed location outside the first 1MiB,
+then a protective partition must be used to cover the firmware LBAs.
+Protective partitions should have a partition type of 0xF8 unless an
immutable feature of the platform makes this impossible.
+OS partitioning tools must not create partitions in the first 1MiB
+of the storage device, and must not remove protective partitions.
+
.. _section-fw-partition-fs:
Firmware Partition Filesystem
@@ -202,7 +238,7 @@ and cannot be moved between systems.
eMMC and Universal Flash Storage (UFS) device are often used as
shared fixed storage for both firmware and the OS.
-Where possible, it is prefered for the system to boot from a dedicated boot
+Where possible, it is preferred for the system to boot from a dedicated
boot
region on media that provides one (e.g., eMMC) that is sufficiently large.
Otherwise, the platform storage should be pre-formatted in the factory
with
a partition table, a dedicated firmware partition, and firmware binaries
diff --git a/source/conf.py b/source/conf.py
index 86f7b88..4a2566a 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -100,7 +100,7 @@ html_theme = 'alabaster'
# Add any paths that contain custom static files (such as style
sheets) here,
# relative to this directory. They are copied after the builtin static
files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
# -- Options for HTMLHelp output
------------------------------------------
diff --git a/source/index.rst b/source/index.rst
index 8eab909..bf2dadf 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -21,35 +21,34 @@ Creative Commons, PO Box 1866, Mountain View, CA
94042, USA.
.. tabularcolumns:: l c p{11.5cm}
.. table:: Revision History
- ================= =========
=============================================
- Date Issue Changes
- ================= =========
=============================================
- 20 September 2017 0.51 Confidentiality Change, EBBR version 0.51
- 6 July 2018 0.6-pre1 - Relicense to CC-BY-SA 4.0
- - Added Devicetree requirements
- - Added Multiprocessor boot requirements
- - Transitioned to reStructuredText and
GitHub
- - Added firmware on shared media
requirements
- - RTC is optional
- - Add constraints on sharing devices between
- firmware and OS
- 12 July 2018 0.6 - Response to comments on v0.6-pre1
- - Add large note on implementation of
runtime
- modification of non-volatile variables
- 18 October 2018 0.7 - Add AArch32 details
- - Refactor Runtime Services text after face
- to fact meeting at Linaro Connect YVR18
- 12 March 2019 0.8 - Update language around SetVariable() and
- what is available during runtime services
- - Editorial changes preparing for v1.0
- 31 March 2019 1.0 - Remove unnecessary UEFI requirements
- appendix
- - Allow for ACPI vendor id in firmware path
- 5 August 2020 1.0.1 - Update to UEFI 2.8 Errata A
- - Specify UUID for passing DTB
- - Typo and editorial fixes
- - Document the release process
- ================= =========
=============================================
+ ============= ======= =============================================
+ Date Issue Changes
+ ============= ======= =============================================
+ 20 Sep 2017 0.51 - Confidentiality Change, EBBR version 0.51
+ 12 Jul 2018 0.6 - Relicense to CC-BY-SA 4.0
+ - Added Devicetree requirements
+ - Added Multiprocessor boot requirements
+ - Transitioned to reStructuredText and GitHub
+ - Added firmware on shared media requirements
+ - RTC is optional
+ - Add constraints on sharing devices between
+ firmware and OS
+ - Add large note on implementation of runtime
+ modification of non-volatile variables
+ 18 Oct 2018 0.7 - Add AArch32 details
+ - Refactor Runtime Services text after face
+ to fact meeting at Linaro Connect YVR18
+ 12 Mar 2019 0.8 - Update language around SetVariable() and
+ what is available during runtime services
+ - Editorial changes preparing for v1.0
+ 31 Mar 2019 1.0 - Remove unnecessary UEFI requirements
+ appendix
+ - Allow for ACPI vendor id in firmware path
+ 5 Aug 2020 1.0.1 - Update to UEFI 2.8 Errata A
+ - Specify UUID for passing DTB
+ - Typo and editorial fixes
+ - Document the release process
+ ============= ======= =============================================
.. toctree::
:numbered:
diff --git a/source/references.rst b/source/references.rst
index 1eb0509..fb7dc81 100644
--- a/source/references.rst
+++ b/source/references.rst
@@ -1,5 +1,11 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. only:: html
+
+ ************
+ Bibliography
+ ************
+
.. [ACPI] `Advanced Configuration and Power Interface specification v6.2A
<http://www.uefi.org/sites/default/files/resources/ACPI%206_2_A_Sept29.pdf>`_,
September 2017, `UEFI Forum <http://www.uefi.org>`_
@@ -16,9 +22,9 @@
<https://static.docs.arm.com/den0022/c/DEN0022C_Power_State_Coordination_Int…>`_
30 January 2015, `Arm Limited <http://arm.com>`_
-.. [SBBR] `Arm Server Base Boot Requirements specification Issue B (v1.0)
-
<https://static.docs.arm.com/den0044/b/DEN0044B_Server_Base_Boot_Requirement…>`_
- 8 March 2016, `Arm Limited <http://arm.com>`_
+.. [ArmBBR] `Arm Base Boot Requirements specification Issue F (v1.0)
+ <https://developer.arm.com/documentation/den0044/f>`_
+ 6 Oct 2020, `Arm Limited <http://arm.com>`_
.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8
Errata A
<https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_,
SBBR has been superseded by Arm BBR. Update the about section to
reference BBR instead. However, none of the specification language
changes because EBBR has a relaxed set of UEFI requirements compared to
BBR.
Fixes: #62
Signed-off-by: Grant Likely <grant.likely(a)secretlab.ca>
---
source/chapter1-about.rst | 19 ++++++++-----------
source/references.rst | 6 +++---
2 files changed, 11 insertions(+), 14 deletions(-)
diff --git a/source/chapter1-about.rst b/source/chapter1-about.rst
index 68a1abc..6f69f53 100644
--- a/source/chapter1-about.rst
+++ b/source/chapter1-about.rst
@@ -146,17 +146,14 @@ including services that are required for virtualization.
It does not define a standardized abstract virtual machine view for a Guest
Operating System.
-This specification is similar to the Arm Server Base Boot Requirements
-specification [SBBR]_ in that it defines the firmware interface presented to an
-operating system.
-SBBR is targeted at the server ecosystem and places strict requirements on the
-platform to ensure cross vendor interoperability.
-EBBR on the other hand allows more flexibility to support embedded designs
-which do not fit within the SBBR model.
-For example, a platform that isn't SBBR compliant because the SoC is only
-supported using Devicetree could be EBBR compliant, but not SBBR compliant.
-
-By definition, all SBBR compliant systems are also EBBR compliant, but the
+This specification is referenced by the Arm Base Boot Requirements
+Specification [ArmBBR]_ § 4.3.
+The UEFI requirements found in this document are similar but not identical to
+the requirements found in BBR.
+EBBR provides greater flexibility for support embedded designs which cannot
+easily meet the stricter BBR requirements.
+
+By definition, all BBR compliant systems are also EBBR compliant, but the
converse is not true.
Conventions Used in this Document
diff --git a/source/references.rst b/source/references.rst
index d91dc08..fb7dc81 100644
--- a/source/references.rst
+++ b/source/references.rst
@@ -22,9 +22,9 @@
<https://static.docs.arm.com/den0022/c/DEN0022C_Power_State_Coordination_Int…>`_
30 January 2015, `Arm Limited <http://arm.com>`_
-.. [SBBR] `Arm Server Base Boot Requirements specification Issue B (v1.0)
- <https://static.docs.arm.com/den0044/b/DEN0044B_Server_Base_Boot_Requirement…>`_
- 8 March 2016, `Arm Limited <http://arm.com>`_
+.. [ArmBBR] `Arm Base Boot Requirements specification Issue F (v1.0)
+ <https://developer.arm.com/documentation/den0044/f>`_
+ 6 Oct 2020, `Arm Limited <http://arm.com>`_
.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A
<https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_,
--
2.20.1
All,
Here are my notes from today. Please correct anything I got wrong.
Attendees:
Bruce Ashfield
Frank Rowand
Simon Glass
Etienne Carriere
Heinrich Schuchardt
Ilias Apalodimas
Joakim Bech
Loic Pallardy
Mark Brown
Mathieu Poirier
Rob Herring
Ruchika Gupta
Vincent Guittot
Vincent Stehle
CC:
Stefano Stabellini
Kumar Gala
Discussion:
Today we did a brainstorming session on goals/requirements for a new DTB
format.
Remember this is a laundry list of requirements / concerns. Not all will
necessarily be included in the new format but all will be considered.
It is not a discussion of the format changes to achieve these goals.
Frank Rowand will be collecting past discussions related to this and
expects this to be ready for the meeting on March 22.
* FR: Reduce Size
* FR: Overlay support in "symbol table" not looking like HW description
* FR: Ability to express "delete node" and "delete property"
** many: do we really need delete node, every node should have status
** RH: not everyone today looks for status != ok
** general agreement that they should
** RH: perhaps we should make it more automatic somehow
* SG: New format should be little endian
** most current active / popular CPU arch are LE these days
* SG: Ability to refer to data blob by reference instead of inline
** blob would still be in DTB file/image
but not inline as a property blob
* RH: Include type info
** Know what is a u64 vs u32 vs phandle
** replicate what we have in schema with bit fields etc
** enums?? structs??
* SG: Provision for comments
* RH: In general want more less conversion DTS -> DTB -> DTS
** WAM: Is it OK to rely on schema?
** SG: Ideally not, would prefer self describing format
* HS: Want to be able to validate DTB (against schema)
** WAM: Isnt this the same as type info?
** RH: That is a lot of it but there is more
* WAM: We want a new section for meta data
** WAM: signatures as discussed on this call
** FR: Source file info / version markers
** HS/WAM: taint flag if the DTC compile or validate is not clean
* SG: IN yaml we can import a node,
** would be good to have this in DTS as well
** FR: It is valid to bring in DTS requirements as some of this
will effect anyway
* WAM: Segmeneted DTB or DTB set
** instead of applying overlays leave base and overlay intact
** deliver to OS as a set with assembly order.
** [We can call it IKEA mode :) ]
** allows signatures to reamin valid, can be passed on
** makes it clear what fixups were performed by the firmware
* SG: a previous node "pointer"
** going backwards is very slow in FDT
* WAM: Huawei is asking for B-Tree to speed up search in FDT
** FR/RH: probably too far but we will consider
* RH: DTB format could be unflattened
** SG: could be too big
** SG: we may really need more than one format to balance speed vs size
** [WAM: learns that libfdt does not unflatten.
U-boot copies Linux code for this.]
** RH: we could have a libdt that would be lib for live trees
* SG: for speed it would be nice to have a directory for quick access
** WAM: improved alias? SG: Yes if they were phandles perhaps
* WAM: Can we revist size, that is pretty broad
** Eliminate as many strings as possible
** FR: Compiler does "tail recursion" on strings already
** WAM: strings in properties are not in symbold table today
** SG: Yes I studied that and elimination of that did not help a lot.
** SG: Today everything is 32 bit
*** I looked at reducing and could save 20%
*** But it is not as regular
*** WAM: is it aligned today?
*** RH: Yes, 64 bit aligned but not very clear in spec
** HS: Just gzip the DTB if you just want to reduce storage size
** WAM: Published ATOM based DTB doc a few years ago.
*** Try to move most strings to 32 bit ATOM constants (not offsets)
*** Optionally include ATOM table to include the strings
Devicetree Atom Table Format:
https://docs.google.com/document/d/19XbxN-zX-GYwOXdF78lGnp0j7UNx1MT3wzyCjai…
Frank reminds us that we want to collect all the stake holders:
* Linux
* DTC
* U-Boot
* BSDs
** One has its own DTC
* RTOS
** Zephyr (mostly DTS)
*** Have their own DTS parser, DOM lib, and code gen
*** Want to make it more generic
** Vxworks (does use runtime DT of some sort)
All agree: Old DTB format will need to be supported for a good while
after new DTB format is defined.
Thanks,
Bill
--
Bill Mills
Principal Technical Consultant, Linaro
+1-240-643-0836
TZ: US Eastern
Work Schedule: Tues/Wed/Thur
Hello,
We have our DTE call today.
I don't have anything on the agenda unless we want to brainstorm on the
DTB format changes.
I know Frank is trying to collect/organize past work on this. Is it
worth while talking today or should we wait for Frank?
Open to any other agenda items.
Join Zoom Meeting
https://linaro-org.zoom.us/j/96170428801?pwd=elBJNFdVMFJub0UzanFUcVQxTHBqdz…
Meeting ID: 961 7042 8801
Passcode: 8250
------
A note on timezones.
This meeting is now anchored to the UK timezone to match the EBBR call.
UK goes to Daylight savings on March 28
Most of the USA goes to Daylight savings on March 14.
This means:
UK:
no visible change in time slot.
USA (most):
Meeting on 22nd will be one hour later.
(and EBBR meeting on 15th)
Non-daylight savings time zones:
DTE and EBBR meetings are 1 hour earlier
from March 28 to Oct 31.
Thanks,
Bill
--
Bill Mills
Principal Technical Consultant, Linaro
+1-240-643-0836
TZ: US Eastern
Work Schedule: Tues/Wed/Thur
Hi,
An arch agnostic way was recently added on the kernel, as an alternative method
to load an initrd [1]. The kernel call to the firmware ends up calling the
protocol with a Device Path End Structure, so the firmware must know which
initrd to load on the buffer the kernel provides.
The protocol is currently implemented by U-boot and EDK2, which both
define a way of specifying the initrd to load. We could use this protocol,
in order to provide vertical distros a way of loading (kernel, initrd) pairs
without GRUB. In that case we need a common way for firmware implementations
to define and manage the initrd. User space applications that control the boot
flow (e.g efibootmgr), should also be able to change the variable accordingly.
Looking at the EFI spec and specifically § 3.1.3 Load Options, we can use the
FilePathList[] of the EFI_LOAD_OPTION, which is described as:
"A packed array of UEFI device paths. The first element of the array is a
device path that describes the device and location of the Image for this
load option. The FilePathList[0] is specific to the device type. Other device
paths may optionally exist in the FilePathList, but their usage is OSV specific.
Each element in the array is variable length, and ends at the device path end
structure. Because the size of Description is arbitrary, this data structure
is not guaranteed to be aligned on a natural boundary. This data structure may
have to be copied to an aligned natural boundary before it is used."
So FilePatrhList[1-n] are available for OS usage. There are 3 ways we could
implement that. All 3 ways would allow us to specify multiple initrds (and we
could extend the same logic to DTBs, but that's a different discussion).
They all re-use the same idea, prepend a VenMedia DP, which has a GUID. We can
then use that GUID to identify the filetype and behavior of the device paths.
1. Prepend a VenMedia Device Path in every initrd Device Path. In that case
FilePathList[] would look like this:
Loaded Image device path - end node - VenMedia - Initrd DP - end node
- VenMedia - Initrd DP - end node - repeat
2. Prepend a VenMedia Device Path once. In that case FilePathList[] would look
like this:
Loaded Image device path - end node - VenMedia - Initrd DP - end
instance - (repeat) - Initrd DP - end node - other DPs
In this case we could use the VenMedia Vendor Defined Data to indicate
the number
of device paths that follow, although it's redundant, since each instance would
terminate on the Device Path End Structure.
3. Use Vendor Defined Data of the VenMedia device path and copy the initrd
device path(s) in there. In that case the Vendor Defined Data will it self
be in a device path format with all the initrds we want.
Loaded Image device path - end node - VenMedia - end node - other DPs
Any preference on these?
Is one of them closer to the EFI spec, so we could go ahead and try to
standardize some of the GUIDs of the VenMedia?
[1] https://lkml.org/lkml/2020/2/16/105
Regards
/Ilias
