Grammar and formatting for DeviceTree docs (#35050)

10 files changed, 81 insertions, 73 deletions

diff --git a/NEWS b/NEWS
index abd7d887c8..54d2624951 100644
--- a/NEWS
+++ b/NEWS
@@ -186,7 +186,7 @@ CHANGES WITH 257 in spe:
 
         * The systemd.machine_id= kernel command line parameter interpreted by
           PID 1 now supports an additional special value: if "firmware" is
-          specified the machine ID is initialized from the SMBIOS/Devicetree
+          specified the machine ID is initialized from the SMBIOS/DeviceTree
           system UUID. (Previously this was already done in VM environments,
           this extends the concept to any system, but only on explicit request
           via this option.)
@@ -276,10 +276,10 @@ CHANGES WITH 257 in spe:
           show up as .device units in systemd.
 
         * The firmware_node/sun sysfs attribute will now be used (if available)
-          for naming slot-based network interfaces,
-          i.e. ID_NET_NAME_SLOT. Moreover the interface aliases specified in
-          Devicetree are now searched for both on the interfaces parent device
-          (as before) and the device itself (new).
+          for naming slot-based network interfaces, i.e. ID_NET_NAME_SLOT.
+          Moreover the interface aliases specified in DeviceTree are now
+          searched for both on the interface's parent device (as before) and
+          the device itself (new).
 
         * Various USB hardware wallets have are now recognized by udev via a
           .hwdb file, and get the ID_HARDWARE_WALLET= property set, which
@@ -2012,7 +2012,7 @@ CHANGES WITH 255:
           respective SBAT sections, so that they can be revoked individually if
           needed.
 
-        * systemd-boot will no longer load unverified Devicetree blobs when UEFI
+        * systemd-boot will no longer load unverified DeviceTree blobs when UEFI
           SecureBoot is enabled. For more details see:
           https://github.com/systemd/systemd/security/advisories/GHSA-6m6p-rjcq-334c
 
@@ -2033,7 +2033,7 @@ CHANGES WITH 255:
           command-line addons before measuring them in TPM2 PCR 12, in a single
           measurement, instead of measuring them individually.
 
-        * systemd-stub will now measure and load Devicetree Blob addons, which
+        * systemd-stub will now measure and load DeviceTree Blob addons, which
           are searched and loaded following the same model as the existing
           kernel command-line addons.
 
@@ -2041,7 +2041,7 @@ CHANGES WITH 255:
           passed from systemd-boot when running inside Confidential VMs with UEFI
           SecureBoot enabled.
 
-        * systemd-stub will now load a Devicetree blob even if the firmware did
+        * systemd-stub will now load a DeviceTree blob even if the firmware did
           not load any beforehand (e.g.: for ACPI systems).
 
         * ukify is no longer considered experimental, and now ships in /usr/bin/.
@@ -4355,7 +4355,7 @@ CHANGES WITH 252 🎃:
         * 'udevadm wait' will now listen to kernel uevents too when called with
           --initialized=no.
 
-        * When naming network devices udev will now consult the Devicetree
+        * When naming network devices udev will now consult the DeviceTree
           "alias" fields for the device.
 
         * systemd-udev will now create infiniband/by-path and
diff --git a/docs/TPM2_PCR_MEASUREMENTS.md b/docs/TPM2_PCR_MEASUREMENTS.md
index daee33980b..2931c22be8 100644
--- a/docs/TPM2_PCR_MEASUREMENTS.md
+++ b/docs/TPM2_PCR_MEASUREMENTS.md
@@ -41,7 +41,7 @@ used for new, additional measurements.
 
 ## PCR Measurements Made by `systemd-boot` (UEFI)
 
-### PCS 5, `EV_EVENT_TAG`, "loader.conf"
+### PCS 5, `EV_EVENT_TAG`, `loader.conf`
 
 The content of `systemd-boot`'s configuration file, `loader/loader.conf`, is
 measured as a tagged event.
@@ -52,7 +52,7 @@ measured as a tagged event.
 
 → **Measured hash** covers the content of `loader.conf` as it is read from the ESP.
 
-### PCR 12, `EV_IPL`, "Kernel Command Line"
+### PCR 12, `EV_IPL`, kernel command line
 
 If the kernel command line was specified explicitly (by the user or in a Boot
 Loader Specification Type #1 file), the kernel command line passed to the
@@ -70,7 +70,7 @@ trailing NUL bytes).
 
 ## PCR Measurements Made by `systemd-stub` (UEFI)
 
-### PCR 11, `EV_IPL`, "PE Section Name"
+### PCR 11, `EV_IPL`, PE section name
 
 A measurement is made for each PE section of the UKI that is defined by the
 [UKI
@@ -87,7 +87,7 @@ both types of records appear interleaved in the event log.
 
 → **Measured hash** covers the PE section name in ASCII (*including* a trailing NUL byte!).
 
-### PCR 11, `EV_IPL`, "PE Section Data"
+### PCR 11, `EV_IPL`, PE section data
 
 Happens once for each UKI-defined PE section of the UKI, in the canonical UKI
 PE section order, as per the UKI specification, see above.
@@ -96,7 +96,7 @@ PE section order, as per the UKI specification, see above.
 
 → **Measured hash** covers the (binary) PE section contents.
 
-### PCR 12, `EV_IPL`, "Kernel Command Line"
+### PCR 12, `EV_IPL`, kernel command line
 
 Might happen up to three times, for kernel command lines from:
 
@@ -110,37 +110,37 @@ UTF-16.
 → **Measured hash** covers the literal kernel command line in UTF-16 (without any
 trailing NUL bytes).
 
-### PCR 12, `EV_EVENT_TAG`, "Devicetrees"
+### PCR 12, `EV_EVENT_TAG`, DeviceTrees
 
-Devicetree addons are measured individually as a tagged event.
+DeviceTree addons are measured individually as a tagged event.
 
 → **Event Tag** `0x6c46f751`
 
-→ **Description** the addon filename.
+→ **Description** is the addon filename.
 
-→ **Measured hash** covers the content of the Devicetree.
+→ **Measured hash** covers the content of the DeviceTree.
 
-### PCR 12, `EV_EVENT_TAG`, "Initrd addons"
+### PCR 12, `EV_EVENT_TAG`, initrd addons
 
 Initrd addons are measured individually as a tagged event.
 
 → **Event Tag** `0x49dffe0f`
 
-→ **Description** the addon filename.
+→ **Description** is the addon filename.
 
 → **Measured hash** covers the contents of the initrd.
 
-### PCR 12, `EV_EVENT_TAG`, "Ucode addons"
+### PCR 12, `EV_EVENT_TAG`, ucode addons
 
 Ucode addons are measured individually as a tagged event.
 
 → **Event Tag** `0xdac08e1a`
 
-→ **Description** the addon filename.
+→ **Description** is the addon filename.
 
 → **Measured hash** covers the contents of the ucode initrd.
 
-### PCR 12, `EV_IPL`, "Per-UKI Credentials initrd"
+### PCR 12, `EV_IPL`, per-uki credentials initrd
 
 → **Description** in the event log record is the constant string "Credentials
 initrd" in UTF-16.
@@ -148,7 +148,7 @@ initrd" in UTF-16.
 → **Measured hash** covers the per-UKI credentials cpio archive (which is generated
  on-the-fly by `systemd-stub`).
 
-### PCR 12, `EV_IPL`, "Global Credentials initrd"
+### PCR 12, `EV_IPL`, global credentials initrd
 
 → **Description** in the event log record is the constant string "Global
 credentials initrd" in UTF-16.
@@ -156,7 +156,7 @@ credentials initrd" in UTF-16.
 → **Measured hash** covers the global credentials cpio archive (which is generated
 on-the-fly by `systemd-stub`).
 
-### PCR 13, `EV_IPL`, "sysext initrd"
+### PCR 13, `EV_IPL`, sysext initrd
 
 → **Description** in the event log record is the constant string "System extension
 initrd" in UTF-16.
@@ -166,7 +166,7 @@ on-the-fly by `systemd-stub`).
 
 ## PCR Measurements Made by `systemd-pcrextend` (Userspace)
 
-### PCR 11, "Boot Phases"
+### PCR 11, boot phases
 
 The `systemd-pcrphase.service`, `systemd-pcrphase-initrd.service`,
 `systemd-pcrphase-sysinit.service` services will measure the boot phase reached
@@ -178,7 +178,7 @@ choose to define additional/different phases.)
 → **Measured hash** covers the phase string (in UTF-8, without trailing NUL
 bytes).
 
