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 @@
       &lt;value&gt;/usr/share/OVMF/OVMF_CODE.fd&lt;/value&gt;
       &lt;enum name='type'&gt;
         &lt;value&gt;rom&lt;/value&gt;
-        &lt;value&gt;pflash&lt;/value&gt;
+        &lt;value&gt;pflapsh&lt;/value&gt;
       &lt;/enum&gt;
       &lt;enum name='readonly'&gt;
         &lt;value&gt;yes&lt;/value&gt;
@@ -143,38 +143,53 @@
 &lt;domainCapabilities&gt;
 </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 &lt;loader/&gt;
-      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 &lt;loader/&gt;
+      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: &lt;loader/&gt;
+      type="pflash" ...&gt;/path/to/the/firmware/binary/&lt;/loader&gt;.
+      </dd>
 
       <dt><code>readonly</code></dt>
       <dd>Options for the <code>readonly</code> attribute of the
-      &lt;loader/&gt; element.</dd>
+      &lt;loader/&gt; element in the domain XML.</dd>
 
       <dt><code>secure</code></dt>
       <dd>Options for the <code>secure</code> attribute of the
-      &lt;loader/&gt; element. Note, that <code>yes</code> is listed
-      only if there is a firmware that supports it.</dd>
+      &lt;loader/&gt; 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

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list