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

[George Dunlap <george.dunlap@citrix.com>]

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