LM
/
coreos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update the boot chapter to reflect current boot flow

This commit is contained in:
Samuel Dolt 2023-03-10 11:47:33 +01:00
parent 05f53a8804
commit 81777d48bb
5 changed files with 18 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
documentation/boot/bootflow-generic.dot
View File

@ -5,6 +5,5 @@ digraph G {
os [label = "Operating System";shape = rect;];
fw -> btl -> os [style = dashed;];
fw -> os;
fw -> btl -> os;
}

4
documentation/boot/bootflow-uboot.dot
View File

@ -3,7 +3,9 @@ digraph G {
uboot [label = "u-boot with EFI/EBBR support";shape = rect;];
btl [label = "EFIBootGuard";shape = rect;];
kernel [label = "OS (EFI Stub + Kernel + Initramfs";shape = rect;];
rom -> uboot -> kernel;
rom -> uboot -> btl -> kernel;
}

46
documentation/boot/overview.rst
View File

@ -76,7 +76,7 @@ legacy like:
- Fixed offsets to firmware data
We require the firmware to provide a DeviceTree based system description and not
an ACPI based table (as allowed by the specification)
an ACPI based table (as allowed by the specification).
We also require the firmware to implement the UEFI Secure Boot functionality.
@ -84,15 +84,12 @@ ARM64 / AArch64 based machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The firmware for ARM64 should implement a subset of the UEFI specification, as
defined by the EBBR Specification. The part of the specification marked as
legacy or deprecated must not be used.
This means:
- Only GPT partionning disk are supported
- No fixed offsets to firmware data
defined by the EBBR Specification.
We require the firmware to provide a DeviceTree based system description and not
an ACPI based table (as allowed by the specification)
an ACPI based table (as allowed by the specification). The DeviceTree provided
by the firmware can be very minimal as it can be replaced at boot time
by a device-tree contained inside the Operating System Image.
We also require the firmware to implement the UEFI Secure Boot functionality.
@ -105,38 +102,13 @@ The firmware for AMD64 should implement the UEFI specification.
Bootloader
==========
CoreOS only support `systemd-boot` as bootloader. The usage of the bootloader
is optional. It's primary use case is for system that don't use a firmware
provided by CoreOS.
CoreOS only support `efibootguard` as bootloader. The usage of the bootloader
is mandated.
Operating system
================
The operating system image is an UEFI application that contain the kernel. We
support two method to create this image:
The operating system image is an UEFI application that contain the kernel. It's
a Unified Kernel Image generated by tools from the EFIBootGuard project.
Unified Kernel Images (UKI)
---------------------------
This is the most secure method. The UEFI entry point is provided by
`systemd-stub` and the image contains the Linux Kernel, the boot arguments of
the kernel, the os-release file and an initrd ram disk.
This allows to have all these part authenticated via UEFI secure boot.
.. warning::
UKI are not supported for ARM32 target at the moment, due to a bug in objcopy.
See https://sourceware.org/bugzilla/show_bug.cgi?id=26218
.. note::
UKI has the advantages to be discoverable by the bootloader without any
configuration file, and doesn't need a firmware that is able to set the
kernel command line.
Kernel built with the built-in EFI sub
--------------------------------------
This method use the EFI stub provided by the kernel. The initramfs image has to
be bundled with the Kernel, using `INITRAMFS_IMAGE_BUNDLE`, as otherwise it
will not be authenticated by UEFI secure boot.

16
documentation/boot/uboot-dts-handling.dot
View File

@ -1,16 +0,0 @@
digraph G {
start [label = "boot";];
mb [label = "Detect the main board name";shape = rect;];
mbdts [label = "Load main board device tree";shape = rect;];
ext [label = "Detect the extension module name";shape = rect;];
extdts [label = "Load a device tree overlay for each module";shape = rect;];
dtsprocess [label = "Add and remove device tree node as needed (DT Fixup)";shape = rect;];
stop [label = "Start UEFI application";];
start -> mb -> mbdts -> ext -> extdts -> dtsprocess -> stop;
}

71
documentation/boot/uboot.rst
View File

@ -21,13 +21,10 @@ to be changed at runtime.
Device tree handling
====================
As per the EBBR specification, the firmware is responsible to provide the
device tree to the kernel.
This means that loading the main device tree and all the device tree overlay are
is the responsibility of the firmware.
.. graphviz:: uboot-dts-handling.dot
As per the EBBR specification, the firmware is responsible to provide a
device tree to the kernel. Not that it's OK to export the device tree used by
U-Boot internally as it will be replaced by a propper device tree at a later
stage. This avoid the need to load the device tree from a boot partition.
Features to implement per machine
=================================
@ -35,19 +32,11 @@ Features to implement per machine
The u-boot provided by CoreOS should implement the following features for each
supported machine:
board_fit_config_name_match
----------------------------
This allows u-boot to select the device tree to use dynamically using board
detection. See `README.multi-dtb-fit`
extension_board_scan
--------------------
The extension_board_scan function has to be implemented. This function should
return the list of add-ons board detected, with the filename of the
correspondig device-tree overlay.
return the list of add-ons board detected.
DT Fixup
--------
@ -55,53 +44,3 @@ DT Fixup
U-Boot can create, modify and remove node from the device tree dynamically
before starting the kernel. This can be used to pass dynamic information stored
inside a "board descriptor" eeprom or CPLD to the Kernel.
Custom Features that are generic
================================
The u-boot provided by CoreOS should implement the following custom features:
File authentication
-------------------
In order to be able to authenticate device tree, device-tree overlay file or
other file needed by the firmware, we need a command to authenticate a file that
was previously loaded is the `load` command.
.. note::
My proposal is to use the UEFI Capsule format, to reuse theses function from
u-boot:
- **efi_capsule_authenticate**: Authenticate the UEFI capsule using a x509
certificate built into u-boot
- **efi_remove_auth_hdr**: Can be used to point a pointer to the start of the
content of an authenticated capsule.
An UEFI Capsule is a generic container that can be signed using a x.509
private key. The public key is stored inside u-boot (it's not the same as
the keys used for UEFI secure-boot). See
https://u-boot.readthedocs.io/en/v2022.10/develop/uefi/uefi.html?highlight=capsule#enabling-capsule-authentication
extension_overlay_cmd
---------------------
A custom command should be made for `extension_overlay_cmd`. The extension
subsystem use the command defined as extension_overlay_cmd to load
the overlay `${extension_overlay_name}` into `extension_overlay_addr`
This should reuse the file authentication mechanismus.
.. note::
A concept on where and how to securly store device tree and overlay needed
by the kernel has to be written.
My proposal is to use the UEFI Capsule format, to reuse theses function from
u-boot:
- **efi_capsule_authenticate**: Authenticate the UEFI capsule using a x509
certificate built into u-boot
- **efi_remove_auth_hdr**: Can be used to point a pointer to the start of the
content of an authenticated capsule.