[RFC PATCH 0/1] ref-manual: add boot architecture documentation

[RFC PATCH 0/1] ref-manual: add boot architecture documentation

[Jon Mason]

This RFC adds documentation to the Yocto Project for the hardware boot flow, the software components involved in that flow, and the proposed variables used to prevent invalid combinations of mutually exclusive boot software components.

This documentation is intended to provide common background and context in the Yocto Project for the associated software selections and variable usage.

This RFC is documentation-only so I can get feedback on the description, terminology, and overall approach before sending the full implementation.  I plan to send a full patch series that includes
this documentation along with the corresponding recipe and variable changes for the relevant software components after addressing any feedback.

Comments on the content, naming, and placement would be appreciated.

Thanks,
Jon

Jon Mason (1):
  ref-manual: add boot architecture documentation

 .../ref-manual/boot-architecture.rst          | 361 ++++++++++++++++++
 documentation/ref-manual/index.rst            |   1 +
 2 files changed, 362 insertions(+)
 create mode 100644 documentation/ref-manual/boot-architecture.rst

-- 
2.50.1 (Apple Git-155)

[RFC PATCH 1/1] ref-manual: add boot architecture documentation

[Jon Mason]

Add a new documentation page describing the firmware and bootloader
architecture used by systems built with the Yocto Project across
multiple processor architectures.

The document explains the typical boot stages (Boot ROM, platform
firmware, system firmware, and OS loader) and provides example boot
flows for Arm, Arm64, RISC-V, and x86 systems.

Signed-off-by: Jon Mason <jon.mason@arm.com>
---
 .../ref-manual/boot-architecture.rst          | 361 ++++++++++++++++++
 documentation/ref-manual/index.rst            |   1 +
 2 files changed, 362 insertions(+)
 create mode 100644 documentation/ref-manual/boot-architecture.rst