-### PCR 15, "Machine ID"
+### PCR 15, machine ID
 
 The `systemd-pcrmachine.service` service will measure the machine ID (as read
 from `/etc/machine-id`) during boot.
@@ -187,7 +187,7 @@ from `/etc/machine-id`) during boot.
 formatted in hexadecimal lowercase characters (in UTF-8, without trailing NUL
 bytes).
 
-### PCR 15, "File System"
+### PCR 15, file system
 
 The `systemd-pcrfs-root.service` and `systemd-pcrfs@.service` services will
 measure a string identifying a specific file system, typically covering the
@@ -200,7 +200,7 @@ without trailing NUL bytes).
 
 ## PCR Measurements Made by `systemd-cryptsetup` (Userspace)
 
-### PCR 15, "Volume Key"
+### PCR 15, volume key
 
 The `systemd-cryptsetup@.service` service will measure a key derived from the
 LUKS volume key of a specific encrypted volume, typically covering the backing
diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml
index 6625fca91e..1ba6a5bdbf 100644
--- a/man/systemd-stub.xml
+++ b/man/systemd-stub.xml
@@ -59,58 +59,66 @@
       <!-- Let's keep this in the canonical order we also measure the sections by, i.e. as in
            src/fundamental/uki.h's UnifiedSection enum -->
 
