Enhance docs for ukify and direct kernel boots (#39516)

As requested in

https://github.com/systemd/systemd/pull/39516#pullrequestreview-3407564896.

man/bootctl.xml

@@ -608,7 +608,7 @@ System:
  TPM2 Support: yes
  Boot into FW: supported                     ← does the firmware support booting into itself
 
-Current Boot Loader:                         ← details about sd-boot or another boot loader
+Current Boot Loader:                         ← details about systemd-boot or another boot loader
       Product: systemd-boot <replaceable>version</replaceable>            implementing the <ulink
     url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
      Features: ✓ Boot counting

man/systemd-boot.xml

@@ -383,10 +383,10 @@
     <para>Optionally, a random seed for early boot entropy pool provisioning is stored in
     <filename>/loader/random-seed</filename> in the ESP.</para>
 
-    <para>During initialization, <command>sd-boot</command> automatically loads all driver files placed in
+    <para>During initialization, <command>systemd-boot</command> automatically loads all driver files placed
-    the <filename>/EFI/systemd/drivers/</filename> directory of the ESP. The files placed there must have an
+    in the <filename>/EFI/systemd/drivers/</filename> directory of the ESP. The files placed there must have
-    extension of the EFI architecture ID followed by <filename>.efi</filename> (e.g. for x86-64 this means a
+    an extension of the EFI architecture ID followed by <filename>.efi</filename> (e.g. for x86-64 this means
-    suffix of <filename>x64.efi</filename>). This may be used to automatically load file system drivers and
+    a suffix of <filename>x64.efi</filename>). This may be used to automatically load file system drivers and
     similar, to extend the native firmware support.</para>
 
     <para>Enrollment of Secure Boot variables can be performed manually or automatically if files are available
@@ -711,18 +711,26 @@ uki-url http://example.com/somedir/fooos.efi</programlisting>
   <refsect1>
     <title>Using <command>systemd-boot</command> in virtual machines</title>
 
-    <para>When using qemu with OVMF (UEFI Firmware for virtual machines) the <option>-kernel</option> switch
+    <para>When using <ulink url="https://www.qemu.org/docs/master/">qemu</ulink> with
-    works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux
+    <ulink url="https://www.linux-kvm.org/downloads/lersek/ovmf-whitepaper-c770f8c.txt">OVMF</ulink>
-    kernels. Example command line for loading <command>systemd-boot</command> on x64:</para>
+    (UEFI Firmware for virtual machines) the <option>-kernel</option> switch works not only for linux
+    kernels, but for any EFI binary, including <filename>systemd-boot</filename> and unified linux kernels
+    (UKIs). Example command line for loading <command>systemd-boot</command> on x64:</para>
 
     <para>
-      <command>qemu-system-x86_64 <replaceable>[ ... ]</replaceable>
+      <command>qemu-system-x86_64
-      -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi</command>
+      -drive if=pflash,format=qcow2,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE_4M.qcow2
+      -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
+      -drive file=<replaceable>...</replaceable>
+      <replaceable>[ ... ]</replaceable>
+      </command>
     </para>
 
-    <para>systemd-boot will detect that it was started directly instead of being loaded from ESP and will
+    <para>(The path to the firmware file might need to be adjusted depending on the distribution.)
-    search for the ESP in that case, taking into account boot order information from the hypervisor (if
+    <filename>systemd-boot</filename> will detect that it was started directly instead of being loaded from
-    available).</para>
+    ESP and will search for the ESP in that case, taking into account boot order information from the
+    hypervisor (if available). Note that for this to yield a useful result, another <option>-drive</option>
+    argument needs to be used to attach an actual disk image with an ESP.</para>
   </refsect1>
 
   <refsect1>

man/ukify.xml

@@ -45,11 +45,19 @@
     <title>Description</title>
 
     <para><command>ukify</command> is a tool whose primary purpose is to combine components (usually a
-    kernel, an initrd, and a UEFI boot stub) to create a
+    kernel, an initrd, and the
-    <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink>
+    <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> UEFI
-    — a PE binary that can be executed by the firmware to start the embedded linux kernel.
+    stub) to create a <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified
-    See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    Kernel Image (UKI)</ulink> — a single PE binary that boots the system. When the UKI is executed, the stub
-    for details about the stub.</para>
+    extracts and boots the embedded linux kernel. The UKI can be started directly by the firmware or through
+    a boot loader. When used with <ulink url="https://www.qemu.org/docs/master/">qemu</ulink>, a UKI can also
+    be executed through "direct kernel boot", see example below.</para>
+
+    <para><command>ukify</command> can also be used generate other types of UKI-like images, in particular
+    extensions. See the description of the <command>build</command> verb below. <command>ukify</command> can
+    also generate certificates and keys for SecureBoot and PCR signing, see the description of the
+    <command>genkey</command> verb below. <command>ukify</command> can also print detailed information about
+    unified kernel images, see the description of <command>inspect</command> verb below.</para>
   </refsect1>
 
   <refsect1>
@@ -719,6 +727,27 @@
       <para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para>
     </example>
 
+    <example>
+      <title>Direct kernel boot in a virtual machine</title>
+
+      <para>When using <ulink url="https://www.qemu.org/docs/master/">qemu</ulink> with
+      <ulink url="https://www.linux-kvm.org/downloads/lersek/ovmf-whitepaper-c770f8c.txt">OVMF</ulink>
+      (UEFI Firmware for virtual machines) the <option>-kernel</option> switch can be used directly with a
+      UKI. Example:</para>
+
+      <para>
+        <command>qemu-kvm
+        -drive if=pflash,format=qcow2,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE_4M.qcow2
+        -kernel <filename index='false'>./vmlinuz.unsigned.efi</filename>
+        <replaceable>[ ... ]</replaceable>
+        </command>
+      </para>
+
+      <para>(The path to the firmware file might need to be adjusted depending on the distribution.) Usually,
+      another <option>-drive</option> argument would to be used to attach an actual disk image, but this
+      is not required.</para>
+    </example>
+
     <example>
       <title>All the bells and whistles</title>