diff --git a/documentation/ref-manual/boot-architecture.rst b/documentation/ref-manual/boot-architecture.rst
new file mode 100644
index 000000000000..e801e0a402d5
--- /dev/null
+++ b/documentation/ref-manual/boot-architecture.rst
@@ -0,0 +1,361 @@
+Boot Architecture and Firmware Components
+=========================================
+
+This document describes the firmware and boot architecture used by
+systems built with the Yocto Project across several processor
+architectures:
+
+* Arm (Arm32)
+* Arm64 (AArch64)
+* RISC-V
+* x86 / x86_64
+
+Understanding the firmware chain is important when configuring Yocto
+Project builds because multiple software components can fulfill the
+same role in the boot process. These components are often mutually
+exclusive and are typically selected through BitBake providers or
+machine configuration.
+
+
+Boot Process Overview
+---------------------
+
+Most systems boot through a sequence of stages that progressively
+initialize the hardware and load the operating system. Control typically
+passes from more privileged and trusted stages to less privileged ones.
+
+::
+
+   Boot ROM
+      ↓
+   Platform Firmware
+      ↓
+   System Firmware
+      ↓
+   OS Loader (optional)
+      ↓
+   Operating System
+
+
+Boot ROM
+--------
+
+Boot ROM is the first code executed when a processor starts. It is
+typically implemented by the CPU or SoC manufacturer and stored in
+on-chip read-only memory.
+
+Boot ROM performs minimal initialization and loads the next stage of
+firmware from boot media such as SPI flash, eMMC, or SD storage.
+
+Boot ROM code is generally **not modifiable by system developers**.
+
+
+Platform Firmware
+-----------------
+
+Platform firmware performs early platform initialization before the
+main boot firmware executes. Depending on the architecture and
+implementation, it may configure security boundaries, initialize memory
+and clocks, provide management-controller functions, or expose
+privileged runtime services used later by the operating system.
+
+Some parts of this layer may remain resident after boot. Platform
+firmware is usually platform-specific and typically has fewer
+interchangeable implementations than later boot stages.
+
+Examples include:
+
+* Trusted Firmware-A (TF-A)
+* Trusted Firmware-M (TF-M), where applicable
+* System Control Processor (SCP) firmware
+* OpenSBI, which implements the Supervisor Binary Interface (SBI)
+
+
+System Firmware
+---------------
+
+System firmware provides the main boot environment. It prepares the
+hardware needed to load the next stage, discovers bootable devices,
+and may provide a command shell or a UEFI environment. Many modern
+implementations can also boot the kernel directly from storage,
+making a separate OS loader optional.
+
+This layer is generally modifiable by system developers and often
+has alternative implementations.
+
+Typical implementations include:
+
+* U-Boot
+* EDK2
+* coreboot
+
+In Yocto Project builds this layer can be selected through a virtual
+provider using ``PREFERRED_PROVIDER``.
+
+The name ``virtual/boot-firmware`` reflects the role of this layer as
+the primary firmware environment responsible for locating bootable
+devices and initiating the operating system boot process.
+
+Example configuration::
+
+   PREFERRED_PROVIDER_virtual/boot-firmware = "u-boot"
+
+
+OS Loader
+---------
+
+The OS loader is the final stage that typically resides on disk. It
+selects and loads a specific operating system kernel and optional
+initramfs into memory and passes the required configuration to start
+the system.
+
+This layer is modifiable by system developers and usually has multiple
+implementations.
+
+Examples include:
+
+* GRUB
+* Syslinux / EXTLINUX
+* systemd-boot
+
+In Yocto Project builds this layer can also be selected through a
+virtual provider.
+
+The name ``virtual/boot-manager`` reflects the role of this software in
+selecting and loading an operating system kernel from storage.
+
+Example configuration::
+
+   PREFERRED_PROVIDER_virtual/boot-manager = "grub-efi"
+
+Some systems boot the kernel directly from system firmware (for example
+U-Boot or UEFI). In these cases an additional OS loader is not required.
+
+Example::
+
+   PREFERRED_PROVIDER_virtual/boot-manager = "none"
+
+
+Boot Process by Architecture
+----------------------------
+
+
+Arm (Arm32)
+~~~~~~~~~~~
+
+Many Arm32 systems boot directly into U-Boot using its SPL stage.
+
+::
+
+   Boot ROM
+      ↓
+   U-Boot SPL
+      ↓
+   U-Boot
+      ↓
+   Linux Kernel
+
+
+Arm64 (AArch64)
+~~~~~~~~~~~~~~~
+
+Arm64 platforms commonly include Trusted Firmware-A prior to the
+main boot firmware.
+
+::
+
+   Boot ROM
+      ↓
+   TF-A BL1 / BL2 / BL31
+      ↓
+   U-Boot or EDK2
+      ↓
+   OS Loader or Linux Kernel
+
+When a separate OS loader is used, it is typically GRUB or
+systemd-boot.
+
+
+RISC-V
+~~~~~~
+
+RISC-V systems typically include OpenSBI, which provides the
+Supervisor Binary Interface (SBI).
+
+::
+
+   Boot ROM
+      ↓
+   OpenSBI
+      ↓
+   U-Boot or EDK2
+      ↓
+   OS Loader or Linux Kernel
+
+When a separate OS loader is used, it is typically GRUB or
+systemd-boot.
+
+
+x86 / x86_64
+~~~~~~~~~~~~
+
+Typical x86 systems use platform firmware implementing BIOS
+compatibility or UEFI.
+
+::
+
+   CPU reset vector (firmware entry point)
+      ↓
+   Platform Firmware (BIOS / UEFI, for example coreboot- or EDK2-based firmware)
+      ↓
+   GRUB or systemd-boot
+      ↓
+   Linux Kernel
+
+
+Security Considerations
+-----------------------
+
+Secure Boot
+~~~~~~~~~~~
+
+Secure Boot ensures that only software verified by a trusted key can
+execute during the boot process.
+
+Each stage verifies the integrity and authenticity of the next stage
+before transferring control. Verification is typically performed using
+digital signatures and public-key cryptography.
+
+The process begins with a hardware root of trust, often implemented in
+Boot ROM or secure firmware, which contains the keys used to verify
+subsequent boot stages.
+
+A simplified Secure Boot chain may look like this::
+
+   Boot ROM (Root of Trust)
+      ↓
+   Platform Firmware
+      ↓
+   System Firmware
+      ↓
+   OS Loader
+      ↓
+   Linux Kernel
+
+If verification fails at any stage, execution is typically halted or
+recovery mechanisms are triggered.
+
+Common Secure Boot mechanisms include:
+
+* Firmware signature verification
+* Signed bootloader images
+* Signed kernel images
+* UEFI Secure Boot
+* U-Boot FIT image verification
+
+In Yocto Project builds Secure Boot is commonly implemented using:
+
+* U-Boot verified boot (FIT image signatures)
+* UEFI Secure Boot with EDK2
+* Trusted Firmware-A verified boot
+
+
+Trusted Boot
+~~~~~~~~~~~~
+
+Trusted Boot focuses on *measuring* the boot process rather than
+preventing execution.
+
+Instead of blocking execution, Trusted Boot records cryptographic
+measurements (typically hashes) of boot components as they are loaded.
+These measurements are stored in a Trusted Platform Module (TPM) or
+other protected storage.
+
+A simplified measurement chain may look like this::
+
+   Boot ROM
+      ↓
+   Measure Platform Firmware
+      ↓
+   Measure Bootloader
+      ↓
+   Measure Kernel
+      ↓
+   Store measurements in TPM
+
+Measurements are extended into Platform Configuration Registers (PCRs)
+in the TPM and can later be used to verify system integrity.
+
+Trusted Boot enables capabilities such as:
+
+* Remote attestation
+* Platform integrity verification
+* Measured boot logging
+* Runtime integrity checking
+
+Trusted Boot does **not necessarily prevent execution of untrusted
+software**, but provides a verifiable record of what software was
+loaded during boot.
+
+
+Secure Boot and Trusted Boot Together
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many systems combine Secure Boot and Trusted Boot to provide both
+enforcement and measurement.
+
+For example::
+
+   Boot ROM
+      ↓
+   Verify Platform Firmware
+      ↓
+   Measure Platform Firmware
+      ↓
+   Verify Bootloader
+      ↓
+   Measure Bootloader
+      ↓
+   Verify Kernel
+      ↓
+   Measure Kernel
+
+This approach both prevents unauthorized code from running and
+provides an auditable record of the boot process.
+
+
+Yocto Project Integration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Yocto Project can be used to build systems that implement Secure
+Boot and Trusted Boot through several layers and components.
+
+Examples include:
+
+* Secure Boot support in U-Boot
+* UEFI Secure Boot with EDK2
+* Trusted Firmware-A verified boot support
+* TPM integration
+* Linux Integrity Measurement Architecture (IMA)
+* Extended Verification Module (EVM)
+
+These features can be enabled and configured using machine
+configurations, distribution features, and additional layers such as
+security-focused metadata layers.
+
+
+References
+----------
+
+* `Boot Loader Specification <https://systemd.io/BOOT_LOADER_SPECIFICATION/>`_
+* `Coreboot <https://doc.coreboot.org/>`_
+* `EDK2 <https://github.com/tianocore/edk2>`_
+* `GNU GRUB <https://www.gnu.org/software/grub/>`_
+* `IMA/EVM <https://sourceforge.net/p/linux-ima/wiki/Home/>`_
+* `Linux Integrity Measurement Architecture (IMA) <https://ima-doc.readthedocs.io/en/latest/ima-concepts.html>`_
+* `OpenSBI <https://github.com/riscv-software-src/opensbi>`_
+* `Syslinux Project <https://wiki.syslinux.org/wiki/index.php?title=The_Syslinux_Project>`_
+* `Trusted Firmware-A <https://trustedfirmware-a.readthedocs.io/>`_
+* `Trusted Firmware-M <https://trustedfirmware-m.readthedocs.io/>`_
+* `U-Boot <https://u-boot.readthedocs.io/>`_
+* `UEFI Secure Boot documentation <https://docs.system-transparency.org/st-1.1.0/docs/selected-topics/secureboot_concepts/>`_
diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst
index aa1a63e0500b..2456f56c37ee 100644
--- a/documentation/ref-manual/index.rst
+++ b/documentation/ref-manual/index.rst
@@ -12,6 +12,7 @@ Yocto Project Reference Manual
 
    system-requirements
    yocto-project-supported-features
