[PATCH v2 pve-docs 16/16] qm: document the efi-firmware VM option

[Christian Ludwig <christian_ludwig@genua.de>]

Describe how to set and remove a custom EFI firmware image.

Signed-off-by: Christian Ludwig <christian_ludwig@genua.de>
---
 qm.adoc | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 5b46cdc..4186067 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1246,6 +1246,54 @@ NOTE: The markers `ms-cert=2023` and `ms-cert=2023w` may indicate partial
 enrollment. The VM start task log will warn about this. You should apply the
 enrollment procedure for such EFI disks too.
 
+[[qm_custom_efi_firmware]]
+Custom EFI Firmware
+^^^^^^^^^^^^^^^^^^^
+
+By default, {pve} uses the system-provided OVMF firmware images. If you need a
+custom or vendor-specific EFI firmware code image, you can override the default
+firmware with the `efi-firmware` VM option.
+
+The firmware image must first be uploaded to a storage that has the
+`efi-firmware` content type enabled.
+
+To configure a VM to use a custom firmware image:
+
+----
+# qm set <vmid> -efi-firmware <storage>:efi-firmware/<name>
+----
+
+For example:
+
+----
+# qm set 100 -efi-firmware local:efi-firmware/custom-ovmf-code.fd
+----
+
+NOTE: The `efi-firmware` option requires `bios` to be set to `ovmf`.
+
+The custom image replaces the firmware code (pflash0) only. The EFI vars disk
+(`efidisk0`) keeps its contents, which are created from the vars template of
+the system-provided firmware. If they do not match the custom image, the guest
+may fail to boot. A matching vars image can be imported with:
+
+----
+# qm set <vmid> -efidisk0 <storage>:0,efitype=4m,pre-enrolled-keys=0,import-from=<source>
+----
+
+Confidential VMs (AMD SEV-SNP, Intel TDX) load the firmware read-only via
+`-bios` and use no EFI vars disk at all, so this does not apply to them. For
+that reason, the web interface only offers custom firmware images for such VMs,
+through the 'BIOS' entry in the 'Hardware' panel of a VM.
+
+The firmware image is not copied when a VM migrates, so it has to be on a
+shared storage.
+
+To remove a custom firmware assignment and revert to the default OVMF image:
+
+----
+# qm set <vmid> -delete efi-firmware
+----
+
 [[qm_tpm]]
 Trusted Platform Module (TPM)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.34.1