-      <listitem><para>A <literal>.linux</literal> section with the ELF Linux kernel
-      image. (Required)</para></listitem>
+      <listitem><para>A <literal>.linux</literal> section with the ELF Linux kernel image.
+      This section is required.</para></listitem>
 
-      <listitem><para>An <literal>.osrel</literal> section with OS release information, i.e. the contents of
-      the <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
-      of the OS the kernel belongs to.</para></listitem>
+      <listitem><para>An optional <literal>.osrel</literal> section with OS release information, i.e. the
+      contents of the
+      <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file of
+      the OS the kernel belongs to.</para></listitem>
 
-      <listitem><para>A <literal>.cmdline</literal> section with the kernel command line to pass to the
-      invoked kernel.</para></listitem>
+      <listitem><para>An optional <literal>.cmdline</literal> section with the kernel command line to pass to
+      the invoked kernel.</para></listitem>
 
-      <listitem><para>An <literal>.initrd</literal> section with the initrd.</para></listitem>
+      <listitem><para>An optional <literal>.initrd</literal> section with the initrd.</para></listitem>
 
-      <listitem><para>A <literal>.ucode</literal> section with an initrd containing microcode, to be handed
-      to the kernel before any other initrd. This initrd must not be compressed.</para></listitem>
+      <listitem><para>An optional <literal>.ucode</literal> section with an initrd containing microcode, to
+      be handed to the kernel before any other initrd. This initrd must not be compressed.</para></listitem>
 
-      <listitem><para>A <literal>.splash</literal> section with an image (in the Windows
+      <listitem><para>An optional <literal>.splash</literal> section with an image (in the Windows
       <filename>.BMP</filename> format) to show on screen before invoking the kernel.</para></listitem>
 
-      <listitem><para>A <literal>.dtb</literal> section with a compiled binary DeviceTree.</para></listitem>
-
-      <listitem><para>Zero or more <literal>.dtbauto</literal> sections. Stub will always try to find first matching one.
-      Matching process extracts first <varname>compatible</varname> string from <literal>.dtbauto</literal>
-      section and compares it with the first Devicetree's <varname>compatible</varname> string supplied by
-      the firmware in configuration tables. If firmware does not provide Devicetree, matching with
-      <varname>.hwids</varname>  section will be used instead. Stub will use 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>),
-      then it will proceed to trying to find any of them in <literal>.hwids</literal> section and will use first
-      matching entry's <varname>compatible</varname>  as a search key among the <literal>.dtbauto</literal>
-      entries, in a similar fashion as the use of <varname>compatible</varname> string read from the firmware
-      provided Devicetree was described before. First matching <literal>.dtbauto</literal> section will be
+      <listitem><para>An optional <literal>.dtb</literal> section with a compiled binary DeviceTree.
+      </para></listitem>
+
+      <listitem><para>Zero or more <literal>.dtbauto</literal> sections. <filename>systemd-stub</filename>
+      will always use the first matching one. The match is performed by taking the first DeviceTree's
+      <varname>compatible</varname> string supplied by the firmware in configuration tables and comparing it
+      with the first <varname>compatible</varname> string from each of the <literal>.dtbauto</literal>
+      sections. If the firmware does not provide a DeviceTree, the match is done using the
+      <varname>.hwids</varname> section instead. After selecting a <literal>.hwids</literal> section (see the
+      description below), the <varname>compatible</varname> 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 <varname>.dtb</varname> if present.</para></listitem>
 