+   boot-architecture
    terms
    release-process
    structure
-- 
2.50.1 (Apple Git-155)

Re: [docs] [RFC PATCH 1/1] ref-manual: add boot architecture documentation

[Quentin Schulz]

Hi Jon,

On 3/31/26 2:29 PM, Jon Mason via lists.yoctoproject.org wrote:
> [You don't often get email from jon.mason=arm.com@lists.yoctoproject.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> Add a new documentation page describing the firmware and bootloader
> architecture used by systems built with the Yocto Project across
> multiple processor architectures.
> 
> The document explains the typical boot stages (Boot ROM, platform
> firmware, system firmware, and OS loader) and provides example boot
> flows for Arm, Arm64, RISC-V, and x86 systems.
> 
> Signed-off-by: Jon Mason <jon.mason@arm.com>
> ---
>   .../ref-manual/boot-architecture.rst          | 361 ++++++++++++++++++
>   documentation/ref-manual/index.rst            |   1 +
>   2 files changed, 362 insertions(+)
>   create mode 100644 documentation/ref-manual/boot-architecture.rst
> 
> diff --git a/documentation/ref-manual/boot-architecture.rst b/documentation/ref-manual/boot-architecture.rst
> new file mode 100644
> index 000000000000..e801e0a402d5
> --- /dev/null
> +++ b/documentation/ref-manual/boot-architecture.rst
> @@ -0,0 +1,361 @@
> +Boot Architecture and Firmware Components
> +=========================================
> +
> +This document describes the firmware and boot architecture used by
> +systems built with the Yocto Project across several processor
> +architectures:
> +
> +* Arm (Arm32)
> +* Arm64 (AArch64)
> +* RISC-V
> +* x86 / x86_64
> +
> +Understanding the firmware chain is important when configuring Yocto
> +Project builds because multiple software components can fulfill the
> +same role in the boot process. These components are often mutually
> +exclusive and are typically selected through BitBake providers or
> +machine configuration.
> +
> +
> +Boot Process Overview
> +---------------------
> +
> +Most systems boot through a sequence of stages that progressively
> +initialize the hardware and load the operating system. Control typically
> +passes from more privileged and trusted stages to less privileged ones.
> +
> +::
> +
> +   Boot ROM
> +      ↓
> +   Platform Firmware
> +      ↓
> +   System Firmware
> +      ↓
> +   OS Loader (optional)
> +      ↓
> +   Operating System
> +
> +
> +Boot ROM
> +--------
> +
> +Boot ROM is the first code executed when a processor starts. It is
> +typically implemented by the CPU or SoC manufacturer and stored in
> +on-chip read-only memory.
> +
> +Boot ROM performs minimal initialization and loads the next stage of
> +firmware from boot media such as SPI flash, eMMC, or SD storage.
> +
> +Boot ROM code is generally **not modifiable by system developers**.
> +

What do you mean "generally" :) Are there Boot Read-Only Memory which 
are BootRWM :) ?

Specifying "by system developers" seems to indicate they may be modified 
by other kind of developers, but isn't BootROM part of the silicon 
(configurable through OTP/(e)fuses)?

> +
> +Platform Firmware
> +-----------------
> +
> +Platform firmware performs early platform initialization before the
> +main boot firmware executes. Depending on the architecture and
> +implementation, it may configure security boundaries, initialize memory
> +and clocks, provide management-controller functions, or expose
> +privileged runtime services used later by the operating system.
> +
> +Some parts of this layer may remain resident after boot. Platform

Please do not use layer as a term to differentiate the boot stages, 
layer already has a meaning in Yocto :)

> +firmware is usually platform-specific and typically has fewer
> +interchangeable implementations than later boot stages.
> +
> +Examples include:
> +
> +* Trusted Firmware-A (TF-A)
> +* Trusted Firmware-M (TF-M), where applicable
> +* System Control Processor (SCP) firmware
> +* OpenSBI, which implements the Supervisor Binary Interface (SBI)
> +

This is not correct for at least Rockchip SoCs. I think it's also not 
correct for Allwinner SoCs. I **think** TI may be doing this but I have 
never worked with their SoCs. For Rockchip, a TPL/SPL is loaded first, 
and then it loads a U-Boot FIT with TF-A, OP-TEE OS and U-Boot proper. 
So if you will, one boots a first part of the System Firmware, which 
loads the Platform Firmware which in turn loads the second part of the 
System Firmware.

Note also that people are increasingly wanting to have TF-A/OP-TEE OS as 
late as possible in the boot process, and I've seen implementations 
where TF-A is part of the kernel FIT image. This allows to easily update 
those persistent and security-critical components without requiring a 
risky bootloader (here called System Firmware) update.

I think this may make things even more confusing since the boot process 
clearly won't be identical for all Aarch64 SoC vendors (at least for the 
time being) and won't match the documentation. Do you have a plan on how 
to handle that?

> +
> +System Firmware
> +---------------
> +
> +System firmware provides the main boot environment. It prepares the
> +hardware needed to load the next stage, discovers bootable devices,
> +and may provide a command shell or a UEFI environment. Many modern
> +implementations can also boot the kernel directly from storage,
> +making a separate OS loader optional.
> +
> +This layer is generally modifiable by system developers and often
> +has alternative implementations.
> +
> +Typical implementations include:
> +
> +* U-Boot
> +* EDK2
> +* coreboot
> +
> +In Yocto Project builds this layer can be selected through a virtual
> +provider using ``PREFERRED_PROVIDER``.
> +
> +The name ``virtual/boot-firmware`` reflects the role of this layer as
> +the primary firmware environment responsible for locating bootable
> +devices and initiating the operating system boot process.
> +
> +Example configuration::
> +
> +   PREFERRED_PROVIDER_virtual/boot-firmware = "u-boot"
> +
> +
> +OS Loader
> +---------
> +
> +The OS loader is the final stage that typically resides on disk. It
> +selects and loads a specific operating system kernel and optional
> +initramfs into memory and passes the required configuration to start
> +the system.
> +
> +This layer is modifiable by system developers and usually has multiple
> +implementations.
> +
> +Examples include:
> +
> +* GRUB
> +* Syslinux / EXTLINUX
> +* systemd-boot
> +
> +In Yocto Project builds this layer can also be selected through a
> +virtual provider.
> +
> +The name ``virtual/boot-manager`` reflects the role of this software in
> +selecting and loading an operating system kernel from storage.
> +
> +Example configuration::
> +
> +   PREFERRED_PROVIDER_virtual/boot-manager = "grub-efi"
> +
> +Some systems boot the kernel directly from system firmware (for example
> +U-Boot or UEFI). In these cases an additional OS loader is not required.
> +

What do we do when we're expecting to use the extlinux implementation in 
U-Boot? Or another implementation? How is this going to be handled? 
Technically, it **is** syslinux/extlinux, just that the extlinux.conf 
file needs to be in a bootable partition readable by U-Boot proper (the 
System Firmware).

> +Example::
> +
> +   PREFERRED_PROVIDER_virtual/boot-manager = "none"
> +
> +
> +Boot Process by Architecture
> +----------------------------
> +
> +
> +Arm (Arm32)
> +~~~~~~~~~~~

