[src/trunk]: src/share/man/man4 man page for balloon driver from Cherry

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

details:   https://anonhg.NetBSD.org/src/rev/46ef7adfb44e
branches:  trunk
changeset: 756203:46ef7adfb44e
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Jul 08 20:00:24 2010 +0000

description:
man page for balloon driver from Cherry

diffstat:

 share/man/man4/Makefile           |    4 +-
 share/man/man4/man4.x86/Makefile  |    6 +
 share/man/man4/man4.x86/balloon.4 |  121 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 129 insertions(+), 2 deletions(-)

diffs (153 lines):

diff -r 265755107c43 -r 46ef7adfb44e share/man/man4/Makefile
--- a/share/man/man4/Makefile   Thu Jul 08 19:20:16 2010 +0000
+++ b/share/man/man4/Makefile   Thu Jul 08 20:00:24 2010 +0000
@@ -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>
diff -r 265755107c43 -r 46ef7adfb44e share/man/man4/man4.x86/Makefile
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/man4.x86/Makefile  Thu Jul 08 20:00:24 2010 +0000
@@ -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>
diff -r 265755107c43 -r 46ef7adfb44e share/man/man4/man4.x86/balloon.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/man4.x86/balloon.4 Thu Jul 08 20:00:24 2010 +0000
@@ -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 <cherry%zyx.in@localhost> and
+.\" 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 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 cherry%zyx.in@localhost
+.An Jean-Yves Migeon Aq jym%NetBSD.org@localhost
+.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.