Update docs for memory parameters and memtune command

* docs/formatdomain.html.in: Add memtune element details, added min_guarantee
* src/libvirt.c: Update virDomainGetMemoryParameters api description, make
  it more clear that the user first needs to call the api to get the number
  of parameters supported and then call again to get the values.
* tools/virsh.pod: Add usage of new command memtune in virsh manpage

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index a4821e1efaa61d0d786bc4f7bea05b368eba6bbe..a8a1fac40cf2764b838f3db7c87e942d404edf9d 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -194,6 +194,12 @@
   <memoryBacking>
     <hugepages/>
   </memoryBacking>
+  <memtune>
+    <hard_limit>1048576</hard_limit>
+    <soft_limit>131072</soft_limit>
+    <swap_hard_limit>2097152</swap_hard_limit>
+    <min_guarantee>65536</min_guarantee>
+  </memtune>
   <vcpu cpuset="1-4,^3,6">2</vcpu>
   ...</pre>
 
@@ -211,6 +217,26 @@
         <code>hugepages</code> element set within it. This tells the
         hypervisor that the guest should have its memory allocated using
         hugepages instead of the normal native page size.</dd>
+      <dt><code>memtune</code></dt>
+      <dd> The optional <code>memtune</code> element provides details
+      regarding the memory tuneable parameters for the domain. If this is
+      omitted, it defaults to the OS provided defaults.</dd>
+      <dt><code>hard_limit</code></dt>
+      <dd> The optional <code>hard_limit</code> element is the maximum memory
+       the guest can use. The units for this value are kilobytes (i.e. blocks
+       of 1024 bytes)</dd>
+      <dt><code>soft_limit</code></dt>
+      <dd> The optional <code>soft_limit</code> element is the memory limit to
+       enforce during memory contention. The units for this value are
+       kilobytes (i.e. blocks of 1024 bytes)</dd>
+      <dt><code>swap_hard_limit</code></dt>
+      <dd> The optional <code>swap_hard_limit</code> element is the maximum
+       swap the guest can use. The units for this value are kilobytes
+       (i.e. blocks of 1024 bytes)</dd>
+      <dt><code>min_guarantee</code></dt>
+      <dd> The optional <code>min_guarantee</code> element is the guaranteed
+       minimum memory allocation for the guest. The units for this value are
+       kilobytes (i.e. blocks of 1024 bytes)</dd>
       <dt><code>vcpu</code></dt>
       <dd>The content of this element defines the number of virtual
         CPUs allocated for the guest OS, which must be between 1 and

diff --git a/src/libvirt.c b/src/libvirt.c
index 28684605ddbad1e0fbb723ed99f0ef8aa0550c3d..629d97b19d0a60d0a0816b7baab5b6da4bc4b0a7 100644 (file)
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -3063,9 +3063,23 @@ error:
  * Get the memory parameters, the @params array will be filled with the values
  * equal to the number of parameters suggested by @nparams
  *
- * As a special case, if @nparams is zero and @params is NULL, the API will
- * set the number of parameters supported by the HV in @nparams and return
- * SUCCESS.
+ * As the value of @nparams is dynamic, call the API setting @nparams to 0 and
+ * @params as NULL, the API returns the number of parameters supported by the
+ * HV by updating @nparams on SUCCESS. The caller should then allocate @params
+ * array, i.e. (sizeof(@virMemoryParameter) * @nparams) bytes and call the API
+ * again.
+ *
+ * Here is the sample code snippet:
+ *
+ * if ((virDomainGetMemoryParameters(dom, NULL, &nparams, 0) == 0) &&
+ *     (nparams != 0)) {
+ *     params = vshMalloc(ctl, sizeof(virMemoryParameter) * nparams);
+ *     memset(params, 0, sizeof(virMemoryParameter) * nparams);
+ *     if (virDomainGetMemoryParameters(dom, params, &nparams, 0)) {
+ *         vshError(ctl, "%s", _("Unable to get memory parameters"));
+ *         goto error;
+ *     }
+ * }
  *
  * This function requires privileged access to the hypervisor. This function
  * expects the caller to allocate the @param

diff --git a/tools/virsh.pod b/tools/virsh.pod
index d662b787ec469daa37c18805bb8c21c6557b699d..199046bc54a9ea981920d57d7843c7b01517b9fc 100644 (file)
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -513,6 +513,14 @@ Change the maximum memory allocation limit in the guest domain. This should
 not change the current memory use. The memory limit is specified in
 kilobytes.
 
+=item B<memtune> I<domain-id>
+
+Displays the domain memory parameters.
+
+=item B<memtune> I<domain-id> optional I<--hard-limit> B<kilobytes> optional I<--soft-limit> B<kilobytes> optional I<--swap-hard-limit> B<kilobytes>
+
+Allows you to set the domain memory parameters. LXC and QEMU/KVM supports these parameters.
+
 =item B<setvcpus> I<domain-id> I<count>
 
 Change the number of virtual CPUs active in the guest domain. Note that