API/qemu: add async unplug flag to virDomainSetVcpu

Add VIR_DOMAIN_SETVCPU_ASYNC_UNPLUG for virDomainSetVcpu().

Define a dedicated virDomainSetVcpuBehaviour flag type and wire the
new flag through the QEMU driver. As with setvcpus async unplug,
success indicates request acceptance while final completion is
reported by the vcpu-removed event.

Update the API documentation and add virsh support for the async path to
the setvcpu subcommand.

Signed-off-by: Akash Kulhalli <akash.kulhalli@oracle.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>

docs/manpages/virsh.rst

@@ -4867,7 +4867,7 @@ setvcpu
 
 ::
 
-   setvcpu domain vcpulist [--enable] | [--disable]
+   setvcpu domain vcpulist [--enable] | [--disable] [--async]
       [[--live] [--config] | [--current]]
 
 Change state of individual vCPUs using hot(un)plug mechanism.
@@ -4887,6 +4887,11 @@ If *--current* is specified, it is equivalent to either *--live* or
 default. Both *--live* and *--config* flags may be given, but
 *--current* is exclusive.
 
+If *--async* is specified with *--disable*, live vCPU unplug requests are fired
+without waiting for the guest to comply. Final completion of this operation is
+reported by the ``vcpu-removed`` domain event, while rejected unplug requests
+continue to be reported by ``device-removal-failed``.
+
 
 shutdown
 --------

include/libvirt/libvirt-domain.h

@@ -329,6 +329,24 @@ typedef enum {
     /* 1 << 2 is reserved for virTypedParameterFlags */
 } virDomainModificationImpact;
 
+/**
+ * virDomainSetVcpuFlags:
+ *
+ * These flags must be used when calling the `virDomainSetVcpu` API.
+ *
+ * Since: 12.4.0
+ */
+typedef enum {
+    /* Alias of VIR_DOMAIN_AFFECT_CURRENT. (Since: 12.4.0)  */
+    VIR_DOMAIN_SETVCPU_AFFECT_CURRENT = VIR_DOMAIN_AFFECT_CURRENT,
+    /* Alias of VIR_DOMAIN_AFFECT_LIVE. (Since: 12.4.0)  */
+    VIR_DOMAIN_SETVCPU_AFFECT_LIVE = VIR_DOMAIN_AFFECT_LIVE,
+    /* Alias of VIR_DOMAIN_AFFECT_CONFIG. (Since: 12.4.0)  */
+    VIR_DOMAIN_SETVCPU_AFFECT_CONFIG = VIR_DOMAIN_AFFECT_CONFIG,
+    /* Do not wait for the guest to comply with the request (Since: 12.4.0) */
+    VIR_DOMAIN_SETVCPU_ASYNC_UNPLUG = 1 << 2
+} virDomainSetVcpuFlags;
+
 /**
  * virDomainInfo:
  *

src/libvirt-domain.c

@@ -13135,7 +13135,7 @@ virDomainSetGuestVcpus(virDomainPtr domain,
  * @domain: pointer to domain object
  * @vcpumap: text representation of a bitmap of vcpus to set
  * @state: 0 to disable/1 to enable cpus described by @vcpumap
- * @flags: bitwise-OR of virDomainModificationImpact
+ * @flags: bitwise-OR of virDomainSetVcpuFlags
  *
  * Enables/disables individual vcpus described by @vcpumap in the hypervisor.
  *
@@ -13144,6 +13144,16 @@ virDomainSetGuestVcpus(virDomainPtr domain,
  *
  * Note that OSes and hypervisors may require vCPU 0 to stay online.
  *
+ * If @flags includes VIR_DOMAIN_SETVCPU_ASYNC_UNPLUG, live vCPU disable
+ * (i.e. hot-unplug) request(s) are fired without waiting for the guest to
+ * comply. Success in this mode means only that the unplug request(s) were
+ * accepted. Final completion is reported by VIR_DOMAIN_EVENT_ID_VCPU_REMOVED,
+ * carrying the XML ``<vcpu id='...'>`` value for each removed vCPU. Rejected
+ * unplug requests continue to be reported by the event ID
+ * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED.
+ * The success event may be delivered before this API call returns. This flag
+ * has no effect when the selected vCPUs are enabled.
+ *
  * Returns 0 on success, -1 on error.
  *
  * Since: 3.1.0

src/qemu/qemu_driver.c

@@ -19178,12 +19178,14 @@ qemuDomainSetVcpu(virDomainPtr dom,
     virDomainObj *vm = NULL;
     virDomainDef *def = NULL;
     virDomainDef *persistentDef = NULL;
+    bool async_unplug = !!(flags & VIR_DOMAIN_SETVCPU_ASYNC_UNPLUG);
     g_autoptr(virBitmap) map = NULL;
     ssize_t lastvcpu;
     int ret = -1;
 
     virCheckFlags(VIR_DOMAIN_AFFECT_LIVE |
-                  VIR_DOMAIN_AFFECT_CONFIG, -1);
+                  VIR_DOMAIN_AFFECT_CONFIG |
+                  VIR_DOMAIN_SETVCPU_ASYNC_UNPLUG, -1);
 
     if (state != 0 && state != 1) {
         virReportInvalidArg(state, "%s", _("unsupported state value"));
@@ -19230,7 +19232,7 @@ qemuDomainSetVcpu(virDomainPtr dom,
     }
 
     ret = qemuDomainSetVcpuInternal(driver, vm, def, persistentDef, map,
-                                    !!state, false);
+                                    !!state, async_unplug);
 
  endjob:
     virDomainObjEndJob(vm);

tools/virsh-domain.c

@@ -7837,6 +7837,10 @@ static const vshCmdOptDef opts_setvcpu[] = {
      .type = VSH_OT_BOOL,
      .help = N_("disable cpus specified by cpumap")
     },
+    {.name = "async",
+     .type = VSH_OT_BOOL,
+     .help = N_("return after firing vcpu unplug request")
+    },
     VIRSH_COMMON_OPT_DOMAIN_CONFIG,
     VIRSH_COMMON_OPT_DOMAIN_LIVE,
     VIRSH_COMMON_OPT_DOMAIN_CURRENT,
@@ -7851,6 +7855,7 @@ cmdSetvcpu(vshControl *ctl, const vshCmd *cmd)
     bool disable = vshCommandOptBool(cmd, "disable");
     bool config = vshCommandOptBool(cmd, "config");
     bool live = vshCommandOptBool(cmd, "live");
+    bool async = vshCommandOptBool(cmd, "async");
     const char *vcpulist = NULL;
     int state = 0;
     unsigned int flags = VIR_DOMAIN_AFFECT_CURRENT;
@@ -7859,11 +7864,14 @@ cmdSetvcpu(vshControl *ctl, const vshCmd *cmd)
 
     VSH_EXCLUSIVE_OPTIONS("current", "live");
     VSH_EXCLUSIVE_OPTIONS("current", "config");
+    VSH_EXCLUSIVE_OPTIONS("async", "enable");
 
     if (config)
         flags |= VIR_DOMAIN_AFFECT_CONFIG;
     if (live)
         flags |= VIR_DOMAIN_AFFECT_LIVE;
+    if (async)
+        flags |= VIR_DOMAIN_SETVCPU_ASYNC_UNPLUG;
 
     if (!(enable || disable)) {
         vshError(ctl, "%s", _("one of --enable, --disable is required"));