From c88e4f74f35e9469c7940abe44ef87e953bb143a Mon Sep 17 00:00:00 2001
From: Paul Meyer <katexochen0@gmail.com>
Date: Sun, 7 Jun 2026 19:18:33 +0200
Subject: [PATCH] man: fix systemd-stub .hwids section to be a singleton

Only .dtbauto and .efifw may appear more than once, .hwids is a
singleton per the UKI specification and the stub reads a single .hwids
section (per profile), matching hardware IDs against entries within it.

Co-developed-by: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Paul Meyer <katexochen0@gmail.com>
(cherry picked from commit af44888d22f03358e923e56f96a629b4810a5ca9)
(cherry picked from commit a5eee37d9e608d0486528a6fbbceda2d77c39c4a)
(cherry picked from commit 715cdf030af91a6a152073be3c957d521823b711)
---
 man/systemd-stub.xml | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml
index d098804dc10..0ac278bbe85 100644
--- a/man/systemd-stub.xml
+++ b/man/systemd-stub.xml
@@ -89,10 +89,11 @@
       <literal>compatible</literal> string supplied by the firmware in configuration tables and comparing it
       with the first <literal>compatible</literal> string from each of the <literal>.dtbauto</literal>
       sections. If the firmware does not provide a DeviceTree, the match is done using the
-      <literal>.hwids</literal> section instead. After selecting a <literal>.hwids</literal> section (see the
-      description below), the <literal>compatible</literal> string from that section will be used to perform
-      the same matching procedure. If a match is found, that <literal>.dtbauto</literal> section will be
-      loaded and will override <literal>.dtb</literal> if present.</para></listitem>
+      <literal>.hwids</literal> section instead. After selecting the matching entry in the
+      <literal>.hwids</literal> section (see the description below), the <literal>compatible</literal> string
+      from that entry will be used to perform the same matching procedure. If a match is found, that
+      <literal>.dtbauto</literal> section will be loaded and will override <literal>.dtb</literal> if
+      present.</para></listitem>
 
       <listitem><para>Zero or more <literal>.efifw</literal> sections for the firmware image. It works
       in many ways similar to <literal>.dtbauto</literal> sections. <command>systemd-stub</command>
@@ -103,12 +104,12 @@
       matching firmware will be loaded.
       </para></listitem>
 
-      <listitem><para>Zero or more <literal>.hwids</literal> sections with hardware IDs of the machines to
+      <listitem><para>An optional <literal>.hwids</literal> section with hardware IDs of the machines to
       match DeviceTrees. <command>systemd-stub</command> will use the SMBIOS data to calculate hardware IDs
       of the machine (as per <ulink
       url="https://learn.microsoft.com/en-us/windows-hardware/drivers/install/specifying-hardware-ids-for-a-computer">specification</ulink>),
-      and then it will try to find any of them in each of the <literal>.hwids</literal> sections. The first
-      matching section will be used.</para></listitem>
+      and then it will try to find any of them in the <literal>.hwids</literal> section. The first
+      matching entry will be used.</para></listitem>
 
       <listitem><para>An optional <literal>.uname</literal> section with the kernel version information, i.e.
       the output of <command>uname -r</command> for the kernel included in the <literal>.linux</literal>
@@ -130,7 +131,7 @@
     <!-- FIXME: how does .dtauto/.hwids matching interact with profiles? -->
 
     <para>In a basic UKI, the sections listed above appear at most once, with the exception of
-    <literal>.dtbauto</literal> and <literal>.hwids</literal> sections. In a multi-profile UKI,
+    <literal>.dtbauto</literal> and <literal>.efifw</literal> 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 <literal>.profile</literal> is
     defined to be used as the separator between sets of sections. The