[libvirt] [PATCH v4 3/5] blockjob: expose active commit capability

[Eric Blake]

Add an element to QEMU's capability XML, to show if the underlying
qemu binary supports active commit.  This allows the client to know
ahead of time if they can rely on this method, or must fall back
to older techniques such as blockpull.  Without this information,
the only way to check for active commit is to attempt one and check
for errors.

This attribute can be a simple binary (active commit is supported
only if <activecommit/> is in the capabilities) rather than a
full-blown toggle definition.  (In contrast, the <disksnapshot>
capability had to be a toggle because we forgot to add it at the
same time as turning on the feature of external snapshots; and
therefore, the absence of the attribute is not sufficient to
conclude whether disk snapshots are supported.)

Our documentation for features was rather sparse; this fleshes out
more of the details for other existing capabilities (and cost me
some time trawling git history).

* docs/schemas/capability.rng (features): Add activecommit.
* docs/formatcaps.html.in: Document it, and other features.
* src/qemu/qemu_capabilities.c (virQEMUCapsInitGuestFromBinary):
Set it.
* src/conf/capabilities.c (virCapabilitiesFormatXML): Expose as
simpler binary.

Signed-off-by: Eric Blake <eblake at redhat.com>
---
 docs/formatcaps.html.in      | 46 +++++++++++++++++++++++++++++++++++++++++++-
 docs/schemas/capability.rng  |  5 +++++
 src/conf/capabilities.c      |  3 ++-
 src/qemu/qemu_capabilities.c |  6 ++++++
 4 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in
index 137af25..6ac0f4a 100644
--- a/docs/formatcaps.html.in
+++ b/docs/formatcaps.html.in
@@ -95,7 +95,51 @@

         <dt><code>features</code></dt>
         <dd>This optional element encases possible features that can be used
-        with a guest of described type.</dd>
+          with a guest of described type.  Possible subelements are:
+          <dl>
+            <dt>pae</dt><dd>If present, 32-bit guests can use PAE
+              address space extensions, <span class="since">since
+              0.4.1</span></dd>
+            <dt>nonpae</dt><dd>If present, 32-bit guests can be run
+              without requiring PAE, <span class="since">since
+              0.4.1</span></dd>
+            <dt>ia64_be</dt><dd>If present, IA64 guests can be run in
+              big-endian mode, <span class="since">since 0.4.1</span></dd>
+            <dt>acpi</dt><dd>If this element is present,
+              the <code>default</code> attribute describes whether the
+              hypervisor exposes ACPI to the guest by default, and
+              the <code>toggle</code> attribute describes whether the
+              user can override this
+              default. <span class="since">Since 0.4.1</span></dd>
+            <dt>apic</dt><dd>If this element is present,
+              the <code>default</code> attribute describes whether the
+              hypervisor exposes APIC to the guest by default, and
+              the <code>toggle</code> attribute describes whether the
+              user can override this
+              default. <span class="since">Since 0.4.1</span></dd>
+            <dt>cpuselection</dt><dd>If this element is present, the
+              hypervisor supports the <code><cpu></code> element
+              within a domain definition for fine-grained control over
+              the CPU presented to the
+              guest. <span class="since">Since 0.7.5</span></dd>
+            <dt>deviceboot</dt><dd>If this element is present,
+              the <code><boot order='...'/></code> element can
+              be used inside devices, rather than the older boot
+              specification by category. <span class="since">Since
+              0.8.8</span></dd>
+            <dt>disksnapshot</dt><dd>If this element is present,
+              the <code>default</code> attribute describes whether
+              external disk snapshots are supported.  If absent,
+              external snapshots may still be supported, but it
+              requires attempting the API and checking for an error to
+              find out for sure. <span class="since">Since
+              1.2.3</span></dd>
+            <dt>activecommit</dt><dd>Active commit (via the
+              virDomainBlockCommit API) is supported only if this
+              element is present. <span class="since">Since
+              1.2.6</span></dd>
+          </dl>
+        </dd>
     </dl>

     <h3><a name="elementExamples">Examples</a></h3>
diff --git a/docs/schemas/capability.rng b/docs/schemas/capability.rng
index f954599..de32ee9 100644
--- a/docs/schemas/capability.rng
+++ b/docs/schemas/capability.rng
@@ -399,6 +399,11 @@
             <empty/>
           </element>
         </optional>
+        <optional>
+          <element name='activecommit'>
+            <empty/>
+          </element>
+        </optional>
       </interleave>
     </element>
   </define>
diff --git a/src/conf/capabilities.c b/src/conf/capabilities.c
index 19359a5..ebf6121 100644
--- a/src/conf/capabilities.c
+++ b/src/conf/capabilities.c
@@ -1005,7 +1005,8 @@ virCapabilitiesFormatXML(virCapsPtr caps)
                     STREQ(caps->guests[i]->features[j]->name, "nonpae") ||
                     STREQ(caps->guests[i]->features[j]->name, "ia64_be") ||
                     STREQ(caps->guests[i]->features[j]->name, "cpuselection") ||
-                    STREQ(caps->guests[i]->features[j]->name, "deviceboot")) {
+                    STREQ(caps->guests[i]->features[j]->name, "deviceboot") ||
+                    STREQ(caps->guests[i]->features[j]->name, "activecommit")) {
                     virBufferAsprintf(&buf, "<%s/>\n",
                                       caps->guests[i]->features[j]->name);
                 } else {
diff --git a/src/qemu/qemu_capabilities.c b/src/qemu/qemu_capabilities.c
index d698db9..d1d33d5 100644
--- a/src/qemu/qemu_capabilities.c
+++ b/src/qemu/qemu_capabilities.c
@@ -822,6 +822,12 @@ virQEMUCapsInitGuestFromBinary(virCapsPtr caps,
     if (!virCapabilitiesAddGuestFeature(guest, "disksnapshot", hasdisksnapshot, 0))
         goto cleanup;

+    if (!virCapabilitiesAddGuestFeature(guest, "activecommit",
+                                        virQEMUCapsGet(qemubinCaps,
+                                                       QEMU_CAPS_ACTIVE_COMMIT),
+                                        0))
+        goto cleanup;
+
     if (virCapabilitiesAddGuestDomain(guest,
                                       "qemu",
                                       NULL,
-- 
1.9.3