You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
109 lines
5.1 KiB
109 lines
5.1 KiB
From 495763256a6e10ff90210d54efd53f1d4f9e2544 Mon Sep 17 00:00:00 2001
|
|
Message-ID: <495763256a6e10ff90210d54efd53f1d4f9e2544.1772815313.git.jdenemar@redhat.com>
|
|
From: Andrea Bolognani <abologna@redhat.com>
|
|
Date: Mon, 23 Feb 2026 14:58:15 +0100
|
|
Subject: [PATCH] docs: Improvement related to firmware selection
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
Recommend that users take advantage of firmware autoselection
|
|
and discourage providing paths manually.
|
|
|
|
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
|
|
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
|
|
Acked-by: Gerd Hoffmann <kraxel@redhat.com>
|
|
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
|
|
(cherry picked from commit a03a8205725efec69b1fc7cc0318fa6ce79b6aa9)
|
|
|
|
https://issues.redhat.com/browse/RHEL-82645
|
|
|
|
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
|
|
---
|
|
docs/formatdomaincaps.rst | 59 ++++++++++++++++++++++-----------------
|
|
1 file changed, 34 insertions(+), 25 deletions(-)
|
|
|
|
diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst
|
|
index 22a6d5d067..3426b7c9cd 100644
|
|
--- a/docs/formatdomaincaps.rst
|
|
+++ b/docs/formatdomaincaps.rst
|
|
@@ -145,15 +145,17 @@ domains.
|
|
...
|
|
<domainCapabilities>
|
|
|
|
-The ``firmware`` enum corresponds to the ``firmware`` attribute of the ``os``
|
|
-element in the domain XML. The presence of this enum means libvirt is capable of
|
|
-the so-called firmware auto-selection feature. And the listed firmware values
|
|
-represent the accepted input in the domain XML. Note that the ``firmware`` enum
|
|
-reports only those values for which a firmware "descriptor file" exists on the
|
|
-host. Firmware descriptor file is a small JSON document that describes details
|
|
-about a given BIOS or UEFI binary on the host, e.g. the firmware binary path,
|
|
-its architecture, supported machine types, NVRAM template, etc. This ensures
|
|
-that the reported values won't cause a failure on guest boot.
|
|
+The presence of the ``firmware`` enum means that libvirt can perform firmware
|
|
+autoselection, and each of the values is guaranteed to be usable. In the
|
|
+domain XML, firmware autoselection is enabled as follows:
|
|
+
|
|
+::
|
|
+
|
|
+ <os firmware='efi'>
|
|
+ ...
|
|
+
|
|
+Autoselection is the recommended mechanism for configuring the guest firmware.
|
|
+Providing paths and other information manually is discouraged.
|
|
|
|
The ``<firmwareFeatures/>`` element :since:`(since 12.1.0)` contains one
|
|
enum for each of the features that can be used to fine-tune the firmware
|
|
@@ -196,27 +198,34 @@ such as:
|
|
would not work, since ``no`` is not one of the valid values advertised by
|
|
the ``secureBoot`` enum.
|
|
|
|
-For the ``loader`` element, the following can occur:
|
|
+The information contained in the ``<loader/>`` element is not relevant when
|
|
+using firmware autoselection, which is the recommended approach to guest
|
|
+firmware configuration, and as such can largely be ignored. Its subelements
|
|
+are the following:
|
|
|
|
``value``
|
|
- List of known firmware binary paths. Currently this is used only to advertise
|
|
- the known location of OVMF binaries for QEMU. OVMF binaries will only be
|
|
- listed if they actually exist on host.
|
|
+ One element for each known firmware binary present on the system.
|
|
+
|
|
+ Note that a binary being present here indicates that the file exists and it
|
|
+ is compatible with the architecture/machine type, but does not provide any
|
|
+ insight into which mechanism (see ``type`` below) should be used to load it.
|
|
``type``
|
|
- Whether the boot loader is a typical BIOS (``rom``) or a UEFI firmware
|
|
- (``pflash``). Each ``value`` sub-element under the ``type`` enum represents a
|
|
- possible value for the ``type`` attribute for the <loader/> element in the
|
|
- domain XML. E.g. the presence of ``pfalsh`` under the ``type`` enum means
|
|
- that a domain XML can use UEFI firmware via: <loader/> type="pflash"
|
|
- ...>/path/to/the/firmware/binary/</loader>.
|
|
+ Whether firmware can be loaded using a ``pflash`` device (UEFI only) or as
|
|
+ a ``rom`` (either UEFI or BIOS).
|
|
``readonly``
|
|
- Options for the ``readonly`` attribute of the <loader/> element in the domain
|
|
- XML.
|
|
+ Supported values for the ``readonly`` attribute of the ``<loader/>`` element
|
|
+ in the domain XML.
|
|
``secure``
|
|
- Options for the ``secure`` attribute of the <loader/> element in the domain
|
|
- XML. Note that the value ``yes`` is listed only if libvirt detects a firmware
|
|
- descriptor file that has path to an OVMF binary that supports Secure boot,
|
|
- and lists its architecture and supported machine type.
|
|
+ Supported values for the ``secure`` attribute of the ``<loader/>`` element
|
|
+ in the domain XML.
|
|
+
|
|
+ Note that the value ``yes`` is listed if libvirt detects a firmware
|
|
+ descriptor file that points to a firmware binary that implements Secure
|
|
+ Boot and is compatible with the architecture/machine type, but the UEFI
|
|
+ variable store template associated with it might not have the usual set of
|
|
+ Secure Boot certificates enrolled. To figure out whether it's actually
|
|
+ possible to enforce Secure Boot, look at the ``enrolledKeys`` enum inside
|
|
+ the ``<firmwareFeatures/>`` element instead.
|
|
|
|
CPU configuration
|
|
~~~~~~~~~~~~~~~~~
|
|
--
|
|
2.53.0
|
|
|