1.\" $NetBSD: balloon.4,v 1.4 2011/01/14 10:01:03 jruoho Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Cherry G. Mathew <cherry@zyx.in> and 8.\" Jean-Yves Migeon <jym@NetBSD.org> 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd January 14, 2011 32.Dt BALLOON 4 xen 33.Os 34.Sh NAME 35.Nm balloon 36.Nd Xen hypervisor dynamic memory resize helper 37.Sh SYNOPSIS 38.Cd "options XEN_BALLOON" 39.Sh DESCRIPTION 40The Xen 41.Nm 42driver can be enabled to allow the Xen hypervisor to dynamically 43resize the amount of RAM a 44.Nx 45VM is allowed to use. 46This allows the hypervisor to manage RAM more 47efficiently, similar in spirit to how the 48.Nx 49kernel would manage RAM wrt processes, with 50.Xr uvm 9 . 51.Pp 52The 53.Nm 54driver negotiates domain VM memory allocation change requests from 55the Xen hypervisor, by reserving "pinned" memory for itself from the 56.Nx 57.Xr uvm 9 58subsystem. 59.Pp 60There are two methods to notify the 61.Nm 62driver of memory allocation change requests. 63.Bl -tag -width "Xr sysctl 3" -offset indent 64.It Xr xenbus 4 65In the xenbus method, the change notification originates outside the 66VM, presumable from the Hypervisor, and is communicated over the 67xenbus interface. 68.It Xr sysctl 3 69In the 70.Xr sysctl 3 71method, the change notification originates from within the VM. 72Two 73.Xr sysctl 7 74nodes are provided: 75.Bl -ohang -width kern.xen.balloon.current 76.It Va kern.xen.balloon.current 77This node is read-only and returns the number of memory pages 78currently allocated to the VM. 79.It Va kern.xen.balloon.target 80This node can be written to, and sets a new target memory reservation, 81in pages. 82Note that targets set this way from within the VM do not 83reflect in the hypervisor. 84This is therefore a less preferred way to use the 85.Nm 86.El 87.El 88.Pp 89In either case, once a new allocation target is set, the balloon 90driver thread asynchronously attempts to reach this target in discrete 91steps. 92Every step, if it fails, is tried more than once. 93When the target is reached, the thread goes back to sleep, waiting 94for a new incoming target. 95If it is not reached, the target is updated to 96reflect the value after the last successful step. 97.Sh EXAMPLES 98.Bd -literal 99 # # Have a look at the current reservations. 100 # sysctl -a|grep balloon 101 kern.xen.balloon.current = 32512 102 kern.xen.balloon.target = 32512 103 # 104 # # Change the current target to 30000 kernel pages. 105 # sysctl -w kern.xen.balloon.target=30000 106 kern.xen.balloon.target: 32512 -\*[Gt] 30000 107 # 108.Ed 109.Sh SEE ALSO 110.Xr uvm 9 111.Rs 112.%A Carl A. Waldspurger 113.%T "Memory Resource Management in VMware ESX Server" 114.%I USENIX Association 115.%B Proceedings of the 5th Symposium on \ 116Operating Systems Design and Implementation 117.%D December 9-11, 2002 118.%U http://www.usenix.org/events/osdi02/tech/full_papers/waldspurger/waldspurger.pdf 119.Re 120.\" 121.Sh AUTHORS 122.An Cherry G. Mathew Aq cherry@zyx.in 123.An Jean-Yves Migeon Aq jym@NetBSD.org 124.Sh CAVEATS 125VMs can be inadvertently 126.No crashed/ Ns Fn panic Ns ed 127by over expanding the 128balloon allocation, creating extreme OS memory pressure. 129.Sh BUGS 130.Fn xenmem_get_maxreservation 131is currently hard-coded to return nkmempages. 132This driver is still regarded as EXPERIMENTAL. 133