mirror of
https://github.com/systemd/systemd.git
synced 2024-11-27 12:13:33 +08:00
Grammar and formatting for DeviceTree docs (#35050)
This commit is contained in:
Luca Boccassi
GitHub
commit
f72fe2d73c
18
NEWS
18
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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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>An optional <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>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
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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 */
|
||||
|
||||
@ -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 */
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user