[libvirt] [PATCH v1] 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 <kchamart@redhat.com> --- docs/formatdomaincaps.html.in | 53 ++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index bc99d378567a553afe682bc522e7a753b2d805fc..a8d970934df2c0ce8c41eb4958c94fbdf96ef8e0 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -127,7 +127,7 @@ <value>/usr/share/OVMF/OVMF_CODE.fd</value> <enum name='type'> <value>rom</value> - <value>pflash</value> + <value>pflapsh</value> </enum> <enum name='readonly'> <value>yes</value> @@ -143,38 +143,53 @@ <domainCapabilities> </pre> - <p>The <code>firmware</code> enum corresponds to - <code>firmware</code> attribute of the <code>os</code> 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. + <p>The <code>firmware</code> enum corresponds to the + <code>firmware</code> attribute of the <code>os</code> 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 <code>firmware</code> enum reports only those + values for which a firmware "descriptor file" exists on the host + -- a small JSON document that describes details about a given UEFI + binary on the host, e.g. the fimware binary path, its + architecture, supported machine type, NVRAM template, etc. This + ensures that the reported values won't cause a failure on guest + boot. (The firmware "descriptor files" are typically shipped + Linux distribution as part of the firmware package, + e.g. EDK2/OVMF.) </p> <p>For the <code>loader</code> element, the following can occur:</p> <dl> <dt><code>value</code></dt> - <dd>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.</dd> + <dd>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.</dd> <dt><code>type</code></dt> - <dd>Whether loader is a typical BIOS (<code>rom</code>) or - an UEFI binary (<code>pflash</code>). This refers to - <code>type</code> attribute of the <loader/> - element.</dd> + <dd>Whether the boot loader is a typical BIOS (<code>rom</code>) + or a UEFI firmware (<code>pflash</code>). Each <code>value</code> + sub-element under the <code>type</code> enum represents a possible + value for the <code>type</code> attribute for the <loader/> + element in the domain XML. E.g. the presence + of <code>pfalsh</code> under the <code>type</code> enum means that + a domain XML can use UEFI firmware via: <loader/> + type="pflash" ...>/path/to/the/firmware/binary/</loader>. + </dd> <dt><code>readonly</code></dt> <dd>Options for the <code>readonly</code> attribute of the - <loader/> element.</dd> + <loader/> element in the domain XML.</dd> <dt><code>secure</code></dt> <dd>Options for the <code>secure</code> attribute of the - <loader/> element. Note, that <code>yes</code> is listed - only if there is a firmware that supports it.</dd> + <loader/> element in the domain XML. Note that the + value <code>yes</code> 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.</dd> </dl> <h3><a id="elementsCPU">CPU configuration</a></h3> -- 2.21.0
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 <kchamart@redhat.com> --- docs/formatdomaincaps.html.in | 53 ++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index bc99d37856..a8d970934d 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -127,7 +127,7 @@ <value>/usr/share/OVMF/OVMF_CODE.fd</value> <enum name='type'> <value>rom</value> - <value>pflash</value> + <value>pflapsh</value> </enum> <enum name='readonly'> <value>yes</value> @@ -143,38 +143,53 @@ <domainCapabilities> </pre> - <p>The <code>firmware</code> enum corresponds to - <code>firmware</code> attribute of the <code>os</code> 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. + <p>The <code>firmware</code> enum corresponds to the + <code>firmware</code> attribute of the <code>os</code> 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 <code>firmware</code> enum reports only those + values for which a firmware "descriptor file" exists on the host + -- a small JSON document that describes details about a given UEFI + binary on the host, e.g. the fimware binary path, its + architecture, supported machine type, NVRAM template, etc. This + ensures that the reported values won't cause a failure on guest + boot. (The firmware "descriptor files" are typically shipped + Linux distribution as part of the firmware package, + e.g. EDK2/OVMF.) </p> <p>For the <code>loader</code> element, the following can occur:</p> <dl> <dt><code>value</code></dt> - <dd>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.</dd> + <dd>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.</dd> <dt><code>type</code></dt> - <dd>Whether loader is a typical BIOS (<code>rom</code>) or - an UEFI binary (<code>pflash</code>). This refers to - <code>type</code> attribute of the <loader/> - element.</dd> + <dd>Whether the boot loader is a typical BIOS (<code>rom</code>) + or a UEFI firmware (<code>pflash</code>). Each <code>value</code> + sub-element under the <code>type</code> enum represents a possible + value for the <code>type</code> attribute for the <loader/> + element in the domain XML. E.g. the presence + of <code>pfalsh</code> under the <code>type</code> enum means that + a domain XML can use UEFI firmware via: <loader/> + type="pflash" ...>/path/to/the/firmware/binary/</loader>. + </dd> <dt><code>readonly</code></dt> <dd>Options for the <code>readonly</code> attribute of the - <loader/> element.</dd> + <loader/> element in the domain XML.</dd> <dt><code>secure</code></dt> <dd>Options for the <code>secure</code> attribute of the - <loader/> element. Note, that <code>yes</code> is listed - only if there is a firmware that supports it.</dd> + <loader/> element in the domain XML. Note that the + value <code>yes</code> 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.</dd> </dl> <h3><a id="elementsCPU">CPU configuration</a></h3> -- 2.21.0
On 9/11/19 4:34 PM, Kashyap Chamarthy wrote:
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 <kchamart@redhat.com> --- docs/formatdomaincaps.html.in | 53 ++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 19 deletions(-)
diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index bc99d378567a553afe682bc522e7a753b2d805fc..a8d970934df2c0ce8c41eb4958c94fbdf96ef8e0 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -127,7 +127,7 @@ <value>/usr/share/OVMF/OVMF_CODE.fd</value> <enum name='type'> <value>rom</value> - <value>pflash</value> + <value>pflapsh</value>
This looks like a unintended change.
</enum> <enum name='readonly'> <value>yes</value> @@ -143,38 +143,53 @@ <domainCapabilities> </pre>
- <p>The <code>firmware</code> enum corresponds to - <code>firmware</code> attribute of the <code>os</code> 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. + <p>The <code>firmware</code> enum corresponds to the + <code>firmware</code> attribute of the <code>os</code> 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 <code>firmware</code> enum reports only those + values for which a firmware "descriptor file" exists on the host + -- a small JSON document that describes details about a given UEFI + binary on the host, e.g. the fimware binary path, its
FW descriptors can describe a BIOS image too.
+ architecture, supported machine type, NVRAM template, etc. This + ensures that the reported values won't cause a failure on guest + boot.
(The firmware "descriptor files" are typically shipped + Linux distribution as part of the firmware package, + e.g. EDK2/OVMF.)
This is not exactly true. FW descriptors are shipped by qemu actaully. But also, I don't think users need to bother - their distro will install it when updating qemu package. ACK to the rest and pushed. Thanks for taking care of this. Michal
On Wed, Sep 11, 2019 at 05:40:02PM +0200, Michal Privoznik wrote:
On 9/11/19 4:34 PM, Kashyap Chamarthy wrote:
[...]
diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index bc99d378567a553afe682bc522e7a753b2d805fc..a8d970934df2c0ce8c41eb4958c94fbdf96ef8e0 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -127,7 +127,7 @@ <value>/usr/share/OVMF/OVMF_CODE.fd</value> <enum name='type'> <value>rom</value> - <value>pflash</value> + <value>pflapsh</value>
This looks like a unintended change.
Oops, indeed; sorry. [...]
+ <code>firmware</code> attribute of the <code>os</code> 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 <code>firmware</code> enum reports only those + values for which a firmware "descriptor file" exists on the host + -- a small JSON document that describes details about a given UEFI + binary on the host, e.g. the fimware binary path, its
FW descriptors can describe a BIOS image too.
Yes; missed to be careful here.
+ architecture, supported machine type, NVRAM template, etc. This + ensures that the reported values won't cause a failure on guest + boot.
(The firmware "descriptor files" are typically shipped + Linux distribution as part of the firmware package, + e.g. EDK2/OVMF.)
This is not exactly true. FW descriptors are shipped by qemu actaully.
Yes and no. QEMU upstream ships them in the pc-bios/descriptors. However, most major distributions Debian, Ubuntu and Fedora[*] ship them as part of edk2/edk2-ovmf packages. Because (quoting from the commit message from here[*]): [quote] - Distributions providing their own EDK2 packages would not include the descriptors from upstream QEMU, even if they otherwise package QEMU. That's beause the descriptor files in QEMU match the firmware bundled with QEMU -- but the firmware images in the distros' own EDK2 packages are different. So, if a distro provides an EDK2 package, then the same EDK2 package should offer matching descriptors. QEMU offers descriptors (soon) because QEMU technically distributes edk2 firmware binaries (soon). [Where "soon" == QEMU 4.1] - In Fedora, we need to ship them [the "descriptor files"] as part of the EDK2 package, because Fedora throws away all the firmware files that QEMU bundles, because we're [Fedora] required to rebuild everything from pristine source. [/quote] [*] https://src.fedoraproject.org/rpms/edk2/c/674b3c8a27a8
But also, I don't think users need to bother - their distro will install it when updating qemu package.
Yeah. I just wanted to add a hint for those wondering "where do I find these files".
ACK to the rest and pushed. Thanks for taking care of this.
Thanks for the quick review and merge. -- /kashyap
participants (2)
-
Kashyap Chamarthy -
Michal Privoznik