[libvirt] [PATCH v1] docs: Expand the "BIOS bootloader" documentation for domainCaps

[Michal Privoznik]

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 at 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