[libvirt] [RFC PATCH 0/8 v3] Summary on block IO throttle

[Eric Blake]

On 11/10/2011 03:04 PM, Eric Blake wrote:
>
> We still need a v4 respinning this to use virTypedParameter; I can help
> by posting a patch 1/8 that shows the changes that I think we need in
> the public interface, but I don't want to spend the time rebasing the
> entire series.

This is more along the lines of what I'm looking for in patch 1/8 (as a 
diff against your v3 attempt at 1/8).  Obviously, it doesn't compile as 
is, so much as focus on the public interface aspect:

diff --git i/include/libvirt/libvirt.h.in w/include/libvirt/libvirt.h.in
index 4b05869..52ae0ab 100644
--- i/include/libvirt/libvirt.h.in
+++ w/include/libvirt/libvirt.h.in
@@ -1684,26 +1684,27 @@ int           virDomainBlockPull(virDomainPtr 
dom, const char *path,
   * Block I/O throttling support
   */

-typedef struct _virDomainBlockIoTuneInfo virDomainBlockIoTuneInfo;
-struct _virDomainBlockIoTuneInfo {
-    unsigned long long total_bytes_sec;
-    unsigned long long read_bytes_sec;
-    unsigned long long write_bytes_sec;
-    unsigned long long total_iops_sec;
-    unsigned long long read_iops_sec;
-    unsigned long long write_iops_sec;
-};
-typedef virDomainBlockIoTuneInfo *virDomainBlockIoTuneInfoPtr;
+/**
+ * VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_BYTES_SEC:
+ *
+ * Macro for the BlockIoTune tunable weight: it represents the total
+ * bytes per second permitted through a block device, as a ullong.
+ */
+#define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_BYTES_SEC "total_bytes_sec"
+
+/* ... and so forth - 6 macros total */

  int
  virDomainSetBlockIoTune(virDomainPtr dom,
                          const char *disk,
-                        virDomainBlockIoTuneInfoPtr info,
+                        virTypedParameterPtr params,
+                        int nparams,
                          unsigned int flags);
  int
  virDomainGetBlockIoTune(virDomainPtr dom,
                          const char *disk,
-                        virDomainBlockIoTuneInfoPtr reply,
+                        virTypedParameterPtr params,
+                        int *nparams,
                          unsigned int flags);


diff --git i/src/libvirt.c w/src/libvirt.c
index cd5931f..287dfc5 100644
--- i/src/libvirt.c
+++ w/src/libvirt.c
@@ -17184,17 +17184,23 @@ error:
   * virDomainSetBlockIoTune:
   * @dom: pointer to domain object
   * @disk: Fully-qualified disk name
- * @info: Specify block I/O limits in bytes
+ * @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: An OR'ed set of virDomainModificationImpact
   *
- * This function is mainly to enable Block I/O throttling function in 
libvirt.
- * It is used to change the block I/O throttling setting for specified 
domain.
+ * Change all or a subset of the per-device block IO tunables.
   *
- * Returns 0 if the operation has started, -1 on failure.
+ * The @disk parameter is the name of the block device.  Get this
+ * by calling virDomainGetXMLDesc and finding the <target dev='...'>
+ * attribute within //domain/devices/disk.  (For example, "xvda").
+ *
+ * Returns -1 in case of error, 0 in case of success.
   */
  int virDomainSetBlockIoTune(virDomainPtr dom,
                              const char *disk,
-                            virDomainBlockIoTuneInfoPtr info,
+                            virTypedParameterPtr params,
+                            int nparams,
                              unsigned int flags)
  {
      virConnectPtr conn;
@@ -17245,18 +17251,35 @@ error:
   * virDomainGetBlockIoTune:
   * @dom: pointer to domain object
   * @disk: Fully-qualified disk name
- * @reply: Specify block I/O info in bytes
+ * @params: pointer to blkio parameter object
+ *          (return value, allocated by the caller)
+ * @nparams: pointer to number of blkio parameters; input and output
   * @flags: An OR'ed set of virDomainModificationImpact
   *
- * This function is mainly to enable Block I/O throttling function in 
libvirt.
- * It is used to get the block I/O throttling setting for specified domain.
+ * Get all block IO tunable parameters for a given device.  On input,
+ * @nparams gives the size of the @params array; on output, @nparams
+ * gives how many slots were filled with parameter information, which
+ * might be less but will not exceed the input value.
   *
- * Returns 0 if the operation has started, -1 on failure.
+ * As a special case, calling with @params as NULL and @nparams as 0 on
+ * input will cause @nparams on output to contain the number of parameters
+ * supported by the hypervisor. The caller should then allocate @params
+ * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call 
the API
+ * again.
+ *
+ * See virDomainGetMemoryParameters() for an equivalent usage example.
+ *
+ * The @disk parameter is the name of the block device.  Get this
+ * by calling virDomainGetXMLDesc and finding the <target dev='...'>
+ * attribute within //domain/devices/disk.  (For example, "xvda").
+ *
+ * Returns -1 in case of error, 0 in case of success.
   */

  int virDomainGetBlockIoTune(virDomainPtr dom,
                              const char *disk,
-                            virDomainBlockIoTuneInfoPtr reply,
+                            virTypedParameterPtr params,
+                            int *nparams,
                              unsigned int flags)
  {
      virConnectPtr conn;


-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org