[src/trunk]: src/share/man/man4 Please welcome balloon(4), the Xen memory bal...

[jym <jym%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7ea9357e068e
branches:  trunk
changeset: 764400:7ea9357e068e
user:      jym <jym%NetBSD.org@localhost>
date:      Tue Apr 19 23:54:38 2011 +0000

description:
Please welcome balloon(4), the Xen memory balloon man page.

diffstat:

 share/man/man4/balloon.4 |  190 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 190 insertions(+), 0 deletions(-)

diffs (194 lines):

diff -r 9c25930eabe6 -r 7ea9357e068e share/man/man4/balloon.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/balloon.4  Tue Apr 19 23:54:38 2011 +0000
@@ -0,0 +1,190 @@
+.\"    $NetBSD: balloon.4,v 1.1 2011/04/19 23:54:38 jym Exp $
+.\"
+.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jean-Yves Migeon <jym%NetBSD.org@localhost>.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd April 20, 2011
+.Dt BALLOON 4 xen
+.Os
+.Sh NAME
+.Nm balloon
+.Nd Xen memory balloon driver
+.Sh SYNOPSIS
+.Cd "balloon* at xenbus?"
+.Sh DESCRIPTION
+The
+.Nm
+driver supports the memory ballooning operations offered in
+.Tn Xen
+environments.
+It allows shrinking or extending a domain's available memory by passing
+pages between different domains.
+At any time, the total memory available to a domain is called the
+``reservation''.
+.Pp
+Pages are moved via the use of the balloon, a reserved quantity
+of memory available to all domains that can be freely deflated (or inflated)
+at a domain's will.
+Deflating balloon means that pages are moved out from it, and bound to
+domain's virtual memory.
+Respectively, inflating balloon indicates that pages are moved out of
+domain's memory and pushed inside balloon.
+This is similar to a dynamic allocation of wired physical memory, except
+that the pages are not available to domain anymore.
+.Pp
+Any domain is free to request memory from
+.Nm
+up to the maximum value set by the host's administrator through the
+.Ic mem-max
+command of
+.Xr xm 1 .
+Alternatively, the host's administrator is free to request to a particular
+domain to give some memory back.
+This command requires the targetted domain's cooperation and requires
+.Nm balloon
+support within it.
+This can be done through the
+.Ic mem-set
+command of
+.Xr xm 1 .
+Alternatively, one can control the ballooning directly by writing
+under the
+.Dq memory/target
+node inside Xenstore.
+This entry controls the target memory reservation
+of a given domain, indicated in kilobytes (KiB).
+.Pp
+An interface to control
+.Nm
+is also available through
+.Xr sysctl 8
+under
+.Dq kern.xen.balloon
+(all values being in kilobytes):
+.Bl -tag indent -width xxxxxxx
+.It min
+(read-write) The minimum reservation value acceptable by the domain's
+.Nm balloon
+driver.
+Any request that would require domain to reduce its reservation below
+this threshold will be refused by the driver.
+This can be used by a domain's administrator to control the number of memory
+pages that will be kept available to domain.
+.It max
+(read-only) The maximum reservation accessible to a domain.
+Its value can only be changed by the dom0's administrator, through the
+.Ic mem-max
+command of
+.Xr xm 1 .
+.It target
+(read-write) The target reservation of the domain.
+This entry serves the same purpose as the
+.Dq memory/target
+entry in Xenstore.
+This controls the targetted number of pages that the domain should have.
+Note that this is only a target, and may not be achieved for a variety of
+reasons.
+.It current
+(read-only) The current memory reservation of the domain.
+.Sh ERRORS
+When setting the minimum threshold or target reservation entries through
+.Dq kern.xen.balloon ,
+the following errors can be returned:
+.Bl -tag -width Er
+.It Bq Er EPERM
+The value passed is beyond limits.
+The new value is either too low
+.Po Dq min
+is below driver's safeguard value, or
+.Dq target
+is below minimum value
+.Pc ,
+or too high
+.Po Dq target
+is above maximum value
+.Pc .
+.Sh BUGS
+There are a number of reasons why a domain may not attain the targetted
+memory reservation:
+.Nm
+can be empty and cannot be collapsed further, domain
+may not have enough free memory pages (due to memory fragmentation,
+memory exhaustion, ...) so it cannot give enough back to
+.Nm .
+.Pp
+Currently, the virtual memory sub-system of
+.Nx
+is not capable of ``hot-plugging'' new memory pages into place.
+This means that increasing a domain's memory reservation above
+its initial maximum value is pointless, as new memory pages
+cannot be consumed by the memory management sub-system.
+.Pp
+.Sh DIAGNOSTICS
+.Bl -diag
+.It "WARNING: balloon could not reach target %zu (current %zu)"
+.Nm
+failed to reach the target reservation.
+This is typically due to a target set too low; the kernel prevented
+memory exhaustion by refusing further allocation.
+.It "increase reservation incomplete: was %zu, returned %d"
+The hypervisor only gave a partial set of memory pages to domain.
+This happens when host's memory consumption is high, and hypervisor
+is unable to give enough free pages back to domain.
+.It "memory 'hot-plug' unsupported - clipping reservation %zu => %zu pages."
+An attempt was made by domain to get more memory than initially obtained
+during boot.
+As physical memory pages cannot be added to memory management sub-system
+dynamically,
+.Nm
+will limit reservation up to the maximum value it can handle.
+.El
+.Sh SEE ALSO
+.Xr xm 1 ,
+.Xr xenbus 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Nx 6.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was written by
+.An Cherry G. Mathew Aq cherry%NetBSD.org@localhost
+and
+.An Jean-Yves Migeon Aq jym%NetBSD.org@localhost .
+.Sh SECURITY CONSIDERATIONS
+Ballooning involves moving pages between different domains.
+This includes their content, which can lead to information leak.
+If you are running domains of different sensitivities on the same host,
+consider disabling the use of ballooning altogether.
+The
+.Nx
+kernel zeroes all pages before relinquishing them to
+.Nm
+but this may not be the case for other operating systems.