[libvirt] [PATCH] Update docs for memory parameters and memtune command

[Nikunj A. Dadhania]

From: Nikunj A. Dadhania <nikunj at linux.vnet.ibm.com>

docs/formatdomain.html.in: Add memtune element details
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

Signed-off-by: Nikunj A. Dadhania <nikunj at linux.vnet.ibm.com>
---
 docs/formatdomain.html.in |   21 +++++++++++++++++++++
 src/libvirt.c             |   20 +++++++++++++++++---
 tools/virsh.pod           |    8 ++++++++
 3 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 8ec7446..9b4c6d7 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -194,6 +194,11 @@
   <memoryBacking>
     <hugepages/>
   </memoryBacking>
+  <memtune>
+    <hard_limit>1048576</hard_limit>
+    <soft_limit>131072</soft_limit>
+    <swap_hard_limit>2097152</swap_hard_limit>
+  </memtune>
   <vcpu cpuset="1-4,^3,6">2</vcpu>
   ...</pre>
 
@@ -211,6 +216,22 @@
         <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>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 2868460..629d97b 100644
--- 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 e0471b1..cb8e942 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -456,6 +456,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