remote: New APIs for ThrottleGroup lifecycle management

Defined new public APIs:
* virDomainSetThrottleGroup to add or update throttlegroup within specific domain,
  it will be referenced by throttlefilter later in disk to do limits
* virDomainGetThrottleGroup to get throttlegroup info, old-style is discarded
  (APIs to query first for the number of parameters and then give it a
  reasonably-sized pointer), instead, the new approach is adopted that
  API returns allocated array of fields and number of fileds that are in it.
* virDomainDelThrottleGroup to delete throttlegroup, it fails if this throttlegroup
  is still referenced by some throttlefilter

Signed-off-by: Chun Feng Wu <danielwuwy@163.com>

* Reimplement getter API to fetch data from XML.
* Apply suggested coding style changes.
* Update of code documentation comments.
* Update the version to 11.2.0.

Signed-off-by: Harikumar Rajkumar <harirajkumar230@gmail.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

include/libvirt/libvirt-domain.h

@@ -8281,4 +8281,18 @@ virDomainGraphicsReload(virDomainPtr domain,
                         unsigned int type,
                         unsigned int flags);
 
+
+int
+virDomainSetThrottleGroup(virDomainPtr dom,
+                          const char *group,
+                          virTypedParameterPtr params,
+                          int nparams,
+                          unsigned int flags);
+
+int
+virDomainDelThrottleGroup(virDomainPtr dom,
+                          const char *group,
+                          unsigned int flags);
+
+
 #endif /* LIBVIRT_DOMAIN_H */

src/driver-hypervisor.h

@@ -1461,6 +1461,18 @@ typedef int
                               unsigned int type,
                               unsigned int flags);
 
