| Message ID | 20190408110943.8987-1-george.dunlap@citrix.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] docs/xl: Clarify documentation for mem-max and mem-set | expand |
On 08/04/2019 13:09, 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> > --- > v2: > - Reword memory unit section based on review feedback > > 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. It is needed for being able to hotplug memory to a domain. You'll need to: - raise the limit of the domain via xl mem-max - modify the static-max xenstore entry - trigger hotplug in the domain (e.g. via ACPI in HVM) Making the interface more usable is on my agenda for quite a while now, but I have been too busy with other stuff lately. Juergen
On 4/8/19 12:09 PM, 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> Wei / Ian: Ping? Juergen replied to my "review note" comment, not to anything actionable in the patch (or commit message) itself. -George
On Wed, May 01, 2019 at 03:59:41PM +0100, George Dunlap wrote: > On 4/8/19 12:09 PM, 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> > > Wei / Ian: Ping? > > Juergen replied to my "review note" comment, not to anything actionable > in the patch (or commit message) itself. Acked-by: Wei Liu <wei.liu2@citrix.com> (I already said this looked okay to me in v1)
On Mon, May 13, 2019 at 02:59:30PM +0100, Wei Liu wrote: > On Wed, May 01, 2019 at 03:59:41PM +0100, George Dunlap wrote: > > On 4/8/19 12:09 PM, 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> > > > > Wei / Ian: Ping? > > > > Juergen replied to my "review note" comment, not to anything actionable > > in the patch (or commit message) itself. > > Acked-by: Wei Liu <wei.liu2@citrix.com> > > (I already said this looked okay to me in v1) I believe Lars' Rb from v1 still stands. I will add while I commit this patch.
On 13/05/2019, 08:28, "Wei Liu" <wei.liu2@citrix.com> wrote:
On Mon, May 13, 2019 at 02:59:30PM +0100, Wei Liu wrote:
> On Wed, May 01, 2019 at 03:59:41PM +0100, George Dunlap wrote:
> > On 4/8/19 12:09 PM, 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>
> >
> > Wei / Ian: Ping?
> >
> > Juergen replied to my "review note" comment, not to anything actionable
> > in the patch (or commit message) itself.
>
> Acked-by: Wei Liu <wei.liu2@citrix.com>
>
> (I already said this looked okay to me in v1)
I believe Lars' Rb from v1 still stands.
Yes
Lars
diff --git a/docs/man/xl.1.pod.in b/docs/man/xl.1.pod.in index 4310fcd818..f44f054dfb 100644 --- a/docs/man/xl.1.pod.in +++ b/docs/man/xl.1.pod.in @@ -393,40 +393,71 @@ 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. -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 default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for +MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB). -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>. +This must be less than the initial B<maxmem> parameter in the domain's +configuration. -The domain will not receive any signal regarding the changed memory limit. +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: -=item B<mem-set> I<domain-id> I<mem> +=over 4 + +=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. + +The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for +MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB). + +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
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> --- v2: - Reword memory unit section based on review feedback 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.1.pod.in | 75 +++++++++++++++++++++++++++++++------------- 1 file changed, 53 insertions(+), 22 deletions(-)