Recommend that users take advantage of firmware autoselection and discourage providing paths manually.
Signed-off-by: Andrea Bolognani <[email protected]> --- 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
