From fb0ef5eac0aa2a3c55bcefb2e4f36b24701146ab Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 3 Oct 2024 12:52:56 +0200
Subject: [PATCH] man/systemd-stub: reword descriptions of .dtb and .profile
 sections

- The text was clearly edited in variuos places to e.g. allow multiple
  sections, so it first said that sections are singletons, and immediately
  after that that some section are not.
- Replace "regardless of the kernel" with "regardless of the kernel version".
  The kernel is very much involved e.g. in loading of the initrds.
- Various other small rewordings to make the text more legible.
---
 man/systemd-stub.xml | 37 +++++++++++++++++++------------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml
index 0bdf8f3139b..18f3023a65f 100644
--- a/man/systemd-stub.xml
+++ b/man/systemd-stub.xml
@@ -51,9 +51,9 @@
     system into the Linux world.</para>
 
     <para>The UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE binary
-    itself. This allows combining various resources inside a single PE binary image (usually called "Unified
-    Kernel Image", or "UKI" for short), which may then be signed via UEFI SecureBoot as a whole, covering all
-    individual resources at once. Specifically it may include the following PE sections:</para>
+    itself. This allows combining various resources inside a single PE binary image (a "Unified Kernel Image"
+    or "UKI" for short), which may then be signed via UEFI SecureBoot as a whole, covering all individual
+    resources at once. Specifically it may include the following PE sections:</para>
 
     <itemizedlist>
       <!-- Let's keep this in the canonical order we also measure the sections by, i.e. as in
@@ -96,10 +96,10 @@
       signature data in the <literal>.pcrsig</literal> section.</para></listitem>
     </itemizedlist>
 
-    <para>Generally, the sections above should appear at most once in a UKI. That said, a concept of
-    "profiles" is defined, that allows multiple sets of these sections to exist in a single UKI file, of
-    which one can be selected at boot. For this an additional PE section <literal>.profile</literal> is
-    defined which can be used as separator between multiple sets of these settings. The
+    <para>In a basic UKI, the sections listed above appear at most once. 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 <literal>.profile</literal> is
+    defined to be used as the separator between sets of sections. The
     <literal>.profile</literal> section itself may contain meta-information about the section, and follows a
     similar structure as the contents of the <literal>.osrel</literal> section. For further details about
     multi-profile UKIs, see below.</para> <para>If UEFI SecureBoot is enabled and the
@@ -191,13 +191,14 @@
 
       <listitem><para>Similarly, files
       <filename><replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename> are loaded and verified as
-      PE binaries, and a <literal>.cmdline</literal> or <literal>.ucode</literal> section is parsed from them.
-      Addons are supposed to be used to pass additional kernel command line parameters, or Devicetree blobs,
-      and microcode updates, regardless of the kernel image being booted, for example to allow platform vendors
-      to ship platform-specific configuration.</para>
+      PE binaries and specific sections are loaded from them. Addons are used to pass additional kernel
+      command line parameters (<literal>.cmdline</literal> section), or Devicetree blobs
+      (<literal>.dtb</literal> section), and microcode updates (<literal>.ucode</literal> section). Addons
+      allow those resources to be passed regardless of the kernel version being booted, for example allowing
+      platform vendors to ship platform-specific configuration.</para>
 
       <para>In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim's DB or
-      Shim's MOK, and will be rejected otherwise. Additionally, if both the addon and the UKI contain a
+      Shim's MOK, and only loaded if the check passes. Additionally, if both the addon and the UKI contain a
       <literal>.uname</literal> section, the addon will be rejected if they do not match exactly. It is
       recommended to always add a <literal>.sbat</literal> section to all signed addons, so that they may be
       revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX. The
@@ -222,14 +223,14 @@
       <listitem><para>Files <filename>/loader/credentials/*.cred</filename> are packed up in a
       <command>cpio</command> archive and placed in the <filename>/.extra/global_credentials/</filename>
       directory of the initrd file hierarchy. This is supposed to be used to pass additional credentials to
-      the initrd, regardless of the kernel being booted. The generated <command>cpio</command> archive is
-      measured into TPM PCR 12 (if a TPM is present).</para></listitem>
+      the initrd, regardless of the kernel version being booted. The generated <command>cpio</command>
+      archive is measured into TPM PCR 12 (if a TPM is present).</para></listitem>
 
       <listitem><para>Additionally, files <filename>/loader/addons/*.addon.efi</filename> are loaded and
-      verified as PE binaries, and <literal>.cmdline</literal>, <literal>.dtb</literal> and/or
-      <literal>.ucode</literal>sections are parsed from them. This is supposed to be used to pass additional
-      command line parameters, Devicetree blobs and microcode updates to the kernel, regardless of the
-      kernel being booted.</para></listitem>
+      verified as PE binaries, and <literal>.cmdline</literal>, <literal>.dtb</literal>, and
+      <literal>.ucode</literal> sections are parsed from them. This is supposed to be used to pass additional
+      command line parameters, DeviceTree blobs, and microcode updates to the kernel, regardless of the
+      kernel version being booted.</para></listitem>
     </itemizedlist>
 
     <para>These mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable initrd
-- 
2.47.3