[libvirt] [PATCH] Update docs for memory parameters and memtune command
From: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com> docs/formatdomain.html.in: Add memtune element details 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 Signed-off-by: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com> --- docs/formatdomain.html.in | 21 +++++++++++++++++++++ src/libvirt.c | 20 +++++++++++++++++--- tools/virsh.pod | 8 ++++++++ 3 files changed, 46 insertions(+), 3 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 8ec7446..9b4c6d7 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -194,6 +194,11 @@ <memoryBacking> <hugepages/> </memoryBacking> + <memtune> + <hard_limit>1048576</hard_limit> + <soft_limit>131072</soft_limit> + <swap_hard_limit>2097152</swap_hard_limit> + </memtune> <vcpu cpuset="1-4,^3,6">2</vcpu> ...</pre> @@ -211,6 +216,22 @@ <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>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 2868460..629d97b 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 e0471b1..cb8e942 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -456,6 +456,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
2010/10/18 Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>:
From: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>
docs/formatdomain.html.in: Add memtune element details 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
Signed-off-by: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com> --- docs/formatdomain.html.in | 21 +++++++++++++++++++++ src/libvirt.c | 20 +++++++++++++++++--- tools/virsh.pod | 8 ++++++++ 3 files changed, 46 insertions(+), 3 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 8ec7446..9b4c6d7 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -194,6 +194,11 @@ <memoryBacking> <hugepages/> </memoryBacking> + <memtune> + <hard_limit>1048576</hard_limit> + <soft_limit>131072</soft_limit> + <swap_hard_limit>2097152</swap_hard_limit> + </memtune> <vcpu cpuset="1-4,^3,6">2</vcpu> ...</pre>
@@ -211,6 +216,22 @@ <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>
Well, the maximum of memory a guest can use is also controlled by the memory and currentMemory element in some way. How does hard_limit relate to those two?
+ <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>
Is this an upper or a lower limit? Does it mean in case of contention this guest may only use up to soft_limit kilobytes of memory (upper limit)? Or does it mean in case of contention make sure that this guest can access at least soft_limit kilobytes of memory (lower limit)? How does this relate to the memory and currentMemory element? How does it related to the min_guarantee element?
+ <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>
What about the min_guarantee element anyway? It's not implemented in virsh. Matthias
On Mon, 18 Oct 2010 09:55:46 +0200, Matthias Bolte <matthias.bolte@googlemail.com> wrote:
2010/10/18 Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>:
From: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>
docs/formatdomain.html.in: Add memtune element details [...] @@ -211,6 +216,22 @@ <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>
Well, the maximum of memory a guest can use is also controlled by the memory and currentMemory element in some way. How does hard_limit relate to those two?
memory and currentMemory are related to balloon size, while these are operating system provided limits.
+ <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>
Is this an upper or a lower limit? Does it mean in case of contention this guest may only use up to soft_limit kilobytes of memory (upper limit)? Or does it mean in case of contention make sure that this guest can access at least soft_limit kilobytes of memory (lower limit)?
Upper limit of memory the guest can use(i.e upto soft_limit) during contention. Balbir, correct me if this isn't correct.
How does this relate to the memory and currentMemory element?
At present no relation, they are implemented by the OS.
How does it related to the min_guarantee element?
It is not related to min_guarantee.
+ <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>
What about the min_guarantee element anyway? It's not implemented in virsh.
Missed it, I will add the docs about min_gaurantee and send the updated patch. It is not implemented in virsh. However, I have taken care of parsing them in domain configuration. Nikunj
* Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com> [2010-10-18 14:03:53]:
On Mon, 18 Oct 2010 09:55:46 +0200, Matthias Bolte <matthias.bolte@googlemail.com> wrote:
2010/10/18 Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>:
From: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>
docs/formatdomain.html.in: Add memtune element details [...] @@ -211,6 +216,22 @@ <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>
Well, the maximum of memory a guest can use is also controlled by the memory and currentMemory element in some way. How does hard_limit relate to those two?
memory and currentMemory are related to balloon size, while these are operating system provided limits.
+ <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>
Is this an upper or a lower limit? Does it mean in case of contention this guest may only use up to soft_limit kilobytes of memory (upper limit)? Or does it mean in case of contention make sure that this guest can access at least soft_limit kilobytes of memory (lower limit)?
Upper limit of memory the guest can use(i.e upto soft_limit) during contention. Balbir, correct me if this isn't correct.
Yes, that interpretation is correct. We try to push back the guest to soft limit on contention, this is typically the case when the guest uses more than the assigned soft limit.
How does this relate to the memory and currentMemory element?
At present no relation, they are implemented by the OS.
This feature allows us to set useful limits, on lack of contention no limits are enforced (IOW, this is work conserving so to speak).
How does it related to the min_guarantee element?
It is not related to min_guarantee.
+ <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>
What about the min_guarantee element anyway? It's not implemented in virsh.
Missed it, I will add the docs about min_gaurantee and send the updated patch. It is not implemented in virsh. However, I have taken care of parsing them in domain configuration.
-- Three Cheers, Balbir
Hi Matthias, Here goes the updated patch. From: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com> 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 Signed-off-by: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com> --- 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 8ec7446..2b8ee34 100644 --- a/docs/formatdomain.html.in +++ b/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 diff --git a/src/libvirt.c b/src/libvirt.c index 2868460..629d97b 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 e0471b1..cb8e942 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -456,6 +456,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
On Mon, Oct 18, 2010 at 02:38:19PM +0530, Nikunj A. Dadhania wrote:
Hi Matthias,
Here goes the updated patch.
From: Nikunj A. Dadhania <nikunj@linux.vnet.ibm.com>
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
Looks fine to me, ACK, Applied and commited, thanks ! Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
participants (4)
-
Balbir Singh -
Daniel Veillard -
Matthias Bolte -
Nikunj A. Dadhania