I've seen Aarch32 being used also. The wikipedia page 
(https://en.wikipedia.org/wiki/ARM_architecture_family) hints at Aarch32 
being Armv7+ and Arm32 being Armv6-, is this what you wanted to convey? 
Working at arm I guess it's the kind of information you'd have access 
to, but then what matters between what marketing says it is and what the 
public believes it is...

> +
> +Many Arm32 systems boot directly into U-Boot using its SPL stage.
> +
> +::
> +
> +   Boot ROM
> +      ↓
> +   U-Boot SPL
> +      ↓
> +   U-Boot
> +      ↓
> +   Linux Kernel
> +
> +
> +Arm64 (AArch64)
> +~~~~~~~~~~~~~~~
> +
> +Arm64 platforms commonly include Trusted Firmware-A prior to the
> +main boot firmware.
> +

Which SoCs vendors do that? Rockchip doesn't for sure. Allwinner I think 
as well. TI may. Unsure about the others. Or is this something specific 
to ACPI-supported Aarch64 platforms?

[...]

> +Security Considerations
> +-----------------------
> +
> +Secure Boot
> +~~~~~~~~~~~
> +
> +Secure Boot ensures that only software verified by a trusted key can
> +execute during the boot process.
> +
> +Each stage verifies the integrity and authenticity of the next stage
> +before transferring control. Verification is typically performed using
> +digital signatures and public-key cryptography.
> +
> +The process begins with a hardware root of trust, often implemented in
> +Boot ROM or secure firmware, which contains the keys used to verify
> +subsequent boot stages.
> +

We **must** say that Yocto cannot implement the Root of Trust, because 
it necessarily mean doing something on the running target. Except if you 
have something in mind to write to efuses/OTP from some script... Like a 
setup image separate from the final image. I don't think we should be 
aiming to do that, but we for sure need to be clear what is in the scope 
for Yocto.

My worry is we are documenting a "general"/"ideal" setup that won't 
apply to some/many devices. Or do you have bigger plans in the 
Arm/RISC-V ecosystem? I know about Arm SystemReady, though it isn't 
required for selling Arm-based products.

[...]

> +Yocto Project Integration
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The Yocto Project can be used to build systems that implement Secure
> +Boot and Trusted Boot through several layers and components.
> +
> +Examples include:
> +
> +* Secure Boot support in U-Boot

This needs to be clarified. You mean U-Boot has support to be part of 
the Secure Boot and verify the next stages it boots, but "Secure Boot" 
generally means (to me) A to Z, meaning from BootROM to filesystem and 
U-Boot doesn't control BootROM so it's a bit misleading here.

Cheers,
Quentin

Re: [docs] [RFC PATCH 1/1] ref-manual: add boot architecture documentation

[Jon Mason]

[-- Attachment #1: Type: text/plain, Size: 13793 bytes --]

Hello Quentin,
Thank you for taking the time to look this over and provide feedback.

Work email is outlook and I wasn't smart enough to cc myself on the initial email.  So, I've had to get creative with the inline responses below (via cut-n-paste and vim).  Please forgive that.


>From: Quentin Schulz <quentin.schulz@cherry.de>
>Date: Tuesday, March 31, 2026 at 9:53 AM
>To: Jon Mason <Jon.Mason@arm.com>, docs@lists.yoctoproject.org <docs@lists.yoctoproject.org>
>Subject: Re: [docs] [RFC PATCH 1/1] ref-manual: add boot architecture documentation
>
>Hi Jon,
>
>On 3/31/26 2:29 PM, Jon Mason via lists.yoctoproject.org wrote:
>> [You don't often get email from jon.mason=arm.com@lists.yoctoproject.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>>
>> Add a new documentation page describing the firmware and bootloader
>> architecture used by systems built with the Yocto Project across
>> multiple processor architectures.
>>
>> The document explains the typical boot stages (Boot ROM, platform
>> firmware, system firmware, and OS loader) and provides example boot
>> flows for Arm, Arm64, RISC-V, and x86 systems.
>>
>> Signed-off-by: Jon Mason <jon.mason@arm.com>
>> ---
>>   .../ref-manual/boot-architecture.rst          | 361 ++++++++++++++++++
>>   documentation/ref-manual/index.rst            |   1 +
>>   2 files changed, 362 insertions(+)
>>   create mode 100644 documentation/ref-manual/boot-architecture.rst
>>
>> diff --git a/documentation/ref-manual/boot-architecture.rst b/documentation/ref-manual/boot-architecture.rst
>> new file mode 100644
>> index 000000000000..e801e0a402d5
>> --- /dev/null
>> +++ b/documentation/ref-manual/boot-architecture.rst
>> @@ -0,0 +1,361 @@
>> +Boot Architecture and Firmware Components
>> +=========================================
>> +
>> +This document describes the firmware and boot architecture used by
>> +systems built with the Yocto Project across several processor
>> +architectures:
>> +
>> +* Arm (Arm32)
>> +* Arm64 (AArch64)
>> +* RISC-V
>> +* x86 / x86_64
>> +
>> +Understanding the firmware chain is important when configuring Yocto
>> +Project builds because multiple software components can fulfill the
>> +same role in the boot process. These components are often mutually
>> +exclusive and are typically selected through BitBake providers or
>> +machine configuration.
>> +
>> +
>> +Boot Process Overview
>> +---------------------
>> +
>> +Most systems boot through a sequence of stages that progressively
>> +initialize the hardware and load the operating system. Control typically
>> +passes from more privileged and trusted stages to less privileged ones.
>> +
>> +::
>> +
>> +   Boot ROM
>> +      ↓
>> +   Platform Firmware
>> +      ↓
>> +   System Firmware
>> +      ↓
>> +   OS Loader (optional)
>> +      ↓
>> +   Operating System
>> +
>> +
>> +Boot ROM
>> +--------
>> +
>> +Boot ROM is the first code executed when a processor starts. It is
>> +typically implemented by the CPU or SoC manufacturer and stored in
>> +on-chip read-only memory.
>> +
>> +Boot ROM performs minimal initialization and loads the next stage of
>> +firmware from boot media such as SPI flash, eMMC, or SD storage.
>> +
>> +Boot ROM code is generally **not modifiable by system developers**.
>> +
>
>
>
>What do you mean "generally" :) Are there Boot Read-Only Memory which
>are BootRWM :) ?
>
>Specifying "by system developers" seems to indicate they may be modified
>by other kind of developers, but isn't BootROM part of the silicon
>(configurable through OTP/(e)fuses)?

While I don't believe it exists, I wasn't completely certain that something like that doesn't live in the wild.  So I was trying to give some wiggle room in case it did, but I think you're right that we should just say it's not writable.

>
>> +
>> +Platform Firmware
>> +-----------------
>> +
>> +Platform firmware performs early platform initialization before the
>> +main boot firmware executes. Depending on the architecture and
>> +implementation, it may configure security boundaries, initialize memory
>> +and clocks, provide management-controller functions, or expose
>> +privileged runtime services used later by the operating system.
>> +
>> +Some parts of this layer may remain resident after boot. Platform
>
>Please do not use layer as a term to differentiate the boot stages,
>layer already has a meaning in Yocto :)

Very fair, I'll replace with something like "grouping" or "tier"

>> +firmware is usually platform-specific and typically has fewer
>> +interchangeable implementations than later boot stages.
>> +
>> +Examples include:
>> +
>> +* Trusted Firmware-A (TF-A)
>> +* Trusted Firmware-M (TF-M), where applicable
>> +* System Control Processor (SCP) firmware
>> +* OpenSBI, which implements the Supervisor Binary Interface (SBI)
>> +
>
>This is not correct for at least Rockchip SoCs. I think it's also not
>correct for Allwinner SoCs. I **think** TI may be doing this but I have
>never worked with their SoCs. For Rockchip, a TPL/SPL is loaded first,
>and then it loads a U-Boot FIT with TF-A, OP-TEE OS and U-Boot proper.
>So if you will, one boots a first part of the System Firmware, which
>loads the Platform Firmware which in turn loads the second part of the
>System Firmware.
>
>Note also that people are increasingly wanting to have TF-A/OP-TEE OS as
>late as possible in the boot process, and I've seen implementations
>where TF-A is part of the kernel FIT image. This allows to easily update
>those persistent and security-critical components without requiring a
>risky bootloader (here called System Firmware) update.
>
>I think this may make things even more confusing since the boot process
>clearly won't be identical for all Aarch64 SoC vendors (at least for the
>time being) and won't match the documentation. Do you have a plan on how
>to handle that?

