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

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

On 01/08/2018, 16:41, "George Dunlap" <george.dunlap@xxxxxxxxxx> 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@xxxxxxxxxx>
    ---
    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@xxxxxxxxxx>
    CC: Wei Liu <wei.liu2@xxxxxxxxxx>
    CC: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    CC: Jan Beulich <jbeulich@xxxxxxxx>
    CC: Tim Deegan <tim@xxxxxxx>
    CC: Konrad Wilk <konrad.wilk@xxxxxxxxxx>
    CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
    CC: Julien Grall <julien.grall@xxxxxxx>
    CC: Lars Kurth <lars.kurth@xxxxxxxxxx>
    ---
     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@xxxxxxxxxx
    
    

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