Module Name: src Committed By: jym Date: Tue Apr 19 23:54:38 UTC 2011
Added Files: src/share/man/man4: balloon.4 Log Message: Please welcome balloon(4), the Xen memory balloon man page. To generate a diff of this commit: cvs rdiff -u -r0 -r1.1 src/share/man/man4/balloon.4 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Added files: Index: src/share/man/man4/balloon.4 diff -u /dev/null src/share/man/man4/balloon.4:1.1 --- /dev/null Tue Apr 19 23:54:38 2011 +++ src/share/man/man4/balloon.4 Tue Apr 19 23:54:38 2011 @@ -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 <j...@netbsd.org>. +.\" +.\" 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 che...@netbsd.org +and +.An Jean-Yves Migeon Aq j...@netbsd.org . +.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.