From 4808c1686b6f49edf9ad7a9596de839aa73b6503 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Sat, 1 Nov 2025 12:15:49 +0100
Subject: [PATCH] man/sd-boot: add some meat to the direct kernel boot example

Unfortunately qemu still default to BIOS boot, so for the direct kernel
boot with an efi file to be of any use, the complex param used to switch
to UEFI mode needs to be provided.

Also add some links to qemu and OVMF.
---
 man/systemd-boot.xml | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml
index 94eaae2d6bb..cc623a9198c 100644
--- a/man/systemd-boot.xml
+++ b/man/systemd-boot.xml
@@ -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
-    works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux
-    kernels. Example command line for loading <command>systemd-boot</command> on x64:</para>
+    <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 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>
-      -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi</command>
+      <command>qemu-system-x86_64
+      -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
-    search for the ESP in that case, taking into account boot order information from the hypervisor (if
-    available).</para>
+    <para>(The path to the firmware file might need to be adjusted depending on the distribution.)
+    <filename>sd-boot</filename> will detect that it was started directly instead of being loaded from 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>
-- 
2.47.3