Skip to content

Commit

Permalink
trivial: wrap lines above 80 characters
Browse files Browse the repository at this point in the history 
Add a word about this limit in the README.

Signed-off-by: Vincent Stehlé <[email protected]>
  • Loading branch information
@vstehle
vstehle committed Mar 6, 2024
1 parent f2c68ed commit 2798117
Show file tree
Hide file tree
Showing 3 changed files with 76 additions and 53 deletions.
10 changes: 7 additions & 3 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,9 @@ On Debian and Ubuntu
--------------------
::

# apt-get install python3-sphinx texlive texlive-latex-extra libalgorithm-diff-perl \
texlive-humanities texlive-generic-recommended texlive-generic-extra \
# 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
Expand All @@ -58,7 +59,8 @@ new version can be installed with the Python package installer::
$ pip3 install --user --upgrade Sphinx
$ export SPHINXBUILD=~/.local/bin/sphinx-build

Export SPHINXBUILD (see above) if Sphinx was installed with pip3 --user, then follow Make commands below.
Export SPHINXBUILD (see above) if Sphinx was installed with pip3 --user,
then follow Make commands below.

**Note**: the ``.github/workflows/main.yaml`` CI configuration file installs the
necessary dependencies for Ubuntu and can be used as an example.
Expand Down Expand Up @@ -150,6 +152,8 @@ tag. Generally this means each ``.rst`` file should include the line
.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _Sphinx: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

In general, try to keep the text width to at most 80 columns.

Sphinx Extensions
-----------------

Expand Down
52 changes: 30 additions & 22 deletions source/chapter1-about.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ For example, an Arm A-class embedded platform will benefit
from a standard interface that supports features such as secure boot and
firmware update.

This specification defines the base firmware requirements for EBBR compliant platforms.
This specification defines the base firmware requirements for EBBR compliant
platforms.
The requirements in this specification are expected to be minimal yet complete,
while leaving plenty of room for innovations and design details.
This specification is intended to be OS-neutral.
Expand All @@ -35,9 +36,11 @@ Using the assumption that better understanding of the thought process behind
EBBR will result in better implementations, this section is a discussion of the
goals and guiding principle that shaped EBBR.

This section should be considered commentary, and not a formal part of the specification.
This section should be considered commentary, and not a formal part of the
specification.

EBBR was written as a response to the lack of boot sequence standardization in the embedded system ecosystem.
EBBR was written as a response to the lack of boot sequence standardization in
the embedded system ecosystem.
As embedded systems are becoming more sophisticated and connected,
it is becoming increasingly important for embedded systems to run standard OS
distributions and software stacks, or to have consistent behaviour across a
Expand Down Expand Up @@ -70,7 +73,8 @@ ensure that the EBBR requirements are implemented by both projects.
U-Boot is the incumbent firmware project for embedded platforms and has
steadily been adding UEFI compliance since 2016.
The following guiding principles are used while developing the EBBR specification.
The following guiding principles are used while developing the EBBR
specification.

- Be agnostic about ACPI and Devicetree.

Expand Down Expand Up @@ -117,7 +121,8 @@ The following guiding principles are used while developing the EBBR specificatio
Generally anything that has a near-upstream U-Boot implementation should be
able to implement the EBBR requirements.
EBBR was drafted with readily available hardware in mind, like the
Raspberry Pi and BeagleBone families of boards, and it is applicable for low cost boards (<$10).
Raspberry Pi and BeagleBone families of boards, and it is applicable for low
cost boards (<$10).

- Plan to evolve over time

Expand Down Expand Up @@ -246,20 +251,20 @@ AARCH64
Execution state provides a single instruction set, A64.

EL0
The lowest Exception level on AArch64. The Exception level that is used to execute
user applications, in Non-secure state.
The lowest Exception level on AArch64. The Exception level that is used
to execute user applications, in Non-secure state.

EL1
Privileged Exception level on AArch64. The Exception level that is used to execute
Operating Systems, in Non-secure state.
Privileged Exception level on AArch64. The Exception level that is used
to execute Operating Systems, in Non-secure state.

EL2
Hypervisor Exception level on AArch64. The Exception level that is used to execute
hypervisor code. EL2 is always in Non-secure state.
Hypervisor Exception level on AArch64. The Exception level that is used
to execute hypervisor code. EL2 is always in Non-secure state.

EL3
Secure Monitor Exception level on AArch64. The Exception level that is used to
execute Secure Monitor code, which handles the transitions between
Secure Monitor Exception level on AArch64. The Exception level that is
used to execute Secure Monitor code, which handles the transitions between
Non-secure and Secure states. EL3 is always in Secure state.

RISC-V
Expand All @@ -268,12 +273,12 @@ RISC-V
.. glossary::

HART
Hardware thread in RISC-V. This is the hardware execution context that contains
all the state mandated by the ISA.
Hardware thread in RISC-V. This is the hardware execution context that
contains all the state mandated by the ISA.