-      <listitem><para>A <literal>.hwids</literal> section with hardware IDs of the machines to match Devicetrees (refer to <literal>.dtbauto</literal> section description).</para></listitem>
+      <listitem><para>Zero or more <literal>.hwids</literal> sections with hardware IDs of the machines to
+      match DeviceTrees. <filename>systemd-stub</filename> 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>
 
-      <listitem><para>A <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>
+      <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>
       section.</para></listitem>
 
-      <listitem><para>An <literal>.sbat</literal> section with
-      <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">SBAT</ulink> revocation
-      metadata.</para></listitem>
+      <listitem><para>An optional <literal>.sbat</literal> section with
+      <ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">SBAT</ulink> revocation metadata.
+      </para></listitem>
 
-      <listitem><para>A <literal>.pcrsig</literal> 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
+      <listitem><para>An optional <literal>.pcrsig</literal> 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.</para></listitem>
 
-      <listitem><para>A <literal>.pcrpkey</literal> section with a public key in the PEM format matching the
-      signature data in the <literal>.pcrsig</literal> section.</para></listitem>
+      <listitem><para>An optional <literal>.pcrpkey</literal> section with a public key in the PEM format
+      matching the signature data in the <literal>.pcrsig</literal> section.</para></listitem>
     </itemizedlist>
 
-    <para>In a basic UKI, the sections listed above appear at most once. In a multi-profile UKI,
+    <!-- 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,
     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
@@ -206,7 +214,7 @@
       <listitem><para>Similarly, files
       <filename><replaceable>foo</replaceable>.efi.extra.d/*.addon.efi</filename> are loaded and verified as
       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
+      command line parameters (<literal>.cmdline</literal> section), or DeviceTree blobs
       (<literal>.dtb</literal> section), additional initrds (<literal>.initrd</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
diff --git a/man/systemd.net-naming-scheme.xml b/man/systemd.net-naming-scheme.xml
index b9e5cd9050..2a71a9a23f 100644
--- a/man/systemd.net-naming-scheme.xml
+++ b/man/systemd.net-naming-scheme.xml
@@ -123,7 +123,7 @@
 
                   <row>
                     <entry><replaceable>prefix</replaceable><constant>d</constant><replaceable>number</replaceable></entry>
-                    <entry>Devicetree alias index</entry>
+                    <entry>DeviceTree alias index</entry>
                   </row>
 
                 </tbody>
diff --git a/src/boot/efi/UEFI_SECURITY.md b/src/boot/efi/UEFI_SECURITY.md
index 55e66dbcc9..78e9c4e16c 100644
--- a/src/boot/efi/UEFI_SECURITY.md
+++ b/src/boot/efi/UEFI_SECURITY.md
@@ -54,7 +54,7 @@ libraries (such as OpenSSL or gnu-efi) are linked, embedded, or used.
 
 ## Additional Resources
 BLS Type #1 entries allow the user to load two types of additional resources that can affect the system
-before `ExitBootServices()` has been called — kernel command line arguments and Devicetree blobs — that are
+before `ExitBootServices()` has been called — kernel command line arguments and DeviceTree blobs — that are
 not validated before use, as they do not carry signatures. For this reason, when SecureBoot is enabled,
 loading these resources is automatically disabled. There is no override for this security mechanism, neither
 at build time nor at runtime. Note that initrds are also not verified in BLS Type #1 configurations, for
@@ -62,7 +62,7 @@ compatibility with how SecureBoot has been traditionally handled on Linux-based
 only load them after `ExitBootServices()` has been called.
 
 Another mechanism is supported by `systemd-boot` and `systemd-stub` to add additional payloads to the boot
-process: "addons". Addons are PE signed binaries that can carry kernel command line arguments or Devicetree
+process: "addons". Addons are PE signed binaries that can carry kernel command line arguments or DeviceTree
 blobs (more payload types might be added in the future).
 In contrast to the user-specified additions in the Type #1 case
 described above, these addons are loaded through the UEFI image loading protocol, and thus are subject to
diff --git a/src/boot/efi/devicetree.c b/src/boot/efi/devicetree.c
index f3563f296f..842b96a97d 100644
--- a/src/boot/efi/devicetree.c
+++ b/src/boot/efi/devicetree.c
@@ -178,8 +178,8 @@ bool firmware_devicetree_exists(void) {
         return !!find_configuration_table(MAKE_GUID_PTR(EFI_DTB_TABLE));
 }
 
-/* This function checks if the firmware provided Devicetree
- * and a UKI provided Devicetree contain the same first entry
+/* This function checks if the firmware provided DeviceTree
+ * and a UKI provided DeviceTree contain the same first entry
  * on their respective "compatible" fields (which usually defines
  * the actual device model). More specifically, given the FW/UKI
  * "compatible" property pair:
diff --git a/src/boot/measure.c b/src/boot/measure.c
index 9e6295b9da..ed253b79f0 100644
--- a/src/boot/measure.c
+++ b/src/boot/measure.c
@@ -98,7 +98,7 @@ static int help(int argc, char *argv[], void *userdata) {
                "     --initrd=PATH       Path to initrd image file              %7$s .initrd\n"
                "     --ucode=PATH        Path to microcode image file           %7$s .ucode\n"
                "     --splash=PATH       Path to splash bitmap file             %7$s .splash\n"
-               "     --dtb=PATH          Path to Devicetree file                %7$s .dtb\n"
+               "     --dtb=PATH          Path to DeviceTree file                %7$s .dtb\n"
                "     --uname=PATH        Path to 'uname -r' file                %7$s .uname\n"
                "     --sbat=PATH         Path to SBAT file                      %7$s .sbat\n"
                "     --pcrpkey=PATH      Path to public key for PCR signatures  %7$s .pcrpkey\n"
diff --git a/src/fundamental/tpm2-pcr.h b/src/fundamental/tpm2-pcr.h
index f903ec3e3b..d8728bf88e 100644
--- a/src/fundamental/tpm2-pcr.h
+++ b/src/fundamental/tpm2-pcr.h
@@ -47,7 +47,7 @@ enum {
 /* The tag used for EV_EVENT_TAG event log records covering the boot loader config */
 #define LOADER_CONF_EVENT_TAG_ID UINT32_C(0xf5bc582a)
 