+typedef int
+(*virDrvDomainSetThrottleGroup)(virDomainPtr dom,
+                                const char *groupname,
+                                virTypedParameterPtr params,
+                                int nparams,
+                                unsigned int flags);
+
+typedef int
+(*virDrvDomainDelThrottleGroup)(virDomainPtr dom,
+                                const char *groupname,
+                                unsigned int flags);
+
 typedef struct _virHypervisorDriver virHypervisorDriver;
 
 /**
@@ -1736,4 +1748,6 @@ struct _virHypervisorDriver {
     virDrvDomainStartDirtyRateCalc domainStartDirtyRateCalc;
     virDrvDomainFDAssociate domainFDAssociate;
     virDrvDomainGraphicsReload domainGraphicsReload;
+    virDrvDomainSetThrottleGroup domainSetThrottleGroup;
+    virDrvDomainDelThrottleGroup domainDelThrottleGroup;
 };

src/libvirt-domain.c

@@ -14072,3 +14072,125 @@ virDomainGraphicsReload(virDomainPtr domain,
     virDispatchError(domain->conn);
     return -1;
 }
+
+
+/**
+ * virDomainSetThrottleGroup:
+ * @dom: pointer to domain object
+ * @group: throttle group name
+ * @params: Pointer to blkio parameter objects
+ * @nparams: Number of blkio parameters (this value can be the same or
+ *           less than the number of parameters supported)
+ * @flags: bitwise-OR of virDomainModificationImpact
+ *
+ * Add throttlegroup or change all of the throttlegroup options
+ * within specific domain
+ *
+ * The @group parameter is the name for new or existing throttlegroup,
+ * it cannot be NULL, detailed throttlegroup info is included in @params,
+ * it either creates new throttlegroup with @params or updates existing
+ * throttlegroup with @params, throttlegroup can be referenced by throttle
+ * filter in attached disk to do limits, the difference from iotune is that
+ * multiple throttlegroups can be referenced within attached disk
+ *
+ * Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: 11.2.0
+ */
+int
+virDomainSetThrottleGroup(virDomainPtr dom,
+                          const char *group,
+                          virTypedParameterPtr params,
+                          int nparams,
+                          unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(dom, "params=%p, group='%s', nparams=%d, flags=0x%x",
+                     params, group, nparams, flags);
+    VIR_TYPED_PARAMS_DEBUG(params, nparams);
+
+    virResetLastError();
+
+    virCheckDomainReturn(dom, -1);
+    conn = dom->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+    virCheckNonNullArgGoto(group, error);
+    virCheckPositiveArgGoto(nparams, error);
+    virCheckNonNullArgGoto(params, error);
+
+    if (virTypedParameterValidateSet(dom->conn, params, nparams) < 0)
+        goto error;
+
+    if (conn->driver->domainSetThrottleGroup) {
+        int ret;
+        ret = conn->driver->domainSetThrottleGroup(dom, group, params, nparams, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(dom->conn);
+    return -1;
+}
+
+
+/**
+ * virDomainDelThrottleGroup:
+ * @dom: pointer to domain object
+ * @group: throttle group name
+ * @flags: bitwise-OR of virDomainModificationImpact
+ *
+ * Delete an throttlegroup from the domain. @group cannot be NULL,
+ * and the @group to be deleted must not have a throttlefilter associated with
+ * it and can be any of the current valid group.
+ *
+ * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
+ * Both flags may be set.
+ * If VIR_DOMAIN_AFFECT_LIVE is set, the change affects a running domain
+ * and may fail if domain is not alive.
+ * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
+ * and will fail for transient domains. If neither flag is specified (that is,
+ * @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain modifies
+ * persistent setup, while an active domain is hypervisor-dependent on whether
+ * just live or both live and persistent state is changed.
+ *
+ * Returns -1 in case of error, 0 in case of success.
+ *
+ * Since: 11.2.0
+ */
+int
+virDomainDelThrottleGroup(virDomainPtr dom,
+                          const char *group,
+                          unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(dom, "group='%s', flags=0x%x",
+                     group, flags);
+
+    virResetLastError();
+
+    virCheckDomainReturn(dom, -1);
+    virCheckNonNullArgGoto(group, error);
+
+    conn = dom->conn;
+
+    if (conn->driver->domainDelThrottleGroup) {
+        int ret;
+        ret = conn->driver->domainDelThrottleGroup(dom, group, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(dom->conn);
+    return -1;
+}

src/libvirt_public.syms

@@ -952,6 +952,8 @@ LIBVIRT_11.2.0 {
     global:
         virDomainGetAutostartOnce;
         virDomainSetAutostartOnce;
+        virDomainSetThrottleGroup;
+        virDomainDelThrottleGroup;
 } LIBVIRT_10.2.0;
 
 # .... define new API here using predicted next version number ....

src/remote/remote_driver.c

@@ -7837,6 +7837,8 @@ static virHypervisorDriver hypervisor_driver = {
     .domainSetLaunchSecurityState = remoteDomainSetLaunchSecurityState, /* 8.0.0 */
     .domainFDAssociate = remoteDomainFDAssociate, /* 9.0.0 */
     .domainGraphicsReload = remoteDomainGraphicsReload, /* 10.2.0 */
+    .domainSetThrottleGroup = remoteDomainSetThrottleGroup, /* 11.2.0 */
+    .domainDelThrottleGroup = remoteDomainDelThrottleGroup, /* 11.2.0 */
 };
 
 static virNetworkDriver network_driver = {

src/remote/remote_protocol.x

@@ -1475,6 +1475,19 @@ struct remote_domain_get_block_io_tune_ret {
     int nparams;
 };
 
+struct remote_domain_set_throttle_group_args {
+    remote_nonnull_domain dom;
+    remote_nonnull_string group;
+    remote_typed_param params<REMOTE_DOMAIN_BLOCK_IO_TUNE_PARAMETERS_MAX>;
+    unsigned int flags;
+};
+
+struct remote_domain_del_throttle_group_args {
+    remote_nonnull_domain dom;
+    remote_string group;
+    unsigned int flags;
+};
+
 struct remote_domain_get_cpu_stats_args {
     remote_nonnull_domain dom;
     unsigned int nparams;
@@ -7076,5 +7089,21 @@ enum remote_procedure {
      * @priority: high
      * @acl: domain:write
      */
-    REMOTE_PROC_DOMAIN_SET_AUTOSTART_ONCE = 450
+    REMOTE_PROC_DOMAIN_SET_AUTOSTART_ONCE = 450,
+
+    /**
+     * @generate: both
+     * @acl: domain:write
+     * @acl: domain:save:!VIR_DOMAIN_AFFECT_CONFIG|VIR_DOMAIN_AFFECT_LIVE
+     * @acl: domain:save:VIR_DOMAIN_AFFECT_CONFIG
+     */
+    REMOTE_PROC_DOMAIN_SET_THROTTLE_GROUP = 451,
+
+    /**
+     * @generate: both
+     * @acl: domain:write
+     * @acl: domain:save:!VIR_DOMAIN_AFFECT_CONFIG|VIR_DOMAIN_AFFECT_LIVE
+     * @acl: domain:save:VIR_DOMAIN_AFFECT_CONFIG
+     */
+    REMOTE_PROC_DOMAIN_DEL_THROTTLE_GROUP = 452
 };

src/remote_protocol-structs

@@ -1050,6 +1050,20 @@ struct remote_domain_get_block_io_tune_ret {
         } params;
         int                        nparams;
 };
+struct remote_domain_set_throttle_group_args {
+	remote_nonnull_domain      dom;
+	remote_nonnull_string      group;
+	struct {
+		u_int              params_len;
+		remote_typed_param * params_val;
+	} params;
+	u_int                      flags;
+};
+struct remote_domain_del_throttle_group_args {
+        remote_nonnull_domain      dom;
+        remote_string              group;
+        u_int                      flags;
+};
 struct remote_domain_get_cpu_stats_args {
         remote_nonnull_domain      dom;
         u_int                      nparams;
@@ -3767,4 +3781,6 @@ enum remote_procedure {
         REMOTE_PROC_DOMAIN_GRAPHICS_RELOAD = 448,
         REMOTE_PROC_DOMAIN_GET_AUTOSTART_ONCE = 449,
         REMOTE_PROC_DOMAIN_SET_AUTOSTART_ONCE = 450,
+        REMOTE_PROC_DOMAIN_SET_THROTTLE_GROUP = 451,
+        REMOTE_PROC_DOMAIN_DEL_THROTTLE_GROUP = 452,
 };