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

[Kashyap Chamarthy]

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