|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Xen-devel] [PATCH v4 4/4] xl: Improve xl documentation in regards to guest memory management
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!
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
the new xenstore paths. I'm not sure if the libxl_memory.txt changes
corresponds to a code change or not.
> 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?
How about, on the left (aligned as appropriate with the existing boxes
etc):
overhead +
|
+ +
| |
| static |
| maximum|
| |
guest | +
maximum| |
| memory |
| hotplug|
| |
+ +
?
> +
> +
> extra internal = LIBXL_MAXMEM_CONSTANT
> extra external = LIBXL_HVM_EXTRA_MEMORY
> shadow = libxl_domain_build_info.shadow_memkb
> static maximum = libxl_domain_build_info.max_memkb
> video = libxl_domain_build_info.video_memkb
> build start = libxl_domain_build_info.target_memkb
> + guest maximum = declared by a guest its maximum supported memory size
^comma here I think? Or "as"
> libxl_domain_setmaxmem -> xen maximum
> - libxl_set_memory_target -> actual target
> -
> -
> + libxl_set_memory_target -> actual target & optionaly xen maximum
optionally
> +
> +
> === Domain memory breakdown: PV guests ==================================
> -
> -
> - + +----------+ +
> - overhead | | extra | |
> - | | external | |
> - | +----------+ + |
> - | | extra | | |
> - | | internal | | |
> - + +----------+ + + + | | footprint
> - | | | | | | | xen |
> - | | | | | | actual | maximum |
> - | | guest | | | build | target | |
> - | | | | | start | | |
> - static | | | | | | | |
> - maximum | +----------+ | + + + +
> - | | | |
> - | | | |
> - | | balloon | | build
> - | | | | maximum
> - | | | |
> - + +----------+ +
> -
> +
> +
> + + +----------+ +
> + overhead | | extra | |
> + | | external | |
> + | +----------+ + |
> + | | extra | | |
> + | | internal | | |
> + + +----------+ + + + + |
> | footprint
> + | | | | | | | | xen |
> + | | | | | | | actual | maximum |
> + | | guest | | | | build | target | |
> + | | | | | | start | | |
> + | | | | | | | | |
> + | +----------+ | | + + + +
> + | | | | |
> + | | | | |
> + | | | | | build
> + guest | | | | | maximum
> + maximum | | balloon | | |
> + | | | | |
> + | | | | static |
> + | | | | maximum |
> + | | | | |
> + | +----------+ + +
> + | | |
> + | | memory |
> + | | hotplug |
> + | | |
> + + +----------+
> +
>
> extra internal = LIBXL_MAXMEM_CONSTANT
> extra external = LIBXL_PV_EXTRA_MEMORY
> static maximum = libxl_domain_build_info.max_memkb
> build start = libxl_domain_build_info.target_memkb
> + guest maximum = declared by a guest its maximum supported memory size
Another comma I think.
> libxl_domain_setmaxmem -> xen maximum
> - libxl_set_memory_target -> actual target
> + libxl_set_memory_target -> actual target & optionaly xen maximum
optionally again.
>
>
> ========================================================================= */
> 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.
> +
> +#### ~/memory/guest-max = ""|MEMKB [w]
> +
> +Declared by a guest its maximum supported memory size. Valid if numeric.
I think "Valid if numeric" is covered by the specification of MEMKB.
> #### ~/memory/target = MEMKB []
>
> The current balloon target for the domain. The balloon driver within
> -the guest is expected to make every effort to every effort use no more
> -than this amount of RAM.
> +the guest is expected to make every effort to use no more than this
> +amount of RAM. Guests whose actual allocation exceeds the target may
> +experience memory allocation failures.
>
> #### ~/memory/videoram = MEMKB [HVM,INTERNAL]
>
> diff --git a/tools/examples/xl.conf b/tools/examples/xl.conf
> index 9402c3f..9dbb1be 100644
> --- a/tools/examples/xl.conf
> +++ b/tools/examples/xl.conf
> @@ -5,6 +5,10 @@
> # starts with all the host's memory.
> #autoballoon="auto"
>
> +# xl mem-set by default will set a memory allocation target and enforce
> +# the maximum memory allocation for each domain
> +#mem_set_enforce_limit=1
> +
> # full path of the lockfile used by xl during domain creation
> #lockfile="/var/lock/xl"
>
> --
> 1.7.10.4
>
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |