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 `_ +* `Coreboot `_ +* `EDK2 `_ +* `GNU GRUB `_ +* `IMA/EVM `_ +* `Linux Integrity Measurement Architecture (IMA) `_ +* `OpenSBI `_ +* `Syslinux Project `_ +* `Trusted Firmware-A `_ +* `Trusted Firmware-M `_ +* `U-Boot `_ +* `UEFI Secure Boot documentation `_ 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