API: Introduce VIR_DOMAIN_VCPU_AGENT, for agent based CPU hot(un)plug

This flag will allow to use qemu guest agent commands to disable
(offline) and enable (online) processors in a live guest that has the
guest agent running.

include/libvirt/libvirt.h.in

@@ -2120,6 +2120,7 @@ typedef enum {
 
     /* Additionally, these flags may be bitwise-OR'd in.  */
     VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count */
+    VIR_DOMAIN_VCPU_AGENT   = (1 << 3), /* Use guest-agent based cpu hotplug */
 } virDomainVcpuFlags;
 
 int                     virDomainSetVcpus       (virDomainPtr domain,

src/libvirt.c

@@ -8906,6 +8906,12 @@ error:
  * equal to virConnectGetMaxVcpus().  Otherwise, this call affects the
  * current virtual CPU limit, which must be less than or equal to the
  * maximum limit.
+ *
+ * If @flags includes VIR_DOMAIN_VCPU_AGENT, then a guest agent is used to
+ * modify the number of processors used by a domain. This flag can only be used
+ * with live guests and is incompatible with VIR_DOMAIN_VCPU_MAXIMUM as the
+ * maximum limit can't be changed using the guest agent.
+ *
  * Not all hypervisors can support all flag combinations.
  *
  * Returns 0 in case of success, -1 in case of failure.
@@ -8931,6 +8937,15 @@ virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus,
         goto error;
     }
 
+    if (flags & VIR_DOMAIN_VCPU_AGENT &&
+        flags & VIR_DOMAIN_VCPU_MAXIMUM) {
+        virReportInvalidArg(flags,
+                            _("flags 'VIR_DOMAIN_VCPU_MAXIMUM' and "
+                              "'VIR_DOMAIN_VCPU_AGENT' in '%s' are mutually "
+                              "exclusive"), __FUNCTION__);
+        goto error;
+    }
+
     virCheckNonZeroArgGoto(nvcpus, error);
 
     if ((unsigned short) nvcpus != nvcpus) {
@@ -8974,7 +8989,11 @@ error:
  *
  * If @flags includes VIR_DOMAIN_VCPU_MAXIMUM, then the maximum
  * virtual CPU limit is queried.  Otherwise, this call queries the
- * current virtual CPU limit.
+ * current virtual CPU count.
+ *
+ * If @flags includes VIR_DOMAIN_VCPU_AGENT, then a guest agent is used to
+ * modify the number of processors used by a domain. This flag is only usable on
+ * live domains.
  *
  * Returns the number of vCPUs in case of success, -1 in case of failure.
  */
@@ -8998,7 +9017,8 @@ virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags)
     if ((flags & VIR_DOMAIN_AFFECT_LIVE) &&
         (flags & VIR_DOMAIN_AFFECT_CONFIG)) {
         virReportInvalidArg(flags,
-                            _("flags 'affect live' and 'affect config' in %s are mutually exclusive"),
+                            _("flags 'affect live' and 'affect config' in %s "
+                              "are mutually exclusive"),
                             __FUNCTION__);
         goto error;
     }

tools/virsh-domain.c

@@ -5161,6 +5161,10 @@ static const vshCmdOptDef opts_vcpucount[] = {
      .type = VSH_OT_BOOL,
      .help = N_("get value according to current domain state")
     },
+    {.name = "agent",
+     .type = VSH_OT_BOOL,
+     .help = N_("use guest agent based hotplug")
+    },
     {.name = NULL}
 };
 
@@ -5203,6 +5207,11 @@ vshCPUCountCollect(vshControl *ctl,
            last_error->code == VIR_ERR_INVALID_ARG))
          goto cleanup;
 
+     if (flags & VIR_DOMAIN_VCPU_AGENT) {
+         vshError(ctl, "%s", _("Failed to retrieve vCPU count via guest agent"));
+         goto cleanup;
+     }
+
      if (!(flags & (VIR_DOMAIN_AFFECT_LIVE | VIR_DOMAIN_AFFECT_CONFIG)) &&
          virDomainIsActive(dom) == 1)
          flags |= VIR_DOMAIN_AFFECT_LIVE;
@@ -5258,7 +5267,8 @@ cmdVcpucount(vshControl *ctl, const vshCmd *cmd)
     bool config = vshCommandOptBool(cmd, "config");
     bool live = vshCommandOptBool(cmd, "live");
     bool current = vshCommandOptBool(cmd, "current");
