Re: [Xen-devel] [PATCH v4 4/4] xl: Improve xl documentation in regards to guest memory management

[Daniel Kiper <daniel.kiper@xxxxxxxxxx>]

On Mon, Apr 29, 2013 at 03:32:40PM +0100, Ian Campbell wrote:
> On Mon, 2013-04-29 at 12:09 +0100, Daniel Kiper wrote:
> > Improve xl documentation in regards to guest memory management.
>
> Thank you for remembering docs!

During Document Day it is a must... ;-)))

> Could I ask that where you are documenting new options, xenstore paths
> or xl commands etc you do it in the patch which makes the code change.
> I'm thinking specifically of the addition of mem_set_enforce_limit and

Sure...

> the new xenstore paths. I'm not sure if the libxl_memory.txt changes
> corresponds to a code change or not.

Yes, it does.

> > Some improvements are suggested by Ian Jackson and Konrad Rzeszutek Wilk.
> >
> > Signed-off-by: Daniel Kiper <daniel.kiper@xxxxxxxxxx>
> > ---
> >  docs/man/xl.conf.pod.5            |   15 +++++
> >  docs/misc/libxl_memory.txt        |  124 
> > +++++++++++++++++++++----------------
> >  docs/misc/xenstore-paths.markdown |   22 ++++---
> >  tools/examples/xl.conf            |    4 ++
> >  4 files changed, 105 insertions(+), 60 deletions(-)
> >
> > diff --git a/docs/man/xl.conf.pod.5 b/docs/man/xl.conf.pod.5
> > index 1229c8a..658b1eb 100644
> > --- a/docs/man/xl.conf.pod.5
> > +++ b/docs/man/xl.conf.pod.5
> > @@ -62,6 +62,21 @@ of memory given to domain 0 by default.
> >
> >  Default: C<"auto">
> >
> > +=item B<mem_set_enforce_limit=BOOLEAN>
> > +
> > +If enabled, then C<xl mem-set> by default will set a memory allocation
> > +target and enforce the maximum memory allocation for each domain.
> > +If disabled, then C<xl mem-set> by default will set only a memory 
> > allocation
> > +target for each domain.
> > +
> > +The memory allocation target is a suggested amount of memory which
> > +should be allocated by a guest. It is nice when the guest follows this
> > +value but it may have its own idea about memory requirments. However,
>
>                                                   requirements.
>
> > +it could not allocate more memory than a ceiling known as the maximum
> > +memory allocation.
> > +
> > +Default: C<1>
> > +
> >  =item B<run_hotplug_scripts=BOOLEAN>
> >
> >  If disabled hotplug scripts will be called from udev, as it used to
> > diff --git a/docs/misc/libxl_memory.txt b/docs/misc/libxl_memory.txt
> > index 253476d..b89214a 100644
> > --- a/docs/misc/libxl_memory.txt
> > +++ b/docs/misc/libxl_memory.txt
> > @@ -1,70 +1,90 @@
> >  /* === Domain memory breakdown: HVM guests 
> > ==================================
> > -
> > -             +  +----------+                                     +
> > -             |  | shadow   |                                     |
> > -             |  +----------+                                     |
> > -    overhead |  | extra    |                                     |
> > -             |  | external |                                     |
> > -             |  +----------+                          +          |
> > -             |  | extra    |                          |          |
> > -             |  | internal |                          |          |
> > -             +  +----------+                +         |          | 
> > footprint
> > -             |  | video    |                |         |          |
> > -             |  +----------+  +    +        |         | xen      |
> > -             |  |          |  |    |        | actual  | maximum  |
> > -             |  |          |  |    |        | target  |          |
> > -             |  | guest    |  |    | build  |         |          |
> > -             |  |          |  |    | start  |         |          |
> > -      static |  |          |  |    |        |         |          |
> > -     maximum |  +----------+  |    +        +         +          +
> > -             |  |          |  |
> > -             |  |          |  |
> > -             |  | balloon  |  | build
> > -             |  |          |  | maximum
> > -             |  |          |  |
> > -             +  +----------+  +
> > -
> > -
> > +
> > +             +  +----------+                                               
> >  +
> > +             |  | shadow   |                                               
> >  |
> > +             |  +----------+                                               
> >  |
> > +    overhead |  | extra    |                                               
> >  |
> > +             |  | external |                                               
> >  |
> > +             |  +----------+                                     +         
> >  |
> > +             |  | extra    |                                     |         
> >  |
> > +             |  | internal |                                     |         
> >  |
> > +             +  +----------+  +                        +         |         
> >  | footprint
> > +             |  | video    |  |                        |         |         
> >  |
> > +             |  +----------+  |          +    +        |         | xen     
> >  |
> > +             |  |          |  |          |    |        | actual  | maximum 
> >  |
> > +             |  |          |  |          |    |        | target  |         
> >  |
> > +             |  | guest    |  |          |    | build  |         |         
> >  |
> > +             |  |          |  |          |    | start  |         |         
> >  |
> > +             |  |          |  |          |    |        |         |         
> >  |
> > +             |  +----------+  |          |    +        +         +         
> >  +
> > +             |  |          |  |          |
> > +             |  |          |  |          |
> > +       guest |  |          |  |          | build
> > +     maximum |  |          |  |          | maximum
> > +             |  | balloon  |  |          |
> > +             |  |          |  |          |
> > +             |  |          |  | static   |
> > +             |  |          |  | maximum  |
> > +             |  |          |  |          |
> > +             |  +----------+  +          +
> > +             |  |          |
> > +             |  | memory   |
> > +             |  | hotplug  |
> > +             |  |          |
> > +             +  +----------+
>
> Hard to read a diff of a picture, do I understand correctly that you
> have just added guest-maximum and moved static maximum over to the other
> side?

Right.

> How about, on the left (aligned as appropriate with the existing boxes
> etc):
>
> overhead         +
>                  |
>        +         +
>        |         |
>        |  static |
>        |  maximum|
>        |         |
> guest  |         +
> maximum|         |
>        |  memory |
>        |  hotplug|
>        |         |
>        +         +
> ?

OK.


[...]

> >   ========================================================================= 
> > */
> > diff --git a/docs/misc/xenstore-paths.markdown 
> > b/docs/misc/xenstore-paths.markdown
> > index 535830e..1ac2159 100644
> > --- a/docs/misc/xenstore-paths.markdown
> > +++ b/docs/misc/xenstore-paths.markdown
> > @@ -124,18 +124,24 @@ This protocol is not currently well documented.
> >
> >  #### ~/memory/static-max = MEMKB []
> >
> > -Specifies a static maximum amount memory which this domain should
> > -expect to be given. In the absence of in-guest memory hotplug support
> > -this set on domain boot and is usually the maximum amount of RAM which
> > -a guest can make use of. See [docs/misc/libxl_memory.txt][LIBXLMEM]
> > -for a description of how memory is accounted for in toolstacks using
> > -the libxl library.
> > +Specifies a static maximum amount of memory which this domain
> > +should expect to be given. It is usually the maximum amount
> > +of RAM which a guest can make use of. This value is set on the
> > +domain boot. If ~/memory/guest-max is set then static maximum
> > +is ignored by libxl. See [docs/misc/libxl_memory.txt][LIBXLMEM]
> > +for a description of how the memory is accounted for in toolstacks
> > +using the libxl library.
>
> I'd retain the "and in the absence of in-guest..." stuff here but go on
> to add a sentence lile "If in-guest memory hotplug is supported, then it
> will write guest-max (see below).
>
> The key point is to describe the behaviour with and without hotplug.

I think that every new polite guest, with or without memory hotplug,
should inform about its maximum supported memory size. It means
that we should not differentiate both cases here.

Daniel

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel