From 61dfbf8c3ace9aa82929885814b8a6c4906fe150 Mon Sep 17 00:00:00 2001
From: "Nikunj A. Dadhania" <nikunj@linux.vnet.ibm.com>
Date: Tue, 19 Oct 2010 14:27:12 +0200
Subject: [PATCH] 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
---
 docs/formatdomain.html.in | 26 ++++++++++++++++++++++++++
 src/libvirt.c             | 20 +++++++++++++++++---
 tools/virsh.pod           |  8 ++++++++
 3 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index a4821e1efa..a8a1fac40c 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -194,6 +194,12 @@
   &lt;memoryBacking&gt;
     &lt;hugepages/&gt;
   &lt;/memoryBacking&gt;
+  &lt;memtune&gt;
+    &lt;hard_limit&gt;1048576&lt;/hard_limit&gt;
+    &lt;soft_limit&gt;131072&lt;/soft_limit&gt;
+    &lt;swap_hard_limit&gt;2097152&lt;/swap_hard_limit&gt;
+    &lt;min_guarantee&gt;65536&lt;/min_guarantee&gt;
+  &lt;/memtune&gt;
   &lt;vcpu cpuset="1-4,^3,6"&gt;2&lt;/vcpu&gt;
   ...</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 28684605dd..629d97b19d 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 d662b787ec..199046bc54 100644
--- 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