[PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[George Dunlap]

mem-set is the primary command that users will need to use and
understand.  Move it first, and clarify the wording; also specify that
you can't set the target higher than maxmem from the domain config.

mem-max is actually a pretty useless command at the moment.  Clarify
that users are not expected to use it; and document all of its quirky
behavior.

Signed-off-by: George Dunlap <george.dunlap@citrix.com>
---
I'm actully somewhat tempted to take out the entry for mem-max
entirely -- it's not at all clear to me what anyone would use it for,
and it's only likely to confuse people.

CC: Ian Jackson <ian.jackson@citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Jan Beulich <jbeulich@suse.com>
CC: Tim Deegan <tim@xen.org>
CC: Konrad Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Julien Grall <julien.grall@arm.com>
CC: Lars Kurth <lars.kurth@citrix.com>
---
 docs/man/xl.pod.1.in | 72 ++++++++++++++++++++++++++++++--------------
 1 file changed, 50 insertions(+), 22 deletions(-)

diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
index b74764dcd3..1d3dabf185 100644
--- a/docs/man/xl.pod.1.in
+++ b/docs/man/xl.pod.1.in
@@ -393,40 +393,68 @@ less utilized than a high CPU workload.  Consider yourself warned.
 
 =back
 
-=item B<mem-max> I<domain-id> I<mem>
+=item B<mem-set> I<domain-id> I<mem>
 
-Specify the maximum amount of memory the domain is able to use, appending 't'
-for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b'
-for bytes.
+Set the target for the domain's balloon driver.  Append 't' for
+terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes
+and 'b' 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.
+This must be less than the initial B<maxmem> parameter in the domain's
+configuration.
 
-The value given just sets the memory amount the domain is allowed to allocate
-in the hypervisor. It can't be set 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). 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>.
+Note that this operation requests the guest operating system's balloon
+driver to reach the target amount of memory.  The guest may fail to
+reach that amount of memory for any number of reasons, including:
 
-The domain will not receive any signal regarding the changed memory limit.
+=over 4
 
-=item B<mem-set> I<domain-id> I<mem>
+=item
+
+The guest doesn't have a balloon driver installed
+
+=item
+
+The guest's balloon driver is buggy
+
+=item
+
+The guest's balloon driver cannot create free guest memory due to
+guest memory pressure
+
+=item
 
-Set the domain's used memory using the balloon driver; append 't' for
-terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' for
-bytes.
+The guest's balloon driver cannot allocate memory from Xen because of
+hypervisor memory pressure
 
-Because this operation requires cooperation from the domain operating
-system, there is no guarantee that it will succeed.  This command will
-definitely not work unless the domain has the required paravirt
-driver.
+=item
+
+The guest administrator has disabled the balloon driver
+
+=back
 
 B<Warning:> There is no good way to know in advance how small of a
 mem-set will make a domain unstable and cause it to crash.  Be very
 careful when using this command on running domains.
 
+=item B<mem-max> I<domain-id> I<mem>
+
+Specify the limit Xen will place on the amount of memory a guest may
+allocate. Append 't' for terabytes, 'g' for gigabytes, 'm' for
+megabytes, 'k' for kilobytes and 'b' for bytes.
+
+NB that users normally shouldn't need this command; B<xl mem-set> will
+set this as appropriate automatically.
+
+I<mem> can't be set lower than the current memory target for
+I<domain-id>.  It is allowed to be higher than the configured maximum
+memory size of the domain (B<maxmem> parameter in the domain's
+configuration). Note however that the initial B<maxmem> value is still
+used as an upper limit for B<xl mem-set>.  Also note that calling B<xl
+mem-set> will reset this value.
+
+The domain will not receive any signal regarding the changed memory
+limit.
+
 =item B<migrate> [I<OPTIONS>] I<domain-id> I<host>
 
 Migrate a domain to another host machine. By default B<xl> relies on ssh as a
-- 
2.18.0


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

Re: [PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[Lars Kurth]

On 01/08/2018, 16:41, "George Dunlap" <george.dunlap@citrix.com> wrote:

    mem-set is the primary command that users will need to use and
    understand.  Move it first, and clarify the wording; also specify that
    you can't set the target higher than maxmem from the domain config.
    
    mem-max is actually a pretty useless command at the moment.  Clarify
    that users are not expected to use it; and document all of its quirky
    behavior.
    
    Signed-off-by: George Dunlap <george.dunlap@citrix.com>
    ---
    I'm actully somewhat tempted to take out the entry for mem-max
    entirely -- it's not at all clear to me what anyone would use it for,
    and it's only likely to confuse people.

Should it be deprecated, if it isn't useful?
    
    CC: Ian Jackson <ian.jackson@citrix.com>
    CC: Wei Liu <wei.liu2@citrix.com>
    CC: Andrew Cooper <andrew.cooper3@citrix.com>
    CC: Jan Beulich <jbeulich@suse.com>
    CC: Tim Deegan <tim@xen.org>
    CC: Konrad Wilk <konrad.wilk@oracle.com>
    CC: Stefano Stabellini <sstabellini@kernel.org>
    CC: Julien Grall <julien.grall@arm.com>
    CC: Lars Kurth <lars.kurth@citrix.com>
    ---
     docs/man/xl.pod.1.in | 72 ++++++++++++++++++++++++++++++--------------
     1 file changed, 50 insertions(+), 22 deletions(-)
    
    diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
    index b74764dcd3..1d3dabf185 100644
    --- a/docs/man/xl.pod.1.in
    +++ b/docs/man/xl.pod.1.in
    @@ -393,40 +393,68 @@ less utilized than a high CPU workload.  Consider yourself warned.
     
     =back
     
    -=item B<mem-max> I<domain-id> I<mem>
    +=item B<mem-set> I<domain-id> I<mem>
     
    -Specify the maximum amount of memory the domain is able to use, appending 't'
    -for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b'
    -for bytes.
    +Set the target for the domain's balloon driver.  Append 't' for

I would say Use instead of Append: if you are not a native speaker you could
be misled that the command appends memory.
 
    +terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes
    +and 'b' 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.
    +This must be less than the initial B<maxmem> parameter in the domain's
    +configuration.

What happens if it is bigger? Will you get an error, or will the system likely 
crash?
     
    -The value given just sets the memory amount the domain is allowed to allocate
    -in the hypervisor. It can't be set 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). 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>.
    +Note that this operation requests the guest operating system's balloon
    +driver to reach the target amount of memory.  The guest may fail to
    +reach that amount of memory for any number of reasons, including:
     
    -The domain will not receive any signal regarding the changed memory limit.
    +=over 4
     
    -=item B<mem-set> I<domain-id> I<mem>
    +=item
    +
    +The guest doesn't have a balloon driver installed
    +
    +=item
    +
    +The guest's balloon driver is buggy
    +
    +=item
    +
    +The guest's balloon driver cannot create free guest memory due to
    +guest memory pressure
    +
    +=item
     
    -Set the domain's used memory using the balloon driver; append 't' for
    -terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' for
    -bytes.
    +The guest's balloon driver cannot allocate memory from Xen because of
    +hypervisor memory pressure
     
    -Because this operation requires cooperation from the domain operating
    -system, there is no guarantee that it will succeed.  This command will
    -definitely not work unless the domain has the required paravirt
    -driver.
    +=item
    +
    +The guest administrator has disabled the balloon driver
    +
    +=back
     
     B<Warning:> There is no good way to know in advance how small of a
     mem-set will make a domain unstable and cause it to crash.  Be very
     careful when using this command on running domains.
     
    +=item B<mem-max> I<domain-id> I<mem>
    +
    +Specify the limit Xen will place on the amount of memory a guest may
    +allocate. Append 't' for terabytes, 'g' for gigabytes, 'm' for
    +megabytes, 'k' for kilobytes and 'b' for bytes.

Same as above: Use instead of Append

    +
    +NB that users normally shouldn't need this command; B<xl mem-set> will
    +set this as appropriate automatically.
    +
    +I<mem> can't be set lower than the current memory target for
    +I<domain-id>.  It is allowed to be higher than the configured maximum
    +memory size of the domain (B<maxmem> parameter in the domain's
    +configuration). Note however that the initial B<maxmem> value is still
    +used as an upper limit for B<xl mem-set>.  Also note that calling B<xl
    +mem-set> will reset this value.
    +
    +The domain will not receive any signal regarding the changed memory
    +limit.
    +
     =item B<migrate> [I<OPTIONS>] I<domain-id> I<host>
     
     Migrate a domain to another host machine. By default B<xl> relies on ssh as a
    -- 

Reviewed-by: lars.kurth@citrix.com
    
    

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

Re: [PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[George Dunlap]

On 08/01/2018 05:16 PM, Lars Kurth wrote:
> 
> 
> On 01/08/2018, 16:41, "George Dunlap" <george.dunlap@citrix.com> wrote:
> 
>     mem-set is the primary command that users will need to use and
>     understand.  Move it first, and clarify the wording; also specify that
>     you can't set the target higher than maxmem from the domain config.
>     
>     mem-max is actually a pretty useless command at the moment.  Clarify
>     that users are not expected to use it; and document all of its quirky
>     behavior.
>     
>     Signed-off-by: George Dunlap <george.dunlap@citrix.com>
>     ---
>     I'm actully somewhat tempted to take out the entry for mem-max
>     entirely -- it's not at all clear to me what anyone would use it for,
>     and it's only likely to confuse people.
> 
> Should it be deprecated, if it isn't useful?
>     
>     CC: Ian Jackson <ian.jackson@citrix.com>
>     CC: Wei Liu <wei.liu2@citrix.com>
>     CC: Andrew Cooper <andrew.cooper3@citrix.com>
>     CC: Jan Beulich <jbeulich@suse.com>
>     CC: Tim Deegan <tim@xen.org>
>     CC: Konrad Wilk <konrad.wilk@oracle.com>
>     CC: Stefano Stabellini <sstabellini@kernel.org>
>     CC: Julien Grall <julien.grall@arm.com>
>     CC: Lars Kurth <lars.kurth@citrix.com>
>     ---
>      docs/man/xl.pod.1.in | 72 ++++++++++++++++++++++++++++++--------------
>      1 file changed, 50 insertions(+), 22 deletions(-)
>     
>     diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
>     index b74764dcd3..1d3dabf185 100644
>     --- a/docs/man/xl.pod.1.in
>     +++ b/docs/man/xl.pod.1.in
>     @@ -393,40 +393,68 @@ less utilized than a high CPU workload.  Consider yourself warned.
>      
>      =back
>      
>     -=item B<mem-max> I<domain-id> I<mem>
>     +=item B<mem-set> I<domain-id> I<mem>
>      
>     -Specify the maximum amount of memory the domain is able to use, appending 't'
>     -for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b'
>     -for bytes.
>     +Set the target for the domain's balloon driver.  Append 't' for
> 
> I would say Use instead of Append: if you are not a native speaker you could
> be misled that the command appends memory.

I'm afraid 'use' doesn't tell me what to do -- `set-max A t`? `set-max A
2048 t`?  `set-max A t2048`?

What about making a paragraph break and changing it to:

"The default unit is kiB.  Add 't' to specify TiB, 'g' for GiB, 'm' for
MiB, and 'b' for bytes (e.g., 2048m)."

Alternate we could say `I<mem>[<unit>]`, but that seems to be getting a
little clunky.

>     +terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes
>     +and 'b' 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.
>     +This must be less than the initial B<maxmem> parameter in the domain's
>     +configuration.
> 
> What happens if it is bigger? Will you get an error, or will the system likely 
> crash?

libxl will return an error.  It's never OK for a command for which we
have a precise limit to crash the system.  (NB the WARNING at the bottom
of this section, about not having a clear lower limit.)

> Reviewed-by: lars.kurth@citrix.com

Thanks

 -George

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

Re: [PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[Lars Kurth]

On 02/08/2018, 11:24, "George Dunlap" <george.dunlap@citrix.com> wrote:

    On 08/01/2018 05:16 PM, Lars Kurth wrote:
    > 
    > 
    > On 01/08/2018, 16:41, "George Dunlap" <george.dunlap@citrix.com> wrote:
    > 
    >     mem-set is the primary command that users will need to use and
    >     understand.  Move it first, and clarify the wording; also specify that
    >     you can't set the target higher than maxmem from the domain config.
    >     
    >     mem-max is actually a pretty useless command at the moment.  Clarify
    >     that users are not expected to use it; and document all of its quirky
    >     behavior.
    >     
    >     Signed-off-by: George Dunlap <george.dunlap@citrix.com>
    >     ---
    >     I'm actully somewhat tempted to take out the entry for mem-max
    >     entirely -- it's not at all clear to me what anyone would use it for,
    >     and it's only likely to confuse people.
    > 
    > Should it be deprecated, if it isn't useful?
    >     
    >     CC: Ian Jackson <ian.jackson@citrix.com>
    >     CC: Wei Liu <wei.liu2@citrix.com>
    >     CC: Andrew Cooper <andrew.cooper3@citrix.com>
    >     CC: Jan Beulich <jbeulich@suse.com>
    >     CC: Tim Deegan <tim@xen.org>
    >     CC: Konrad Wilk <konrad.wilk@oracle.com>
    >     CC: Stefano Stabellini <sstabellini@kernel.org>
    >     CC: Julien Grall <julien.grall@arm.com>
    >     CC: Lars Kurth <lars.kurth@citrix.com>
    >     ---
    >      docs/man/xl.pod.1.in | 72 ++++++++++++++++++++++++++++++--------------
    >      1 file changed, 50 insertions(+), 22 deletions(-)
    >     
    >     diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
    >     index b74764dcd3..1d3dabf185 100644
    >     --- a/docs/man/xl.pod.1.in
    >     +++ b/docs/man/xl.pod.1.in
    >     @@ -393,40 +393,68 @@ less utilized than a high CPU workload.  Consider yourself warned.
    >      
    >      =back
    >      
    >     -=item B<mem-max> I<domain-id> I<mem>
    >     +=item B<mem-set> I<domain-id> I<mem>
    >      
    >     -Specify the maximum amount of memory the domain is able to use, appending 't'
    >     -for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b'
    >     -for bytes.
    >     +Set the target for the domain's balloon driver.  Append 't' for
    > 
    > I would say Use instead of Append: if you are not a native speaker you could
    > be misled that the command appends memory.
    
    I'm afraid 'use' doesn't tell me what to do -- `set-max A t`? `set-max A
    2048 t`?  `set-max A t2048`?
    
    What about making a paragraph break and changing it to:
    
    "The default unit is kiB.  Add 't' to specify TiB, 'g' for GiB, 'm' for
    MiB, and 'b' for bytes (e.g., 2048m)."
    
    Alternate we could say `I<mem>[<unit>]`, but that seems to be getting a
    little clunky.

I will leave that up to you. It's just something I noticed but not a big deal. 

Lars 

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

Re: [PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[Wei Liu]

On Wed, Aug 01, 2018 at 04:41:24PM +0100, George Dunlap wrote:
> mem-set is the primary command that users will need to use and
> understand.  Move it first, and clarify the wording; also specify that
> you can't set the target higher than maxmem from the domain config.
> 
> mem-max is actually a pretty useless command at the moment.  Clarify
> that users are not expected to use it; and document all of its quirky
> behavior.
> 
> Signed-off-by: George Dunlap <george.dunlap@citrix.com>

Looks okay to me. I'm expecting a new version of this patch.

Wei.

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