-/* The tag used for EV_EVENT_TAG event log records covering Devicetree blobs */
+/* The tag used for EV_EVENT_TAG event log records covering DeviceTree blobs */
 #define DEVICETREE_ADDON_EVENT_TAG_ID UINT32_C(0x6c46f751)
 
 /* The tag used for EV_EVENT_TAG event log records covering initrd addons */
diff --git a/src/hostname/hostnamed.c b/src/hostname/hostnamed.c
index d2444dbf2d..cc538ce979 100644
--- a/src/hostname/hostnamed.c
+++ b/src/hostname/hostnamed.c
@@ -502,7 +502,7 @@ try_devicetree:
                 return NULL;
         }
 
-        /* Note that the Devicetree specification uses the very same vocabulary
+        /* Note that the DeviceTree specification uses the very same vocabulary
          * of chassis types as we do, hence we do not need to translate these types:
          *
          * https://github.com/devicetree-org/devicetree-specification/blob/master/source/chapter3-devicenodes.rst */
diff --git a/src/udev/udev-builtin-net_id.c b/src/udev/udev-builtin-net_id.c
index 9e50603c63..09c04b9a7f 100644
--- a/src/udev/udev-builtin-net_id.c
+++ b/src/udev/udev-builtin-net_id.c
@@ -924,7 +924,7 @@ static int names_devicetree(sd_device *dev, const char *prefix, EventMode mode)
                 char str[ALTIFNAMSIZ];
                 if (snprintf_ok(str, sizeof str, "%sd%u", prefix, i))
                         udev_builtin_add_property(dev, mode, "ID_NET_NAME_ONBOARD", str);
-                log_device_debug(dev, "Devicetree identifier: alias_index=%u %s \"%s\"",
+                log_device_debug(dev, "DeviceTree identifier: alias_index=%u %s \"%s\"",
                                  i, special_glyph(SPECIAL_GLYPH_ARROW_RIGHT), str + strlen(prefix));
                 return 0;
         }