-    bool all = maximum + active + current + config + live == 0;
+    bool agent = vshCommandOptBool(cmd, "agent");
+    bool all = maximum + active + current + config + live + agent == 0;
     unsigned int flags = VIR_DOMAIN_AFFECT_CURRENT;
 
     /* Backwards compatibility: prior to 0.9.4,
@@ -5273,6 +5283,7 @@ cmdVcpucount(vshControl *ctl, const vshCmd *cmd)
     VSH_EXCLUSIVE_OPTIONS_VAR(current, live);
     VSH_EXCLUSIVE_OPTIONS_VAR(current, config);
     VSH_EXCLUSIVE_OPTIONS_VAR(active, maximum);
+    VSH_EXCLUSIVE_OPTIONS_VAR(agent, config);
 
     if (live)
         flags |= VIR_DOMAIN_AFFECT_LIVE;
@@ -5280,6 +5291,8 @@ cmdVcpucount(vshControl *ctl, const vshCmd *cmd)
         flags |= VIR_DOMAIN_AFFECT_CONFIG;
     if (maximum)
         flags |= VIR_DOMAIN_VCPU_MAXIMUM;
+    if (agent)
+        flags |= VIR_DOMAIN_VCPU_AGENT;
 
     if (!(dom = vshCommandOptDomain(ctl, cmd, NULL)))
         return false;
@@ -5749,6 +5762,10 @@ static const vshCmdOptDef opts_emulatorpin[] = {
      .type = VSH_OT_BOOL,
      .help = N_("affect current domain")
     },
+    {.name = "agent",
+     .type = VSH_OT_BOOL,
+     .help = N_("use guest agent based hotplug")
+    },
     {.name = NULL}
 };
 
@@ -5885,17 +5902,21 @@ cmdSetvcpus(vshControl *ctl, const vshCmd *cmd)
     bool config = vshCommandOptBool(cmd, "config");
     bool live = vshCommandOptBool(cmd, "live");
     bool current = vshCommandOptBool(cmd, "current");
+    bool agent = vshCommandOptBool(cmd, "agent");
     unsigned int flags = VIR_DOMAIN_AFFECT_CURRENT;
 
     VSH_EXCLUSIVE_OPTIONS_VAR(current, live);
     VSH_EXCLUSIVE_OPTIONS_VAR(current, config);
+    VSH_EXCLUSIVE_OPTIONS_VAR(agent, config);
 
     if (config)
         flags |= VIR_DOMAIN_AFFECT_CONFIG;
     if (live)
         flags |= VIR_DOMAIN_AFFECT_LIVE;
+    if (agent)
+        flags |= VIR_DOMAIN_VCPU_AGENT;
     /* none of the options were specified */
-    if (!current && !live && !config && !maximum)
+    if (!current && flags == 0)
         flags = -1;
 
     if (!(dom = vshCommandOptDomain(ctl, cmd, NULL)))

tools/virsh.pod

@@ -1585,7 +1585,7 @@ exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
 
 =item B<setvcpus> I<domain> I<count> [I<--maximum>] [[I<--config>]
-[I<--live>] | [I<--current>]]
+[I<--live>] | [I<--current>]] [I<--agent>]
 
 Change the number of virtual CPUs active in a guest domain.  By default,
 this command works on active guest domains.  To change the settings for an
@@ -1611,6 +1611,10 @@ is up to the hypervisor whether the I<--config> flag is also assumed, and
 therefore whether the XML configuration is adjusted to make the change
 persistent.
 
+If I<--agent> is specified, then guest agent commands are used to retrieve the
+count of available vCPUs from the perspective of the guest. This flag is usable
+only for live domains.
+
 The I<--maximum> flag controls the maximum number of virtual cpus that can
 be hot-plugged the next time the domain is booted.  As such, it must only be
 used with the I<--config> flag, and not with the I<--live> flag.
@@ -1737,7 +1741,7 @@ NOTE: For an inactive domain, the domain name or UUID must be used as the
 I<domain>.
 
 =item B<vcpucount> I<domain>  [{I<--maximum> | I<--active>}
-{I<--config> | I<--live> | I<--current>}]
+{I<--config> | I<--live> | I<--current>}] [I<--agent>]
 
 Print information about the virtual cpu counts of the given
 I<domain>.  If no flags are specified, all possible counts are
@@ -1754,7 +1758,10 @@ time the domain will be booted, I<--live> requires a running domain and
 lists current values, and I<--current> queries according to the current
 state of the domain (corresponding to I<--live> if running, or
 I<--config> if inactive); these three flags are mutually exclusive.
-Thus, this command always takes exactly zero or two flags.
+
+If I<--agent> is specified, then guest agent commands are used to retrieve the
+count of available vCPUs from the perspective of the guest. This flag is usable
+only for live domains.
 
 =item B<vcpuinfo> I<domain>