From: Jan Kiszka <[email protected]> Signed-off-by: Jan Kiszka <[email protected]> ---
Changes in v4: - document kernel version restriction /wrt initrd README.md | 5 +++++ docs/UNIFIED-LINUX.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 docs/UNIFIED-LINUX.md diff --git a/README.md b/README.md index b7446eb..cc9e457 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,10 @@ Provides the following functionality: * Arm a hardware watchdog prior to loading an OS * Provides a simple update mechanism with fail-safe algorithm +In addition, this project provides a UEFI stub and generator tool to create +unified Linux images consisting of kernel, command line and, optionally, +initrd and device trees. + ## Development ## Mailing list: @@ -51,4 +55,5 @@ See `Installation And Usage` for further information. * [API Library](docs/API.md) * [Compilation Instructions](docs/COMPILE.md) * [Installation And Usage](docs/USAGE.md) +* [Unified Linux Images](docs/UNIFIED-LINUX.md) * [System Recovery](docs/RECOVERY.md) diff --git a/docs/UNIFIED-LINUX.md b/docs/UNIFIED-LINUX.md new file mode 100644 index 0000000..8f9c8e0 --- /dev/null +++ b/docs/UNIFIED-LINUX.md @@ -0,0 +1,38 @@ +# Unified Linux Images # + +A unified Linux image combines all artifacts needed to start Linux from a +single UEFI binary, even in complex scenarios. This includes: +* Kernel (as UEFI binary) +* Kernel command line +* initrd/initramfs (optional, requires kernel version 5.8+) +* alternative device trees (optional) + +Using a single binary enables secure boot setups by allowing to sign and later +on validate this binary during boot-up. + +The ability to embed and select from multiple device trees permits to replace +the firmware-provide device tree with an alternative one if the kernel requires +deviation or the firmware does not permit easy updates. The final device tree +is selected by matching its compatible property against the firmware device +tree. + +## Building unified Linux images ## + +EFI Boot Guard provides the `bg_gen_unified_linux` command to generate the +image from all required artifacts, e.g.: + +``` +bg_gen_unified_linux \ + linux-stubaa64.efi \ + vmlinux-5.17.1 \ + unified-linux.efi \ + --cmdline "console=ttyS0,115200" \ + --initrd initrd-5.17.1 \ + --dtb board-variant-1.dtb \ + --dtb board-variant-2.dtb +``` + +See also `bg_gen_unified_linux --help`. + +The generated `unified-linux.efi` can then be signed with tools like `pesign` +to enable secure boot. -- 2.34.1 -- You received this message because you are subscribed to the Google Groups "EFI Boot Guard" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/efibootguard-dev/6e5ad2f1-c3aa-8795-2828-2f4aa68ba8e4%40siemens.com.