And this is the reason why this is an RFC :)

I was not aware this is how things are being used in some of the SoCs.  I guess this would provide a fallback if something is broken during an update.  I'm not sure it is worth the extra layers of indirection and potential for that potentially being broken, but probably no point in arguing that here.

My intention in this document is to provide a rough idea of how boot works and show what is mutually exclusive, and the logic behind it.  Perhaps there is a way to rewrite this to allow for it to be generic enough to cover the straightforward way I was saying and the indirect way you are saying is used.  I'll see what I can do regarding this in v2.

>> +
>> +System Firmware
>> +---------------
>> +
>> +System firmware provides the main boot environment. It prepares the
>> +hardware needed to load the next stage, discovers bootable devices,
>> +and may provide a command shell or a UEFI environment. Many modern
>> +implementations can also boot the kernel directly from storage,
>> +making a separate OS loader optional.
>> +
>> +This layer is generally modifiable by system developers and often
>> +has alternative implementations.
>> +
>> +Typical implementations include:
>> +
>> +* U-Boot
>> +* EDK2
>> +* coreboot
>> +
>> +In Yocto Project builds this layer can be selected through a virtual
>> +provider using ``PREFERRED_PROVIDER``.
>> +
>> +The name ``virtual/boot-firmware`` reflects the role of this layer as
>> +the primary firmware environment responsible for locating bootable
>> +devices and initiating the operating system boot process.
>> +
>> +Example configuration::
>> +
>> +   PREFERRED_PROVIDER_virtual/boot-firmware = "u-boot"
>> +
>> +
>> +OS Loader
>> +---------
>> +
>> +The OS loader is the final stage that typically resides on disk. It
>> +selects and loads a specific operating system kernel and optional
>> +initramfs into memory and passes the required configuration to start
>> +the system.
>> +
>> +This layer is modifiable by system developers and usually has multiple
>> +implementations.
>> +
>> +Examples include:
>> +
>> +* GRUB
>> +* Syslinux / EXTLINUX
>> +* systemd-boot
>> +
>> +In Yocto Project builds this layer can also be selected through a
>> +virtual provider.
>> +
>> +The name ``virtual/boot-manager`` reflects the role of this software in
>> +selecting and loading an operating system kernel from storage.
>> +
>> +Example configuration::
>> +
>> +   PREFERRED_PROVIDER_virtual/boot-manager = "grub-efi"
>> +
>> +Some systems boot the kernel directly from system firmware (for example
>> +U-Boot or UEFI). In these cases an additional OS loader is not required.
>> +
>
>What do we do when we're expecting to use the extlinux implementation in
>U-Boot? Or another implementation? How is this going to be handled?
>Technically, it **is** syslinux/extlinux, just that the extlinux.conf
>file needs to be in a bootable partition readable by U-Boot proper (the
>System Firmware).

This is the case that I was trying to reference.  The case where you are trying to make sure that grub or systemd-boot isn't used (and thus shouldn't be added to the image).
I'll clean-up the language to make it clearer.

