Skip to contentSkip to conversation

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

PATCH In review George Dunlap 4 participants 6 messages Apr 8, 2019 – May 13, 2019

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 docs/xl: Clarify documentation for mem-max and mem-set

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.

---
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 <[email protected]>
CC Wei Liu <[email protected]>
CC Andrew Cooper <[email protected]>
CC Jan Beulich <[email protected]>
CC Tim Deegan <[email protected]>
CC Konrad Wilk <[email protected]>
CC Stefano Stabellini <[email protected]>
CC Julien Grall <[email protected]>
CC Lars Kurth <[email protected]>
---
 docs/man/xl.1.pod.in | 75 +++++++++++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 22 deletions(-)
docs/man/xl.1.pod.in +53 -22
index 4310fcd818..f44f054dfb 100644
@@ -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
Signature · 7 lines
2.20.1


_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
#1 lore raw
Quoted 8 lines · 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.

Quoted 8 lines

---
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

_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel

#2 lore raw
In reply to George Dunlap
Quoted 9 lines · 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.

Wei / Ian: Ping?

Juergen replied to my "review note" comment, not to anything actionable in the patch (or commit message) itself.

-George

_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel

Acked-by
#3 lore raw
Quoted 9 lines · George Dunlap
Quoted 8 lines · 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.

Quoted 6 lines
Quoted 1 line

Wei / Ian: Ping?

Juergen replied to my "review note" comment, not to anything actionable in the patch (or commit message) itself.

(I already said this looked okay to me in v1)

_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel

#4 lore raw
Quoted 12 lines · Wei Liu
Quoted 11 lines · George Dunlap
Quoted 9 lines · 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.

Quoted 8 lines
Quoted 4 lines

Wei / Ian: Ping?

Juergen replied to my "review note" comment, not to anything actionable in the patch (or commit message) itself.

(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.

_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel

#5 lore raw

On 13/05/2019, 08:28, "Wei Liu" <[email protected]> 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 <[email protected]>
> >
> > 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 <[email protected]>
>
> (I already said this looked okay to me in v1)

I believe Lars' Rb from v1 still stands.

Yes
Lars

_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel