[PATCH] docs: clarify xl mem-max semantics

[PATCH] docs: clarify xl mem-max semantics

[Juergen Gross]

The information given in the xl man page for the mem-max command is
rather brief. Expand it in order to let the reader understand what it
is really doing.

As the related libxl function libxl_domain_setmaxmem() isn't much
clearer add a comment to it explaining the desired semantics.

Signed-off-by: Juergen Gross <jgross@suse.com>
---
 docs/man/xl.pod.1.in | 10 ++++++++++
 tools/libxl/libxl.c  |  6 ++++++
 2 files changed, 16 insertions(+)

diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
index 09c1faa..62307e8 100644
--- a/docs/man/xl.pod.1.in
+++ b/docs/man/xl.pod.1.in
@@ -401,6 +401,16 @@ for bytes.
 The mem-max value may not correspond to the actual memory used in the
 domain, as it may balloon down its memory to give more back to the OS.
 
+The value given just sets the memory amount the domain is allowed to allocate
+in the hypervisor. Thus it can't be lower than the current reservation, but
+it is allowed to be higher than the configured maximum memory size of the
+domain (B<maxmem> parameter in the domain's configuration). Setting the
+allowed memory size via B<xl mem-max> above the B<maxmem> size won't let use
+this value to be used for B<xl mem-set>, as B<xl mem-set> will still use
+B<maxmem> as an upper limit.
+
+The domain is not receiving any signal regarding the changed memory limit.
+
 =item B<mem-set> I<domain-id> I<mem>
 
 Set the domain's used memory using the balloon driver; append 't' for
diff --git a/tools/libxl/libxl.c b/tools/libxl/libxl.c
index 0622311..ed59510 100644
--- a/tools/libxl/libxl.c
+++ b/tools/libxl/libxl.c
@@ -4018,6 +4018,12 @@ out:
 
 /******************************************************************************/
 
+/*
+ * Set the maximum memory size of the domain in the hypervisor. There is no
+ * change of the current memory size involved. The allowed memory size can
+ * even be above the configured maxmem size of the domain, but the related
+ * Xenstore entry memory/static-max isn't modified!
+ */
 int libxl_domain_setmaxmem(libxl_ctx *ctx, uint32_t domid, uint64_t max_memkb)
 {
     GC_INIT(ctx);
-- 
2.10.2


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [PATCH] docs: clarify xl mem-max semantics

[Konrad Rzeszutek Wilk]

On Fri, Jan 20, 2017 at 10:54:18AM +0100, Juergen Gross wrote:
> The information given in the xl man page for the mem-max command is
> rather brief. Expand it in order to let the reader understand what it
> is really doing.
> 
> As the related libxl function libxl_domain_setmaxmem() isn't much
> clearer add a comment to it explaining the desired semantics.

CC-ing Daniel
> 
> Signed-off-by: Juergen Gross <jgross@suse.com>
> ---
>  docs/man/xl.pod.1.in | 10 ++++++++++
>  tools/libxl/libxl.c  |  6 ++++++
>  2 files changed, 16 insertions(+)
> 
> diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
> index 09c1faa..62307e8 100644
> --- a/docs/man/xl.pod.1.in
> +++ b/docs/man/xl.pod.1.in
> @@ -401,6 +401,16 @@ for bytes.
>  The mem-max value may not correspond to the actual memory used in the
>  domain, as it may balloon down its memory to give more back to the OS.
>  
> +The value given just sets the memory amount the domain is allowed to allocate
> +in the hypervisor. Thus it can't be lower than the current reservation, but
> +it is allowed to be higher than the configured maximum memory size of the
> +domain (B<maxmem> parameter in the domain's configuration). Setting the
> +allowed memory size via B<xl mem-max> above the B<maxmem> size won't let use
> +this value to be used for B<xl mem-set>, as B<xl mem-set> will still use
> +B<maxmem> as an upper limit.
> +
> +The domain is not receiving any signal regarding the changed memory limit.
> +
>  =item B<mem-set> I<domain-id> I<mem>
>  
>  Set the domain's used memory using the balloon driver; append 't' for
> diff --git a/tools/libxl/libxl.c b/tools/libxl/libxl.c
> index 0622311..ed59510 100644
> --- a/tools/libxl/libxl.c
> +++ b/tools/libxl/libxl.c
> @@ -4018,6 +4018,12 @@ out:
>  
>  /******************************************************************************/
>  
> +/*
> + * Set the maximum memory size of the domain in the hypervisor. There is no
> + * change of the current memory size involved. The allowed memory size can
> + * even be above the configured maxmem size of the domain, but the related
> + * Xenstore entry memory/static-max isn't modified!
> + */
>  int libxl_domain_setmaxmem(libxl_ctx *ctx, uint32_t domid, uint64_t max_memkb)
>  {
>      GC_INIT(ctx);
> -- 
> 2.10.2
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> https://lists.xen.org/xen-devel

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [PATCH] docs: clarify xl mem-max semantics

[Ian Jackson]

Konrad Rzeszutek Wilk writes ("Re: [Xen-devel] [PATCH] docs: clarify xl mem-max semantics"):
> On Fri, Jan 20, 2017 at 10:54:18AM +0100, Juergen Gross wrote:
> >  The mem-max value may not correspond to the actual memory used in the
> >  domain, as it may balloon down its memory to give more back to the OS.

Thanks for working on this.

> > +The value given just sets the memory amount the domain is allowed
> > +to allocate in the hypervisor. Thus it can't be lower than the
> > +current reservation,

This is not true.  It is perfectly possible to set max_pages lower
than the current reservation.  This is routine: xl mem-set does it
when the guest is being asked to shrink.  It prevents the guest from
growing instead.

Setting max_pages < target seems like it wouldn't make sense but as I
don't understand the system setup for target != max_pages I don't feel
confident about that.

> > + * change of the current memory size involved. The allowed memory size can
> > + * even be above the configured maxmem size of the domain, but the related
> > + * Xenstore entry memory/static-max isn't modified!

static-max is an "almost unrelated" entry, not a "related" one.

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [PATCH] docs: clarify xl mem-max semantics

[Juergen Gross]

On 20/01/17 16:51, Ian Jackson wrote:
> Konrad Rzeszutek Wilk writes ("Re: [Xen-devel] [PATCH] docs: clarify xl mem-max semantics"):
>> On Fri, Jan 20, 2017 at 10:54:18AM +0100, Juergen Gross wrote:
>>>  The mem-max value may not correspond to the actual memory used in the
>>>  domain, as it may balloon down its memory to give more back to the OS.
> 
> Thanks for working on this.
> 
>>> +The value given just sets the memory amount the domain is allowed
>>> +to allocate in the hypervisor. Thus it can't be lower than the
>>> +current reservation,
> 
> This is not true.  It is perfectly possible to set max_pages lower
> than the current reservation.  This is routine: xl mem-set does it
> when the guest is being asked to shrink.  It prevents the guest from
> growing instead.
> 
> Setting max_pages < target seems like it wouldn't make sense but as I
> don't understand the system setup for target != max_pages I don't feel
> confident about that.

xl mem-max won't let you set the value below current reservation.
There is an explicit test in libxl_domain_setmaxmem() to deny such an
attempt.

You are right, however, that there is no causal link between above two
sentences as the wording implies. I'll rephrase that part.

>>> + * change of the current memory size involved. The allowed memory size can
>>> + * even be above the configured maxmem size of the domain, but the related
>>> + * Xenstore entry memory/static-max isn't modified!
> 
> static-max is an "almost unrelated" entry, not a "related" one.

static-max is related to maxmem. It isn't really related to max_pages.


Juergen


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [PATCH] docs: clarify xl mem-max semantics

[Jim Fehlig]

On 01/20/2017 02:54 AM, Juergen Gross wrote:
> The information given in the xl man page for the mem-max command is
> rather brief. Expand it in order to let the reader understand what it
> is really doing.
>
> As the related libxl function libxl_domain_setmaxmem() isn't much
> clearer add a comment to it explaining the desired semantics.
>
> Signed-off-by: Juergen Gross <jgross@suse.com>
> ---
>  docs/man/xl.pod.1.in | 10 ++++++++++
>  tools/libxl/libxl.c  |  6 ++++++
>  2 files changed, 16 insertions(+)
>
> diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
> index 09c1faa..62307e8 100644
> --- a/docs/man/xl.pod.1.in
> +++ b/docs/man/xl.pod.1.in
> @@ -401,6 +401,16 @@ for bytes.
>  The mem-max value may not correspond to the actual memory used in the
>  domain, as it may balloon down its memory to give more back to the OS.
>
> +The value given just sets the memory amount the domain is allowed to allocate
> +in the hypervisor. Thus it can't be lower than the current reservation, but
> +it is allowed to be higher than the configured maximum memory size of the
> +domain (B<maxmem> parameter in the domain's configuration). Setting the
> +allowed memory size via B<xl mem-max> above the B<maxmem> size won't let use
> +this value to be used for B<xl mem-set>, as B<xl mem-set> will still use
> +B<maxmem> as an upper limit.

I find the last sentence a bit awkward. Might I suggest

Using B<xl mem-max> to set the maximum memory above the initial B<maxmem> value 
will not allow the additional memory to be used via B<xl mem-set>. The initial 
B<maxmem> value is still used as an upper limit for B<xl mem-set>.

Regards,
Jim

> +
> +The domain is not receiving any signal regarding the changed memory limit.
> +
>  =item B<mem-set> I<domain-id> I<mem>
>
>  Set the domain's used memory using the balloon driver; append 't' for
> diff --git a/tools/libxl/libxl.c b/tools/libxl/libxl.c
> index 0622311..ed59510 100644
> --- a/tools/libxl/libxl.c
> +++ b/tools/libxl/libxl.c
> @@ -4018,6 +4018,12 @@ out:
>
>  /******************************************************************************/
>
> +/*
> + * Set the maximum memory size of the domain in the hypervisor. There is no
> + * change of the current memory size involved. The allowed memory size can
> + * even be above the configured maxmem size of the domain, but the related
> + * Xenstore entry memory/static-max isn't modified!
> + */
>  int libxl_domain_setmaxmem(libxl_ctx *ctx, uint32_t domid, uint64_t max_memkb)
>  {
>      GC_INIT(ctx);
>


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [PATCH] docs: clarify xl mem-max semantics

[Juergen Gross]

On 21/01/17 00:15, Jim Fehlig wrote:
> On 01/20/2017 02:54 AM, Juergen Gross wrote:
>> The information given in the xl man page for the mem-max command is
>> rather brief. Expand it in order to let the reader understand what it
>> is really doing.
>>
>> As the related libxl function libxl_domain_setmaxmem() isn't much
>> clearer add a comment to it explaining the desired semantics.
>>
>> Signed-off-by: Juergen Gross <jgross@suse.com>
>> ---
>>  docs/man/xl.pod.1.in | 10 ++++++++++
>>  tools/libxl/libxl.c  |  6 ++++++
>>  2 files changed, 16 insertions(+)
>>
>> diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
>> index 09c1faa..62307e8 100644
>> --- a/docs/man/xl.pod.1.in
>> +++ b/docs/man/xl.pod.1.in
>> @@ -401,6 +401,16 @@ for bytes.
>>  The mem-max value may not correspond to the actual memory used in the
>>  domain, as it may balloon down its memory to give more back to the OS.
>>
>> +The value given just sets the memory amount the domain is allowed to
>> allocate
>> +in the hypervisor. Thus it can't be lower than the current
>> reservation, but
>> +it is allowed to be higher than the configured maximum memory size of
>> the
>> +domain (B<maxmem> parameter in the domain's configuration). Setting the
>> +allowed memory size via B<xl mem-max> above the B<maxmem> size won't
>> let use
>> +this value to be used for B<xl mem-set>, as B<xl mem-set> will still use
>> +B<maxmem> as an upper limit.
> 
> I find the last sentence a bit awkward. Might I suggest
> 
> Using B<xl mem-max> to set the maximum memory above the initial
> B<maxmem> value will not allow the additional memory to be used via B<xl
> mem-set>. The initial B<maxmem> value is still used as an upper limit
> for B<xl mem-set>.

Yes, this is better.


Thanks,

Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel