From: Zbigniew Jędrzejewski-Szmek Date: Wed, 6 Nov 2024 13:40:21 +0000 (+0100) Subject: man/systemd-stub: rework the description of sections X-Git-Tag: v257-rc1~8^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bc11463e8e4b7064c5b8bd54b599bab9b94f435b;p=thirdparty%2Fsystemd.git man/systemd-stub: rework the description of sections The text added for .dtbauto/.hwids was very hard to grok. This rewords it to be proper English. No semantic changes are intended. When updating this, I noticed that the interaction of multi-profile UKIs and dtb autoselection is very unclear, a FIXME is added. --- diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 6625fca91ef..8f63770997e 100644 --- a/man/systemd-stub.xml +++ b/man/systemd-stub.xml @@ -59,58 +59,66 @@ - A .linux section with the ELF Linux kernel - image. (Required) + A .linux section with the ELF Linux kernel image. + This section is required. - An .osrel section with OS release information, i.e. the contents of - the os-release5 file - of the OS the kernel belongs to. + An optional .osrel section with OS release information, i.e. the + contents of the + os-release5 file of + the OS the kernel belongs to. - A .cmdline section with the kernel command line to pass to the - invoked kernel. + An optional .cmdline section with the kernel command line to pass to + the invoked kernel. - An .initrd section with the initrd. + An optional .initrd section with the initrd. - A .ucode section with an initrd containing microcode, to be handed - to the kernel before any other initrd. This initrd must not be compressed. + An optional .ucode section with an initrd containing microcode, to + be handed to the kernel before any other initrd. This initrd must not be compressed. - A .splash section with an image (in the Windows + An optional .splash section with an image (in the Windows .BMP format) to show on screen before invoking the kernel. - A .dtb section with a compiled binary DeviceTree. - - Zero or more .dtbauto sections. Stub will always try to find first matching one. - Matching process extracts first compatible string from .dtbauto - section and compares it with the first Devicetree's compatible string supplied by - the firmware in configuration tables. If firmware does not provide Devicetree, matching with - .hwids section will be used instead. Stub will use SMBIOS data to calculate hardware - IDs of the machine (as per specification), - then it will proceed to trying to find any of them in .hwids section and will use first - matching entry's compatible as a search key among the .dtbauto - entries, in a similar fashion as the use of compatible string read from the firmware - provided Devicetree was described before. First matching .dtbauto section will be + An optional .dtb section with a compiled binary DeviceTree. + + + Zero or more .dtbauto sections. systemd-stub + will always use the first matching one. The match is performed by taking the first DeviceTree's + compatible string supplied by the firmware in configuration tables and comparing it + with the first compatible string from each of the .dtbauto + sections. If the firmware does not provide a DeviceTree, the match is done using the + .hwids section instead. After selecting a .hwids section (see the + description below), the compatible string from that section will be used to perform + the same matching procedure. If a match is found, that .dtbauto section will be loaded and will override .dtb if present. - A .hwids section with hardware IDs of the machines to match Devicetrees (refer to .dtbauto section description). + Zero or more .hwids sections with hardware IDs of the machines to + match DeviceTrees. systemd-stub will use the SMBIOS data to calculate hardware IDs + of the machine (as per specification), + and then it will try to find any of them in each of the .hwids sections. The first + matching section will be used. - A .uname section with the kernel version information, i.e. the - output of uname -r for the kernel included in the .linux + An optional .uname section with the kernel version information, i.e. + the output of uname -r for the kernel included in the .linux section. - An .sbat section with - SBAT revocation - metadata. + An optional .sbat section with + SBAT revocation metadata. + - A .pcrsig section with a set of cryptographic signatures for the - expected TPM2 PCR values after the kernel has been booted, in JSON format. This is useful for + An optional .pcrsig section with a set of cryptographic signatures + for the expected TPM2 PCR values after the kernel has been booted, in JSON format. This is useful for implementing TPM2 policies that bind disk encryption and similar to kernels that are signed by a specific key. - A .pcrpkey section with a public key in the PEM format matching the - signature data in the .pcrsig section. + An optional .pcrpkey section with a public key in the PEM format + matching the signature data in the .pcrsig section. - In a basic UKI, the sections listed above appear at most once. In a multi-profile UKI, + + + In a basic UKI, the sections listed above appear at most once, with the exception of + .dtbauto and .hwids sections. In a multi-profile UKI, multiple sets of these sections are present in a single file and form "profiles", one of which can be selected at boot. For this, the PE section .profile is defined to be used as the separator between sets of sections. The