Module Name: src
Committed By: christos
Date: Thu Jul 8 20:00:24 UTC 2010
Modified Files:
src/share/man/man4: Makefile
Added Files:
src/share/man/man4/man4.x86: Makefile balloon.4
Log Message:
man page for balloon driver from Cherry
To generate a diff of this commit:
cvs rdiff -u -r1.521 -r1.522 src/share/man/man4/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man4/man4.x86/Makefile \
src/share/man/man4/man4.x86/balloon.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/Makefile
diff -u src/share/man/man4/Makefile:1.521 src/share/man/man4/Makefile:1.522
--- src/share/man/man4/Makefile:1.521 Sun Jul 4 11:21:58 2010
+++ src/share/man/man4/Makefile Thu Jul 8 16:00:24 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.521 2010/07/04 15:21:58 tsutsui Exp $
+# $NetBSD: Makefile,v 1.522 2010/07/08 20:00:24 christos Exp $
# @(#)Makefile 8.1 (Berkeley) 6/18/93
MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -213,7 +213,7 @@
man4.hp300 man4.hp700 man4.hpcarm man4.hpcmips man4.hpcsh man4.i386 \
man4.mac68k man4.macppc man4.mvme68k man4.pmax man4.prep \
man4.sgimips man4.sparc man4.sparc64 man4.sun2 man4.sun3 man4.vax \
- man4.x68k
+ man4.x68k man4.x86
.include <bsd.man.mk>
.include <bsd.subdir.mk>
Added files:
Index: src/share/man/man4/man4.x86/Makefile
diff -u /dev/null src/share/man/man4/man4.x86/Makefile:1.1
--- /dev/null Thu Jul 8 16:00:24 2010
+++ src/share/man/man4/man4.x86/Makefile Thu Jul 8 16:00:24 2010
@@ -0,0 +1,6 @@
+# $NetBSD: Makefile,v 1.1 2010/07/08 20:00:24 christos Exp $
+
+MAN= balloon.4
+MANSUBDIR=/x86
+
+.include <bsd.man.mk>
Index: src/share/man/man4/man4.x86/balloon.4
diff -u /dev/null src/share/man/man4/man4.x86/balloon.4:1.1
--- /dev/null Thu Jul 8 16:00:24 2010
+++ src/share/man/man4/man4.x86/balloon.4 Thu Jul 8 16:00:24 2010
@@ -0,0 +1,121 @@
+.\" $NetBSD: balloon.4,v 1.1 2010/07/08 20:00:24 christos Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Cherry G. Mathew <che...@zyx.in> and
+.\" 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 July 06, 2010
+.Dt BALLOON 4 xen
+.Os
+.Sh NAME
+.Nm balloon
+.Nd Xen hypervisor dynamic memory resize helper
+.Sh SYNOPSIS
+.Cd "options XEN_BALLOON"
+.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
+NetBSD
+.Xr uvm 9
+subsystem.
+.Pp
+There are two methods to notify the
+.Nm
+driver of memory allocation change requests.
+.Bl -tag -width "Xr sysctl 3" -offset indent
+.It xenbus
+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
+.Nm
+.El
+.El
+.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 -> 30000
+ #
+.Ed
+.Sh SEE ALSO
+.Xr uvm 9
+.Rs
+.%A Carl A. Waldspurger
+.%T Memory Resource Management in VMware ESX Server
+.%U http://www.usenix.org/events/osdi02/tech/waldspurger/waldspurger_html/node6.html
+.Re
+.\"
+.Sh AUTHORS
+.An Cherry G. Mathew Aq che...@zyx.in
+.An Jean-Yves Migeon Aq j...@netbsd.org
+.Sh CAVEATS
+VMs can be inadvertently crashed/panic()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.
