[libvirt] [PATCH] API: document scheduler parameter names

Eric Blake eblake at redhat.com
Tue Nov 1 20:42:10 UTC 2011


Document the parameter names that will be used by
virDomain{Get,Set}SchedulerParameters{,Flags}, rather than
hard-coding those names in each driver, to match what is
done with memory, blkio, and blockstats parameters.

* include/libvirt/libvirt.h.in (VIR_DOMAIN_SCHEDULER_CPU_SHARES)
(VIR_DOMAIN_SCHEDULER_VCPU_PERIOD)
(VIR_DOMAIN_SCHEDULER_VCPU_QUOTA, VIR_DOMAIN_SCHEDULER_WEIGHT)
(VIR_DOMAIN_SCHEDULER_CAP): New field name macros.
* src/qemu/qemu_driver.c (qemuSetSchedulerParametersFlags)
(qemuGetSchedulerParametersFlags): Use new defines.
* src/test/test_driver.c (testDomainGetSchedulerParamsFlags)
(testDomainSetSchedulerParamsFlags): Likewise.
* src/xen/xen_hypervisor.c (xenHypervisorGetSchedulerParameters)
(xenHypervisorSetSchedulerParameters): Likewise.
* src/xen/xend_internal.c (xenDaemonGetSchedulerParameters)
(xenDaemonSetSchedulerParameters): Likewise.
* src/lxc/lxc_driver.c (lxcSetSchedulerParametersFlags)
(lxcGetSchedulerParametersFlags): Likewise.
---

As mentioned here:
https://www.redhat.com/archives/libvir-list/2011-November/msg00055.html

I will welcome any suggested improvements on how to describe what
those parameter names are configuring.  Especially for the phrase
"mysterious 'oo_req'", which looks just awful in public docs.

 include/libvirt/libvirt.h.in |   73 ++++++++++++++++++++++++++++++++---------
 src/lxc/lxc_driver.c         |    5 ++-
 src/qemu/qemu_driver.c       |   25 ++++++++------
 src/test/test_driver.c       |    4 +-
 src/xen/xen_hypervisor.c     |   19 ++++++-----
 src/xen/xend_internal.c      |   18 +++++-----
 6 files changed, 95 insertions(+), 49 deletions(-)

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index 92a14a8..0840d46 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -533,6 +533,46 @@ typedef virTypedParameter *virTypedParameterPtr;

 /* Management of scheduler parameters */

+/**
+ * VIR_DOMAIN_SCHEDULER_CPU_SHARES:
+ *
+ * Macro represents proportional weight of the scheduler used on the
+ * host cpu, when using the posix scheduler, as a ullong.
+ */
+#define VIR_DOMAIN_SCHEDULER_CPU_SHARES "cpu_shares"
+
+/**
+ * VIR_DOMAIN_SCHEDULER_VCPU_PERIOD:
+ *
+ * Macro represents the enforcement period for a quota, in microseconds,
+ * when using the posix scheduler, as a ullong.
+ */
+#define VIR_DOMAIN_SCHEDULER_VCPU_PERIOD "vcpu_period"
+
+/**
+ * VIR_DOMAIN_SCHEDULER_VCPU_QUOTA:
+ *
+ * Macro represents the maximum bandwidth to be used within a period,
+ * when using the posix scheduler, as an llong.
+ */
+#define VIR_DOMAIN_SCHEDULER_VCPU_QUOTA "vcpu_quota"
+
+/**
+ * VIR_DOMAIN_SCHEDULER_WEIGHT:
+ *
+ * Macro represents the relative weight,  when using the credit
+ * scheduler, as a uint.
+ */
+#define VIR_DOMAIN_SCHEDULER_WEIGHT "weight"
+
+/**
+ * VIR_DOMAIN_SCHEDULER_CAP:
+ *
+ * Macro represents the maximum scheduler cap, when using the credit
+ * scheduler, as a uint.
+ */
+#define VIR_DOMAIN_SCHEDULER_CAP "cap"
+
 /*
  * Fetch scheduler parameters, caller allocates 'params' field of size 'nparams'
  */
@@ -586,15 +626,16 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
 /**
  * VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH:
  *
- * Macro providing the field length of virDomainBlockStatsFlagsStruct
+ * Macro providing the field length of parameter names when using
+ * virDomainBlockStatsFlags().
  */
-#define VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH 80
+#define VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH

 /**
  * VIR_DOMAIN_BLOCK_STATS_READ_BYTES:
  *
  * Macro represents the total number of read bytes of the
- * block device.
+ * block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_READ_BYTES "rd_bytes"

@@ -602,7 +643,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_READ_REQ:
  *
  * Macro represents the total read requests of the
- * block device.
+ * block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_READ_REQ "rd_operations"

@@ -610,7 +651,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_READ_TOTAL_TIMES:
  *
  * Macro represents the total time spend on cache reads in
- * nano-seconds of the block device.
+ * nano-seconds of the block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_READ_TOTAL_TIMES "rd_total_times"

@@ -618,7 +659,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_WRITE_BYTES:
  *
  * Macro represents the total number of write bytes of the
- * block device.
+ * block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_WRITE_BYTES "wr_bytes"

@@ -626,7 +667,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_WRITE_REQ:
  *
  * Macro represents the total write requests of the
- * block device.
+ * block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_WRITE_REQ "wr_operations"

@@ -634,7 +675,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_WRITE_TOTAL_TIMES:
  *
  * Macro represents the total time spend on cache writes in
- * nano-seconds of the block device.
+ * nano-seconds of the block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_WRITE_TOTAL_TIMES "wr_total_times"

@@ -642,7 +683,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_FLUSH_REQ:
  *
  * Macro represents the total flush requests of the
- * block device.
+ * block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_FLUSH_REQ "flush_operations"

@@ -650,14 +691,14 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
  * VIR_DOMAIN_BLOCK_STATS_FLUSH_TOTAL_TIMES:
  *
  * Macro represents the total time spend on cache flushing in
- * nano-seconds of the block device.
+ * nano-seconds of the block device, as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_FLUSH_TOTAL_TIMES "flush_total_times"

 /**
  * VIR_DOMAIN_BLOCK_STATS_ERRS:
  *
- * In Xen this returns the mysterious 'oo_req'
+ * In Xen this returns the mysterious 'oo_req', as an llong.
  */
 #define VIR_DOMAIN_BLOCK_STATS_ERRS "errs"

