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

@@ -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

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

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