docs: expand the man page text for virsh setmaxmem

Addresses BZ # 622534:

  https://bugzilla.redhat.com/show_bug.cgi?id=622534

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 4e8b2958f503f2df70cfeb7e27d8a37ae5733d33..811ff2d061e35b9df5285757b496a35f56821ce3 100644 (file)
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -584,9 +584,19 @@ update the XML <currentMemory> element.
 
 =item B<setmaxmem> I<domain-id> B<kilobytes>
 
-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.
+Change the maximum memory allocation limit for an inactive guest domain.
+
+This command works for at least the Xen and vSphere/ESX hypervisors,
+but not for QEMU/KVM.
+
+Some hypervisors require a larger granularity than kilobytes, rounding down
+or rejecting requests that are not an even multiple of the desired amount.
+vSphere/ESX is one of these, requiring the parameter to be evenly divisible
+by 4MB.  For vSphere/ESX, 263168 (257MB) would be rejected because it's not
+a multiple of 4MB, while 266240 (260MB) is valid.
+
+Note, to change the maximum memory allocation for a QEMU/KVM guest domain,
+use the virsh B<edit> command instead to update its XML <memory> element.
 
 =item B<memtune> I<domain-id> optional I<--hard-limit> B<kilobytes>
 optional I<--soft-limit> B<kilobytes> optional I<--swap-hard-limit>