>> +Example::
>> +
>> +   PREFERRED_PROVIDER_virtual/boot-manager = "none"
>> +
>> +
>> +Boot Process by Architecture
>> +----------------------------
>> +
>> +
>> +Arm (Arm32)
>> +~~~~~~~~~~~
>
>
>
>I've seen Aarch32 being used also. The wikipedia page
>(https://en.wikipedia.org/wiki/ARM_architecture_family) hints at Aarch32
>being Armv7+ and Arm32 being Armv6-, is this what you wanted to convey?
>
>Working at arm I guess it's the kind of information you'd have access
>to, but then what matters between what marketing says it is and what the
>public believes it is...

There is an ARMv8 core that is 32bit only (A32), there are others that are 64bit only, and there are a lot that do both.  I'm not trying to muddy the waters here, but more trying to say that there is the legacy 32bit way of doing things ("the easy way" is how I have it in my mind).

I didn't think that Aarch32 was used outside of Arm, but if that is less confusing then I'm happy to replace Arm32 with Aarch32, or write it in a way more understandable

>
>> +
>> +Many Arm32 systems boot directly into U-Boot using its SPL stage.
>> +
>> +::
>> +
>> +   Boot ROM
>> +      ↓
>> +   U-Boot SPL
>> +      ↓
>> +   U-Boot
>> +      ↓
>> +   Linux Kernel
>> +
>> +
>> +Arm64 (AArch64)
>> +~~~~~~~~~~~~~~~
>> +
>> +Arm64 platforms commonly include Trusted Firmware-A prior to the
>> +main boot firmware.
>> +
>
>
>
>Which SoCs vendors do that? Rockchip doesn't for sure. Allwinner I think
>as well. TI may. Unsure about the others. Or is this something specific
>to ACPI-supported Aarch64 platforms?

The Arm reference platforms do it this way, but the point you made above that others don't has me reconsidering how to make this more complete.  Perhaps an "Option A" and "Option B" that has both ways.

>
>
>
>[...]
>
>
>> +Security Considerations
>> +-----------------------
>> +
>> +Secure Boot
>> +~~~~~~~~~~~
>> +
>> +Secure Boot ensures that only software verified by a trusted key can
>> +execute during the boot process.
>> +
>> +Each stage verifies the integrity and authenticity of the next stage
>> +before transferring control. Verification is typically performed using
>> +digital signatures and public-key cryptography.
>> +
>> +The process begins with a hardware root of trust, often implemented in
>> +Boot ROM or secure firmware, which contains the keys used to verify
>> +subsequent boot stages.
>> +
>
>
>
>We **must** say that Yocto cannot implement the Root of Trust, because
>it necessarily mean doing something on the running target. Except if you
>have something in mind to write to efuses/OTP from some script... Like a
>setup image separate from the final image. I don't think we should be
>aiming to do that, but we for sure need to be clear what is in the scope
>for Yocto.
>
>
>My worry is we are documenting a "general"/"ideal" setup that won't
>apply to some/many devices. Or do you have bigger plans in the
>Arm/RISC-V ecosystem? I know about Arm SystemReady, though it isn't
>required for selling Arm-based products.

Ross was suggesting that I rip this out, as he had conserns about this needing to be in the actual security documentation and being incomplete.  I wanted to keep it in, as it is part of the boot process.  Given your concerns, perhaps it is better to simply say that these things exist but are outside the scope of this document.


>
>[...]
>
>
>> +Yocto Project Integration
>> +~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The Yocto Project can be used to build systems that implement Secure
>> +Boot and Trusted Boot through several layers and components.
>> +
>> +Examples include:
>> +
>> +* Secure Boot support in U-Boot
>
>
>
>This needs to be clarified. You mean U-Boot has support to be part of
>the Secure Boot and verify the next stages it boots, but "Secure Boot"
>generally means (to me) A to Z, meaning from BootROM to filesystem and
>U-Boot doesn't control BootROM so it's a bit misleading here.

Per above, I think I'll just rip this out in v2 and say it's outside the scope.

>
>
>
>Cheers,
>
>Quentin
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

[-- Attachment #2: Type: text/html, Size: 55129 bytes --]

Re: [docs] [RFC PATCH 1/1] ref-manual: add boot architecture documentation

[Quentin Schulz]

Hi Jon,

On 3/31/26 10:06 PM, Jon Mason wrote:
> Hello Quentin,
> Thank you for taking the time to look this over and provide feedback.
> 
> Work email is outlook and I wasn't smart enough to cc myself on the initial email.  So, I've had to get creative with the inline responses below (via cut-n-paste and vim).  Please forgive that.
> 

You can download an .mbox.gz or Atom feed from lore.kernel.org directly, 
see at the bottom of 
https://lore.kernel.org/yocto-docs/20260331122924.54516-1-jon.mason@arm.com/T/#t.

On Thunderbird (which I use instead of Outlook to access my Microsoft 
Outlook company emails), you can then use ImportExportNG plugin to 
import the (first uncompressed) .mbox to have it in Thunderbird as if 
you had received it. I used to know how to bounce a mail from one 
address to another but I couldn't find that on Thunderbird last time I 
checked, that could have been another option.

> 
>> From: Quentin Schulz <quentin.schulz@cherry.de>
>> Date: Tuesday, March 31, 2026 at 9:53 AM
>> To: Jon Mason <Jon.Mason@arm.com>, docs@lists.yoctoproject.org <docs@lists.yoctoproject.org>
>> Subject: Re: [docs] [RFC PATCH 1/1] ref-manual: add boot architecture documentation
>>
>> Hi Jon,
>>
>> On 3/31/26 2:29 PM, Jon Mason via lists.yoctoproject.org wrote:

[...]

>>> +firmware is usually platform-specific and typically has fewer
>>> +interchangeable implementations than later boot stages.
>>> +
>>> +Examples include:
>>> +
>>> +* Trusted Firmware-A (TF-A)
>>> +* Trusted Firmware-M (TF-M), where applicable
>>> +* System Control Processor (SCP) firmware
>>> +* OpenSBI, which implements the Supervisor Binary Interface (SBI)
>>> +
>>
>> This is not correct for at least Rockchip SoCs. I think it's also not
>> correct for Allwinner SoCs. I **think** TI may be doing this but I have
>> never worked with their SoCs. For Rockchip, a TPL/SPL is loaded first,
>> and then it loads a U-Boot FIT with TF-A, OP-TEE OS and U-Boot proper.
>> So if you will, one boots a first part of the System Firmware, which
>> loads the Platform Firmware which in turn loads the second part of the
>> System Firmware.
>>
>> Note also that people are increasingly wanting to have TF-A/OP-TEE OS as
>> late as possible in the boot process, and I've seen implementations
>> where TF-A is part of the kernel FIT image. This allows to easily update
>> those persistent and security-critical components without requiring a
>> risky bootloader (here called System Firmware) update.
>>
>> I think this may make things even more confusing since the boot process
>> clearly won't be identical for all Aarch64 SoC vendors (at least for the
>> time being) and won't match the documentation. Do you have a plan on how
>> to handle that?
> 
> And this is the reason why this is an RFC :)
> 
> I was not aware this is how things are being used in some of the SoCs.  I guess this would provide a fallback if something is broken during an update.  I'm not sure it is worth the extra layers of indirection and potential for that potentially being broken, but probably no point in arguing that here.
> 

I am not following here, what is "this" starting from the second sentence?

> My intention in this document is to provide a rough idea of how boot works and show what is mutually exclusive, and the logic behind it.  Perhaps there is a way to rewrite this to allow for it to be generic enough to cover the straightforward way I was saying and the indirect way you are saying is used.  I'll see what I can do regarding this in v2.
> 
It isn't path A or path B.

[...]