HSM
Hart State Management (HSM) is an SBI extension that enables the supervisor
mode software to implement ordered booting.
Hart State Management (HSM) is an SBI extension that enables the
supervisor mode software to implement ordered booting.

HS Mode
Hypervisor-extended-supervisor mode which virtualizes the supervisor mode.
Expand All @@ -292,17 +297,20 @@ RISC-V
64 bit execution mode in RISC-V.

RISC-V Supervisor Binary Interface (SBI)
Supervisor Binary Interface. This is an interface between SEE and supervisor
mode in RISC-V.
Supervisor Binary Interface. This is an interface between SEE and
supervisor mode in RISC-V.

SEE
Supervisor Execution Environment in RISC-V. This can be M mode or HS mode.

S Mode
Supervisor mode is the next privilege mode after M mode where virtual memory is enabled.
Supervisor mode is the next privilege mode after M mode where virtual
memory is enabled.

U Mode
User mode is the least privilege mode where user-space application is expected to run.
User mode is the least privilege mode where user-space application is
expected to run.

VS Mode
Virtualized supervisor mode where the guest OS is expected run when hypervisor is enabled.
Virtualized supervisor mode where the guest OS is expected run when
hypervisor is enabled.
67 changes: 39 additions & 28 deletions source/chapter2-uefi.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,22 +131,25 @@ interface specific UEFI protocols, and so they have been made optional.
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.
- 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.
- 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.
- 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.
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.
- 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
Expand Down Expand Up @@ -222,10 +225,11 @@ processing after restart as found in :UEFI:`8.5.6`. [#FWUpNote]_
Block device partitioning
-------------------------

The system firmware must implement support for MBR, GPT and El Torito partitioning
on block devices.
System firmware may also implement other partitioning methods as needed by the platform,
but OS support for other methods is outside the scope of this specification.
The system firmware must implement support for MBR, GPT and El Torito
partitioning on block devices.
System firmware may also implement other partitioning methods as needed by the
platform, but OS support for other methods is outside the scope of this
specification.

UEFI System Environment and Configuration
=========================================
Expand All @@ -238,7 +242,8 @@ Resident UEFI firmware might target a specific privilege level.
In contrast, UEFI Loaded Images, such as third-party drivers and boot
applications, must not contain any built-in assumptions that they are to be
loaded at a given privilege level during boot time since they can, for example,
legitimately be loaded into either EL1 or EL2 on AArch64 and HS/VS/S mode on RISC-V.
legitimately be loaded into either EL1 or EL2 on AArch64 and HS/VS/S mode on
RISC-V.

AArch64 Exception Levels
------------------------
Expand All @@ -265,7 +270,8 @@ virtualized service, by the hypervisor and not as part of the host firmware.
RISC-V Privilege Levels
-----------------------

RISC-V doesn't define dedicated privilege levels for hypervisor enabled platforms.
RISC-V doesn't define dedicated privilege levels for hypervisor enabled
platforms.
The supervisor mode becomes HS mode where a hypervisor or a hosting-capable
operating system runs while the guest OS runs in virtual S mode (VS mode).
Resident UEFI firmware can be executed in M mode or S/HS mode during POST.
Expand All @@ -281,16 +287,19 @@ is not enabled [RVPRIVSPEC]_.
UEFI Boot at HS mode
^^^^^^^^^^^^^^^^^^^^

Any platform supporting the hypervisor extension enabled most likely will boot UEFI at HS mode,
to allow for the installation of a hypervisor or a virtualization aware Operating System.
Any platform supporting the hypervisor extension enabled most likely will boot
UEFI at HS mode, to allow for the installation of a hypervisor or
a virtualization aware Operating System.

UEFI Boot at VS mode
^^^^^^^^^^^^^^^^^^^^

Booting of UEFI at VS mode is employed within a hypervisor hosted Guest Operating System environment,
to allow the subsequent booting of a UEFI-compliant Operating System.
Booting of UEFI at VS mode is 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 virtualized service, by the hypervisor and not as part of the host firmware.
as a virtualized service, by the hypervisor and not as part of the host
firmware.

UEFI Configuration Tables
=========================
Expand Down Expand Up @@ -397,8 +406,8 @@ UEFI Secure Boot (Optional)

UEFI Secure Boot is optional for this specification.

If Secure Boot is implemented, it must conform to the UEFI specification for Secure Boot. There are no additional
requirements for Secure Boot.
If Secure Boot is implemented, it must conform to the UEFI specification for
Secure Boot. There are no additional requirements for Secure Boot.

UEFI Runtime Services
=====================
Expand Down Expand Up @@ -500,8 +509,8 @@ 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.
`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
-----------------------
Expand All @@ -511,8 +520,8 @@ 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, and the OS should fall back to an architecture or
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]_,
Expand Down Expand Up @@ -560,8 +569,10 @@ that `GetVariable()` and `GetNextVariableName()` 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.
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.

In-band firmware update
^^^^^^^^^^^^^^^^^^^^^^^
Expand Down

0 comments on commit 2798117

Please sign in to comment.