[libvirt] [PATCH] docs: clarify virsh setvcpus and setmem usage with active domains

[Justin Clift]

Addresses BZ # 622534:

  https://bugzilla.redhat.com/show_bug.cgi?id=622534
---
Pushed this, as the text has already been agreed on-list.
 tools/virsh.pod |   53 ++++++++++++++++++++++++++++++++++-------------------
 1 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 0e03d68..1f15fef 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -568,12 +568,19 @@ XEN_CREDIT scheduler and are now I<DEPRECATED>.
 
 =item B<setmem> I<domain-id> B<kilobytes>
 
-Change the current memory allocation in the guest domain. This should take
-effect immediately. The memory limit is specified in
-kilobytes.
+Immediately change the current memory allocation for an active guest domain.
+
+Some hypervisors require a larger granularity than kilobytes, and requests
+that are not an even multiple will either be rounded down or rejected.  For
+example, vSphere/ESX rejects the parameter unless the kB argument is evenly
+divisible by 1024 (that is, the kB argument happens to represent megabytes).
+
+For Xen, you can only adjust the memory of a running domain if the domain is
+paravirtualized or running the PV balloon driver.
 
-For Xen, you can only adjust the memory of a running domain if the
-domain is paravirtualized or running the PV balloon driver.
+Note, this command only works on active guest domains.  To change the memory
+allocation for an inactive guest domain, use the virsh B<edit> command to
+update the XML <memory> element.
 
 =item B<setmaxmem> I<domain-id> B<kilobytes>
 
@@ -593,23 +600,31 @@ QEMU/KVM supports I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>.
 =item B<setvcpus> I<domain-id> I<count> optional I<--maximum> I<--config>
 I<--live>
 
-Change the number of virtual CPUs active in the guest domain. Note that
-I<count> may be limited by host, hypervisor or limit coming from the
-original description of domain.
+Change the number of virtual CPUs active in a guest domain.  By default,
+this command works on active guest domains.  To change the settings for an
+inactive guest domain, use the I<--config> flag.
+
+The I<count> value may be limited by host, hypervisor, or a limit coming
+from the original description of the guest domain. For Xen, you can only
+adjust the virtual CPUs of a running domain if the domain is paravirtualized.
+
+If the I<--config> flag is specified, the change is made to the stored XML
+configuration for the guest domain, and will only take effect when the guest
+domain is next started.
 
-For Xen, you can only adjust the virtual CPUs of a running domain if
-the domain is paravirtualized.
+If I<--live> is specified, the guest domain must be active, and the change
+takes place immediately.  Both the I<--config> and I<--live> flags may be
+specified together if supported by the hypervisor.
 
-If I<--config> is specified, the change will only affect the next
-boot of a domain.  If I<--live> is specified, the domain must be
-running, and the change takes place immediately.  Both flags may be
-specified, if supported by the hypervisor.  If neither flag is given,
-then I<--live> is implied and it is up to the hypervisor whether
-I<--config> is also implied.
+When neither the I<--config> nor I<--live> flags are given, the I<--live>
+flag is assumed and the guest domain must be active.  In this situation it
+is up to the hypervisor whether the I<--config> flag is also assumed, and
+therefore whether the XML configuration is adjusted to make the change
+persistent.
 
-If I<--maximum> is specified, then you must use I<--config> and
-avoid I<--live>; this flag controls the maximum limit of vcpus that
-can be hot-plugged the next time the domain is booted.
+The I<--maximum> flag controls the maximum number of virtual cpus that can
+be hot-plugged the next time the domain is booted.  As such, it must only be
+used with the I<--config> flag, and not with the I<--live> flag.
 
 =item B<shutdown> I<domain-id>
 
-- 
1.7.3.5