From c5f690be75963432d44ac3eb437d5309231db260 Mon Sep 17 00:00:00 2001 From: Kashyap Chamarthy Date: Wed, 11 Sep 2019 16:34:54 +0200 Subject: [PATCH] docs: Expand the "BIOS bootloader" documentation for domainCaps Rewrite some parts for clarity, elaborate the meaning of some of the XML attributes. And where necessary, distinguish that we're dealing with two different XML documents here: - the domainCapabilities XML, to detect the host "hypervisor" (QEMU/KVM) capabilities, and what libvirt knows about them. - the guest XML definition, i.e. what features a guest can use, based on the capabilities (of QEMU and libvirt and the host) reported in the domainCapabilities XML. Signed-off-by: Kashyap Chamarthy Signed-off-by: Michal Privoznik Reviewed-by: Michal Privoznik --- docs/formatdomaincaps.html.in | 49 ++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 18 deletions(-) diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index bc99d37856..0488d986ee 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -143,38 +143,51 @@ <domainCapabilities> -

The firmware enum corresponds to - firmware attribute of the os element. - Plain presence of this enum means that libvirt is capable of so - called firmware auto selection. The listed values then represent - accepted values for the domain attribute. Only values for which - there exists a firmware descriptor that matches machine type and - architecture are listed, i.e. those which won't cause a failure - on domain startup. +

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 + fimware binary path, its architecture, supported machine types, + NVRAM template, etc. This ensures that the reported values won't + cause a failure on guest boot.

For the loader element, the following can occur:

value
-
List of known loader paths. Currently this is only used - to advertise known locations of OVMF binaries for qemu. Binaries - will only be listed if they actually exist on disk.
+
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.
type
-
Whether loader is a typical BIOS (rom) or - an UEFI binary (pflash). This refers to - type attribute of the <loader/> - element.
+
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>. +
readonly
Options for the readonly attribute of the - <loader/> element.
+ <loader/> element in the domain XML.
secure
Options for the secure attribute of the - <loader/> element. Note, that yes is listed - only if there is a firmware that supports it.
+ <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.

CPU configuration

-- GitLab