[PATCH v3 3/3] docs: Add description for unified Linux images

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---
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..556dc38
--- /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)
+* 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

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

Changes in v4:
- document kernel version restriction /wrt initrd

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+)