[src/trunk]: src/share/man/man4/man4.x86 So, hi again, balloon(4). Merge with...

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

details:   https://anonhg.NetBSD.org/src/rev/fcbec994c590
branches:  trunk
changeset: 764402:fcbec994c590
user:      jym <jym%NetBSD.org@localhost>
date:      Wed Apr 20 00:21:34 2011 +0000

description:
So, hi again, balloon(4). Merge with the current version:
- driver attaches to xenbus(4) (no compile time option anymore)
- max reservation hypercall is fixed
- sysctl(7) entries are now in KiB (like Xentools) rather than in number
of pages
- some more explanations.

diffstat:

 share/man/man4/man4.x86/balloon.4 |  239 +++++++++++++++++++++++++------------
 1 files changed, 158 insertions(+), 81 deletions(-)

diffs (275 lines):

diff -r 3e3b9207fce9 -r fcbec994c590 share/man/man4/man4.x86/balloon.4
--- a/share/man/man4/man4.x86/balloon.4 Wed Apr 20 00:04:54 2011 +0000
+++ b/share/man/man4/man4.x86/balloon.4 Wed Apr 20 00:21:34 2011 +0000
@@ -1,11 +1,10 @@
-.\"    $NetBSD: balloon.4,v 1.4 2011/01/14 10:01:03 jruoho Exp $
+.\"    $NetBSD: balloon.4,v 1.5 2011/04/20 00:21:34 jym Exp $
 .\"
-.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
-.\" by Cherry G. Mathew <cherry%zyx.in@localhost> and
-.\" Jean-Yves Migeon <jym%NetBSD.org@localhost>
+.\" 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
@@ -28,85 +27,152 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 14, 2011
+.Dd April 20, 2011
 .Dt BALLOON 4 xen
 .Os
 .Sh NAME
 .Nm balloon
-.Nd Xen hypervisor dynamic memory resize helper
+.Nd Xen memory balloon driver
 .Sh SYNOPSIS
-.Cd "options XEN_BALLOON"
+.Cd "balloon* at xenbus?"
 .Sh DESCRIPTION
-The Xen
-.Nm
-driver can be enabled to allow the Xen hypervisor to dynamically
-resize the amount of RAM a
-.Nx
-VM is allowed to use.
-This allows the hypervisor to manage RAM more
-efficiently, similar in spirit to how the
-.Nx
-kernel would manage RAM wrt processes, with
-.Xr uvm 9 .
-.Pp
 The
 .Nm
-driver negotiates domain VM memory allocation change requests from
-the Xen hypervisor, by reserving "pinned" memory for itself from the
-.Nx
-.Xr uvm 9
-subsystem.
+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
-There are two methods to notify the
+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
-driver of memory allocation change requests.
-.Bl -tag -width "Xr sysctl 3" -offset indent
-.It Xr xenbus 4
-In the xenbus method, the change notification originates outside the
-VM, presumable from the Hypervisor, and is communicated over the
-xenbus interface.
-.It Xr sysctl 3
-In the
-.Xr sysctl 3
-method, the change notification originates from within the VM.
-Two
-.Xr sysctl 7
-nodes are provided:
-.Bl -ohang -width kern.xen.balloon.current
-.It Va kern.xen.balloon.current
-This node is read-only and returns the number of memory pages
-currently allocated to the VM.
-.It Va kern.xen.balloon.target
-This node can be written to, and sets a new target memory reservation,
-in pages.
-Note that targets set this way from within the VM do not
-reflect in the hypervisor.
-This is therefore a less preferred way to use the
+is also available through
+.Xr sysctl 8
+under
+.Dq kern.xen.balloon
+(all values being in kilobytes):
+.Bl -tag indent -width xxxxxxx
+.It current
+(read-only) The current memory reservation of the domain.
+.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.
+.El
+.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 .
+.El
+.Sh BUGS
+There are a number of reasons why a domain may not attain the targetted
+memory reservation:
 .Nm
-.El
-.El
+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
-In either case, once a new allocation target is set, the balloon
-driver thread asynchronously attempts to reach this target in discrete
-steps.
-Every step, if it fails, is tried more than once.
-When the target is reached, the thread goes back to sleep, waiting
-for a new incoming target.
-If it is not reached, the target is updated to
-reflect the value after the last successful step.
-.Sh EXAMPLES
-.Bd -literal
-   # # Have a look at the current reservations.
-   # sysctl -a|grep balloon
-   kern.xen.balloon.current = 32512
-   kern.xen.balloon.target = 32512
-   #
-   # # Change the current target to 30000 kernel pages.
-   # sysctl -w kern.xen.balloon.target=30000
-   kern.xen.balloon.target: 32512 -\*[Gt] 30000
-   #
-.Ed
+Over expanding
+.Nm
+generates high kernel memory pressure.
+While the driver tries to stay as conservative as possible to avoid
+crashes, a very low memory reservation will lead to unwanted swap or even
+.Fn panic .
+.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 ,
 .Xr uvm 9
 .Rs
 .%A Carl A. Waldspurger
@@ -118,15 +184,26 @@
 .%U http://www.usenix.org/events/osdi02/tech/full_papers/waldspurger/waldspurger.pdf
 .Re
 .\"
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Nx 6.0 .
 .Sh AUTHORS
-.An Cherry G. Mathew Aq cherry%zyx.in@localhost
-.An Jean-Yves Migeon Aq jym%NetBSD.org@localhost
-.Sh CAVEATS
-VMs can be inadvertently
-.No crashed/ Ns Fn panic Ns ed
-by over expanding the
-balloon allocation, creating extreme OS memory pressure.
-.Sh BUGS
-.Fn xenmem_get_maxreservation
-is currently hard-coded to return nkmempages.
-This driver is still regarded as EXPERIMENTAL.
+.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.