>>> +Examples include:
>>> +
>>> +* GRUB
>>> +* Syslinux / EXTLINUX
>>> +* systemd-boot
>>> +
>>> +In Yocto Project builds this layer can also be selected through a
>>> +virtual provider.
>>> +
>>> +The name ``virtual/boot-manager`` reflects the role of this software in
>>> +selecting and loading an operating system kernel from storage.
>>> +
>>> +Example configuration::
>>> +
>>> +   PREFERRED_PROVIDER_virtual/boot-manager = "grub-efi"
>>> +
>>> +Some systems boot the kernel directly from system firmware (for example
>>> +U-Boot or UEFI). In these cases an additional OS loader is not required.
>>> +
>>
>> What do we do when we're expecting to use the extlinux implementation in
>> U-Boot? Or another implementation? How is this going to be handled?
>> Technically, it **is** syslinux/extlinux, just that the extlinux.conf
>> file needs to be in a bootable partition readable by U-Boot proper (the
>> System Firmware).
> 
> This is the case that I was trying to reference.  The case where you are trying to make sure that grub or systemd-boot isn't used (and thus shouldn't be added to the image).
> I'll clean-up the language to make it clearer.
> 

Wondering if we cannot have U-Boot extlinux boot a UEFI payload (e.g. 
grub). It seems like you can boot a FIT which contains a UEFI binary 
(I'm assuming grub). You can then simply get this FIT using extlinux I'm 
assuming still.

>>> +Example::
>>> +
>>> +   PREFERRED_PROVIDER_virtual/boot-manager = "none"
>>> +
>>> +
>>> +Boot Process by Architecture
>>> +----------------------------
>>> +
>>> +
>>> +Arm (Arm32)
>>> +~~~~~~~~~~~
>>
>>
>>
>> I've seen Aarch32 being used also. The wikipedia page
>> (https://en.wikipedia.org/wiki/ARM_architecture_family) hints at Aarch32
>> being Armv7+ and Arm32 being Armv6-, is this what you wanted to convey?
>>
>> Working at arm I guess it's the kind of information you'd have access
>> to, but then what matters between what marketing says it is and what the
>> public believes it is...
> 
> There is an ARMv8 core that is 32bit only (A32), there are others that are 64bit only, and there are a lot that do both.  I'm not trying to muddy the waters here, but more trying to say that there is the legacy 32bit way of doing things ("the easy way" is how I have it in my mind).
> 
> I didn't think that Aarch32 was used outside of Arm, but if that is less confusing then I'm happy to replace Arm32 with Aarch32, or write it in a way more understandable
> 

I meant Aarch32 is for 32b Armv7+ cores and Arm32 for 32b Armv6- cores. 
I guess just make it explicit what the 32/64 part of the name comes from 
(and potentially mention it can be called Arm32/Aarch32. (We won't say 
anything about arm in the Linux kernel meaning Arm32, no we won't :) ).

>>
>>> +
>>> +Many Arm32 systems boot directly into U-Boot using its SPL stage.
>>> +
>>> +::
>>> +
>>> +   Boot ROM
>>> +      ↓
>>> +   U-Boot SPL
>>> +      ↓
>>> +   U-Boot
>>> +      ↓
>>> +   Linux Kernel
>>> +
>>> +
>>> +Arm64 (AArch64)
>>> +~~~~~~~~~~~~~~~
>>> +
>>> +Arm64 platforms commonly include Trusted Firmware-A prior to the
>>> +main boot firmware.
>>> +
>>
>>
>>
>> Which SoCs vendors do that? Rockchip doesn't for sure. Allwinner I think
>> as well. TI may. Unsure about the others. Or is this something specific
>> to ACPI-supported Aarch64 platforms?
> 
> The Arm reference platforms do it this way, but the point you made above that others don't has me reconsidering how to make this more complete.  Perhaps an "Option A" and "Option B" that has both ways.
> 

I think there are N options, with N increasing every year.

FYI, on some Arm32 Rockchip SoCs, I believe OP-TEE OS (BL32) is required 
to boot.

Also, Platform Firmware may load another Platform Firmware. That is the 
case on Rockchip SoCs with U-Boot SPL jumps into TF-A as BL31 which in 
turn jumps into OP-TEE OS as BL32 which in turn jumps into U-Boot proper.

Also, when I say "Rockchip SoCs", I mean what we've settled for as the 
"default" boot process. I'm not sure there's anything forbidding you 
from having a different boot flow.

Note also that there's some people (mainly Simon Glass at that point I 
think) about VBE (Verified Boot for Embedded) which is yet another boot 
flow.

Is there any plan to integrate with update software like swupdate/rauc? 
UEFI-supporting U-Boot seems to support update capsules, I see patches 
on the U-Boot ML every now and then for adding capsules to Qualcomm, 
Samsung, Amlogic, Raspberry Pi, NXP, TI, ... devices.

For the sake of completeness, know that Rockchip provides binary blobs 
for the DDR init (which we call TPL because it's there to replace U-Boot 
TPL until there's an open-source implem), (ancient) TF-A and OP-TEE OS 
(as far as I know incompatible with upstream U-Boot). We've plumbing in 
meta-rockchip to allow picking between blob TF-A or upstream TF-A. Not 
sure it's important for you, but at least it's out there now :)

[...]

I think the part we're (I am) missing here, is what you're trying to 
achieve or improve or change. But maybe I'm too early in the discussion 
(especially since only the docs people are in Cc :) ) and this will be 
part of the patch series with the actual implementation. Maybe provide a 
bird eye view on what's the plan in the cover letter to help us out?

Cheers,
Quentin