@@ -1136,7 +1177,7 @@ char *                  virDomainGetSchedulerType(virDomainPtr domain,
  * VIR_DOMAIN_BLKIO_WEIGHT:
  *
  * Macro for the Blkio tunable weight: it represents the io weight
- * the guest can use.
+ * the guest can use, as a uint.
  */

 #define VIR_DOMAIN_BLKIO_WEIGHT "weight"
@@ -1163,7 +1204,7 @@ int     virDomainGetBlkioParameters(virDomainPtr domain,
  * VIR_DOMAIN_MEMORY_HARD_LIMIT:
  *
  * Macro for the memory tunable hard_limit: it represents the maximum memory
- * the guest can use.
+ * the guest can use, as a ullong.
  */

 #define VIR_DOMAIN_MEMORY_HARD_LIMIT "hard_limit"
@@ -1172,7 +1213,7 @@ int     virDomainGetBlkioParameters(virDomainPtr domain,
  * VIR_DOMAIN_MEMORY_SOFT_LIMIT:
  *
  * Macro for the memory tunable soft_limit: it represents the memory upper
- * limit enforced during memory contention.
+ * limit enforced during memory contention, as a ullong.
  */

 #define VIR_DOMAIN_MEMORY_SOFT_LIMIT "soft_limit"
@@ -1181,7 +1222,7 @@ int     virDomainGetBlkioParameters(virDomainPtr domain,
  * VIR_DOMAIN_MEMORY_MIN_GUARANTEE:
  *
  * Macro for the memory tunable min_guarantee: it represents the minimum
- * memory guaranteed to be reserved for the guest.
+ * memory guaranteed to be reserved for the guest, as a ullong.
  */

 #define VIR_DOMAIN_MEMORY_MIN_GUARANTEE "min_guarantee"
@@ -1190,7 +1231,7 @@ int     virDomainGetBlkioParameters(virDomainPtr domain,
  * VIR_DOMAIN_MEMORY_SWAP_HARD_LIMIT:
  *
  * Macro for the swap tunable swap_hard_limit: it represents the maximum swap
- * plus memory the guest can use. This limit has to be more than
+ * plus memory the guest can use, as a ullong. This limit has to be more than
  * VIR_DOMAIN_MEMORY_HARD_LIMIT.
  */

diff --git a/src/lxc/lxc_driver.c b/src/lxc/lxc_driver.c
index 3af7a30..9c89c41 100644
--- a/src/lxc/lxc_driver.c
+++ b/src/lxc/lxc_driver.c
@@ -2524,7 +2524,7 @@ lxcSetSchedulerParametersFlags(virDomainPtr domain,
     for (i = 0; i < nparams; i++) {
         virTypedParameterPtr param = &params[i];

-        if (STRNEQ(param->field, "cpu_shares")) {
+        if (STRNEQ(param->field, VIR_DOMAIN_SCHEDULER_CPU_SHARES)) {
             lxcError(VIR_ERR_INVALID_ARG,
                      _("Invalid parameter `%s'"), param->field);
             goto cleanup;
@@ -2603,7 +2603,8 @@ lxcGetSchedulerParametersFlags(virDomainPtr domain,
     if (virCgroupGetCpuShares(group, &val) != 0)
         goto cleanup;
     params[0].value.ul = val;
-    if (virStrcpyStatic(params[0].field, "cpu_shares") == NULL) {
+    if (virStrcpyStatic(params[0].field,
+                        VIR_DOMAIN_SCHEDULER_CPU_SHARES) == NULL) {
         lxcError(VIR_ERR_INTERNAL_ERROR,
                  "%s", _("Field cpu_shares too big for destination"));
         goto cleanup;
diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
index f81cb88..37272e0 100644
--- a/src/qemu/qemu_driver.c
+++ b/src/qemu/qemu_driver.c
@@ -6297,7 +6297,8 @@ static int qemuDomainSetMemoryParameters(virDomainPtr dom,
             }
         } else if (STREQ(param->field, VIR_DOMAIN_MEMORY_MIN_GUARANTEE)) {
             qemuReportError(VIR_ERR_INVALID_ARG,
-                            _("Memory tunable `%s' not implemented"), param->field);
+                            _("Memory tunable `%s' not implemented"),
+                            param->field);
             ret = -1;
         } else {
             qemuReportError(VIR_ERR_INVALID_ARG,
@@ -6696,7 +6697,7 @@ static int qemuSetSchedulerParametersFlags(virDomainPtr dom,
     for (i = 0; i < nparams; i++) {
         virTypedParameterPtr param = &params[i];

-        if (STREQ(param->field, "cpu_shares")) {
+        if (STREQ(param->field, VIR_DOMAIN_SCHEDULER_CPU_SHARES)) {
             if (param->type != VIR_TYPED_PARAM_ULLONG) {
                 qemuReportError(VIR_ERR_INVALID_ARG, "%s",
                                 _("invalid type for cpu_shares tunable, expected a 'ullong'"));
@@ -6717,7 +6718,7 @@ static int qemuSetSchedulerParametersFlags(virDomainPtr dom,
             if (flags & VIR_DOMAIN_AFFECT_CONFIG) {
                 vmdef->cputune.shares = params[i].value.ul;
             }
-        } else if (STREQ(param->field, "vcpu_period")) {
+        } else if (STREQ(param->field, VIR_DOMAIN_SCHEDULER_VCPU_PERIOD)) {
             if (param->type != VIR_TYPED_PARAM_ULLONG) {
                 qemuReportError(VIR_ERR_INVALID_ARG, "%s",
                                 _("invalid type for vcpu_period tunable,"
@@ -6737,7 +6738,7 @@ static int qemuSetSchedulerParametersFlags(virDomainPtr dom,
             if (flags & VIR_DOMAIN_AFFECT_CONFIG) {
                 vmdef->cputune.period = params[i].value.ul;
             }
-        } else if (STREQ(param->field, "vcpu_quota")) {
+        } else if (STREQ(param->field, VIR_DOMAIN_SCHEDULER_VCPU_QUOTA)) {
             if (param->type != VIR_TYPED_PARAM_LLONG) {
                 qemuReportError(VIR_ERR_INVALID_ARG, "%s",
                                 _("invalid type for vcpu_quota tunable,"
@@ -6981,11 +6982,11 @@ qemuGetSchedulerParametersFlags(virDomainPtr dom,
 out:
     params[0].value.ul = shares;
     params[0].type = VIR_TYPED_PARAM_ULLONG;
-    /* XXX make these field names public in libvirt.h */
-    if (virStrcpyStatic(params[0].field, "cpu_shares") == NULL) {
+    if (virStrcpyStatic(params[0].field,
+                        VIR_DOMAIN_SCHEDULER_CPU_SHARES) == NULL) {
         qemuReportError(VIR_ERR_INTERNAL_ERROR,
                         _("Field name '%s' too long"),
-                        "cpu_shares");
+                        VIR_DOMAIN_SCHEDULER_CPU_SHARES);
         goto cleanup;
     }

@@ -6995,10 +6996,11 @@ out:
         if (*nparams > saved_nparams) {
             params[1].value.ul = period;
             params[1].type = VIR_TYPED_PARAM_ULLONG;
-            if (virStrcpyStatic(params[1].field, "vcpu_period") == NULL) {
+            if (virStrcpyStatic(params[1].field,
+                                VIR_DOMAIN_SCHEDULER_VCPU_PERIOD) == NULL) {
                 qemuReportError(VIR_ERR_INTERNAL_ERROR,
                                 _("Field name '%s' too long"),
-                                "vcpu_period");
+                                VIR_DOMAIN_SCHEDULER_VCPU_PERIOD);
                 goto cleanup;
             }
             saved_nparams++;
@@ -7007,10 +7009,11 @@ out:
         if (*nparams > saved_nparams) {
             params[2].value.ul = quota;
             params[2].type = VIR_TYPED_PARAM_LLONG;
-            if (virStrcpyStatic(params[2].field, "vcpu_quota") == NULL) {
+            if (virStrcpyStatic(params[2].field,
+                                VIR_DOMAIN_SCHEDULER_VCPU_QUOTA) == NULL) {
                 qemuReportError(VIR_ERR_INTERNAL_ERROR,
                                 _("Field name '%s' too long"),
-                                "vcpu_quota");
+                                VIR_DOMAIN_SCHEDULER_VCPU_QUOTA);
                 goto cleanup;
             }
             saved_nparams++;
diff --git a/src/test/test_driver.c b/src/test/test_driver.c
index 326409d..4e1973a 100644
--- a/src/test/test_driver.c
+++ b/src/test/test_driver.c
@@ -2713,7 +2713,7 @@ testDomainGetSchedulerParamsFlags(virDomainPtr domain,
         testError(VIR_ERR_INVALID_ARG, "%s", _("Invalid parameter count"));
         goto cleanup;
     }
-    strcpy(params[0].field, "weight");
+    strcpy(params[0].field, VIR_DOMAIN_SCHEDULER_WEIGHT);
     params[0].type = VIR_TYPED_PARAM_UINT;
     /* XXX */
     /*params[0].value.ui = privdom->weight;*/
@@ -2759,7 +2759,7 @@ testDomainSetSchedulerParamsFlags(virDomainPtr domain,
     }

     for (i = 0; i < nparams; i++) {
-        if (STRNEQ(params[i].field, "weight")) {
+        if (STRNEQ(params[i].field, VIR_DOMAIN_SCHEDULER_WEIGHT)) {
             testError(VIR_ERR_INVALID_ARG, "field");
             goto cleanup;
         }
diff --git a/src/xen/xen_hypervisor.c b/src/xen/xen_hypervisor.c
index 58ae6a3..f1a8e68 100644
--- a/src/xen/xen_hypervisor.c
+++ b/src/xen/xen_hypervisor.c
@@ -1203,9 +1203,6 @@ xenHypervisorGetSchedulerType(virDomainPtr domain, int *nparams)
     return schedulertype;
 }

-static const char *str_weight = "weight";
-static const char *str_cap = "cap";
-
 /**
  * xenHypervisorGetSchedulerParameters:
  * @domain: pointer to the Xen Hypervisor block
@@ -1291,17 +1288,21 @@ xenHypervisorGetSchedulerParameters(virDomainPtr domain,
                 if (ret < 0)
                     return(-1);

-                if (virStrcpyStatic(params[0].field, str_weight) == NULL) {
+                if (virStrcpyStatic(params[0].field,
+                                    VIR_DOMAIN_SCHEDULER_WEIGHT) == NULL) {
                     virXenError(VIR_ERR_INTERNAL_ERROR,
-                                "Weight %s too big for destination", str_weight);
+                                "Weight %s too big for destination",
+                                VIR_DOMAIN_SCHEDULER_WEIGHT);
                     return -1;
                 }
                 params[0].type = VIR_TYPED_PARAM_UINT;
                 params[0].value.ui = op_dom.u.getschedinfo.u.credit.weight;

-                if (virStrcpyStatic(params[1].field, str_cap) == NULL) {
+                if (virStrcpyStatic(params[1].field,
+                                    VIR_DOMAIN_SCHEDULER_CAP) == NULL) {
                     virXenError(VIR_ERR_INTERNAL_ERROR,
-                                "Cap %s too big for destination", str_cap);
+                                "Cap %s too big for destination",
+                                VIR_DOMAIN_SCHEDULER_CAP);
                     return -1;
                 }
                 params[1].type = VIR_TYPED_PARAM_UINT;
@@ -1402,7 +1403,7 @@ xenHypervisorSetSchedulerParameters(virDomainPtr domain,

             for (i = 0; i < nparams; i++) {
                 memset(&buf, 0, sizeof(buf));
-                if (STREQ (params[i].field, str_weight) &&
+                if (STREQ (params[i].field, VIR_DOMAIN_SCHEDULER_WEIGHT) &&
                     params[i].type == VIR_TYPED_PARAM_UINT) {
                     val = params[i].value.ui;
                     if ((val < 1) || (val > USHRT_MAX)) {
@@ -1411,7 +1412,7 @@ xenHypervisorSetSchedulerParameters(virDomainPtr domain,
                         return(-1);
                     }
                     op_dom.u.getschedinfo.u.credit.weight = val;
-                } else if (STREQ (params[i].field, str_cap) &&
+                } else if (STREQ (params[i].field, VIR_DOMAIN_SCHEDULER_CAP) &&
                     params[i].type == VIR_TYPED_PARAM_UINT) {
                     val = params[i].value.ui;
                     if (val >= USHRT_MAX) {
diff --git a/src/xen/xend_internal.c b/src/xen/xend_internal.c
index fa39e8b..4fcc628 100644
--- a/src/xen/xend_internal.c
+++ b/src/xen/xend_internal.c
@@ -3554,9 +3554,6 @@ error:

 }

-static const char *str_weight = "weight";
-static const char *str_cap = "cap";
-
 /**
  * xenDaemonGetSchedulerParameters:
  * @domain: pointer to the Domain block
@@ -3635,18 +3632,21 @@ xenDaemonGetSchedulerParameters(virDomainPtr domain,
                 goto error;
             }

-            if (virStrcpyStatic(params[0].field, str_weight) == NULL) {
+            if (virStrcpyStatic(params[0].field,
+                                VIR_DOMAIN_SCHEDULER_WEIGHT) == NULL) {
                 virXendError(VIR_ERR_INTERNAL_ERROR,
                              _("Weight %s too big for destination"),
-                             str_weight);
+                             VIR_DOMAIN_SCHEDULER_WEIGHT);
                 goto error;
             }
             params[0].type = VIR_TYPED_PARAM_UINT;
             params[0].value.ui = sexpr_int(root, "domain/cpu_weight");

-            if (virStrcpyStatic(params[1].field, str_cap) == NULL) {
+            if (virStrcpyStatic(params[1].field,
+                                VIR_DOMAIN_SCHEDULER_CAP) == NULL) {
                 virXendError(VIR_ERR_INTERNAL_ERROR,
-                             _("Cap %s too big for destination"), str_cap);
+                             _("Cap %s too big for destination"),
+                             VIR_DOMAIN_SCHEDULER_CAP);
                 goto error;
             }
             params[1].type = VIR_TYPED_PARAM_UINT;
@@ -3727,10 +3727,10 @@ xenDaemonSetSchedulerParameters(virDomainPtr domain,
             memset(&buf_weight, 0, VIR_UUID_BUFLEN);
             memset(&buf_cap, 0, VIR_UUID_BUFLEN);
             for (i = 0; i < nparams; i++) {
-                if (STREQ (params[i].field, str_weight) &&
+                if (STREQ (params[i].field, VIR_DOMAIN_SCHEDULER_WEIGHT) &&
                     params[i].type == VIR_TYPED_PARAM_UINT) {
                     snprintf(buf_weight, sizeof(buf_weight), "%u", params[i].value.ui);
-                } else if (STREQ (params[i].field, str_cap) &&
+                } else if (STREQ (params[i].field, VIR_DOMAIN_SCHEDULER_CAP) &&
                     params[i].type == VIR_TYPED_PARAM_UINT) {
                     snprintf(buf_cap, sizeof(buf_cap), "%u", params[i].value.ui);
                 } else {
-- 
1.7.4.4




More information about the libvir-list mailing list