[libvirt] [PATCH] virsh: Fix documentation for memtune command

[Daniel P. Berrange]

On Thu, Mar 31, 2011 at 11:52:48AM +0200, Jiri Denemark wrote:
> Commit 78ba748ef14c520ff1c4af2b5b0a44586ac49c8c claims to fix
> documentation for swap_hard_limit virsh memtune option but it only fixes
> documentation in formatdomain.html and libvirt.h. This patch completes
> the task by fixing "virsh help memtune" output and memtune section of
> virsh man page.
> ---
>  tools/virsh.c   |    2 +-
>  tools/virsh.pod |   29 +++++++++++++++++++++++++++--
>  2 files changed, 28 insertions(+), 3 deletions(-)
> 
> diff --git a/tools/virsh.c b/tools/virsh.c
> index faeaf47..8816812 100644
> --- a/tools/virsh.c
> +++ b/tools/virsh.c
> @@ -3201,7 +3201,7 @@ static const vshCmdOptDef opts_memtune[] = {
>      {"soft-limit", VSH_OT_INT, VSH_OFLAG_NONE,
>       N_("Memory during contention in kilobytes")},
>      {"swap-hard-limit", VSH_OT_INT, VSH_OFLAG_NONE,
> -     N_("Max swap in kilobytes")},
> +     N_("Max memory plus swap in kilobytes")},
>      {"min-guarantee", VSH_OT_INT, VSH_OFLAG_NONE,
>       N_("Min guaranteed memory in kilobytes")},
>      {NULL, 0, 0, NULL}
> diff --git a/tools/virsh.pod b/tools/virsh.pod
> index e882261..ca9e401 100644
> --- a/tools/virsh.pod
> +++ b/tools/virsh.pod
> @@ -611,12 +611,37 @@ 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>
> -B<kilobytes> -I<--min-guarantee> B<kilobytes>
> +B<kilobytes> optional I<--min-guarantee> B<kilobytes>
>  
>  Allows you to display or set the domain memory parameters. Without
>  flags, the current settings are displayed; with a flag, the
>  appropriate limit is adjusted if supported by the hypervisor.  LXC and
> -QEMU/KVM supports I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>.
> +QEMU/KVM support I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>.
> +
> +=over 4
> +
> +=item I<--hard-limit>
> +
> +The maximum memory the guest can use. The units for this value are kilobytes
> +(i.e. blocks of 1024 bytes).
> +
> +=item I<--soft-limit>
> +
> +The memory limit to enforce during memory contention. The units for this value
> +are kilobytes (i.e. blocks of 1024 bytes).
> +
> +=item I<--swap-hard-limit>
> +
> +The maximum memory plus swap the guest can use. The units for this value are
> +kilobytes (i.e. blocks of 1024 bytes). This has to be more than hard-limit
> +value provided.
> +
> +=item I<--min-guarantee>
> +
> +The guaranteed minimum memory allocation for the guest. The units for this
> +value are kilobytes (i.e. blocks of 1024 bytes).
> +
> +=back
>  
>  =item B<blkiotune> I<domain-id> optional I<--weight> B<weight>

I think it is worth explaining that the memory limits here are applying
to the QEMU process as a whole, rather than just to the guest RAM block.

ie, when deciding any of these parameters, you need to add up

 Guest RAM (w/ possible balloon) + Video RAM + misc QEMU ram allocations

The last bit there is more or less impossible to determine, so you'd
have to guess and allow say 10 MB overhead for QEMU's general heap/stack
usage

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|