1.\" $NetBSD: balloon.4,v 1.11 2014/03/18 18:20:40 riastradh Exp $ 2.\" 3.\" Copyright (c) 2011 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jean-Yves Migeon <jym@NetBSD.org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd July 30, 2011 31.Dt BALLOON 4 xen 32.Os 33.Sh NAME 34.Nm balloon 35.Nd Xen memory balloon driver 36.Sh SYNOPSIS 37.Cd "balloon* at xenbus?" 38.Sh DESCRIPTION 39The 40.Nm 41driver supports the memory ballooning operations offered in 42.Tn Xen 43environments. 44It allows shrinking or extending a domain's available memory by passing 45pages between different domains. 46At any time, the total memory available to a domain is called the 47``reservation''. 48.Pp 49Pages are moved via the use of the balloon, a reserved quantity 50of memory available to all domains that can be freely deflated (or inflated) 51at a domain's will. 52Deflating balloon means that pages are moved out from it, and bound to 53domain's virtual memory. 54Respectively, inflating balloon indicates that pages are moved out of 55domain's memory and pushed inside balloon. 56This is similar to a dynamic allocation of wired physical memory, except 57that the pages are not available to domain anymore. 58.Pp 59Any domain is free to request memory from 60.Nm 61up to the maximum value set by the host's administrator through the 62.Ic mem-max 63command of 64.Xr xm 1 . 65Alternatively, the host's administrator is free to request to a particular 66domain to give some memory back. 67This command requires the targeted domain's cooperation and requires 68.Nm balloon 69support within it. 70This can be done through the 71.Ic mem-set 72command of 73.Xr xm 1 . 74Alternatively, one can control the ballooning directly by writing 75under the 76.Dq memory/target 77node inside Xenstore. 78This entry controls the target memory reservation 79of a given domain, indicated in kilobytes (KiB). 80.Pp 81An interface to control 82.Nm 83is also available through 84.Xr sysctl 8 85under 86.Dq machdep.xen.balloon 87(all values being in kilobytes): 88.Bl -tag -width xxxxxxx 89.It current 90(read-only) The current memory reservation of the domain. 91.It min 92(read-write) The minimum reservation value acceptable by the domain's 93.Nm balloon 94driver. 95Any request that would require domain to reduce its reservation below 96this threshold will be refused by the driver. 97This can be used by a domain's administrator to control the number of memory 98pages that will be kept available to domain. 99.It max 100(read-only) The maximum reservation accessible to a domain. 101Its value can only be changed by the dom0's administrator, through the 102.Ic mem-max 103command of 104.Xr xm 1 . 105.It target 106(read-write) The target reservation of the domain. 107This entry serves the same purpose as the 108.Dq memory/target 109entry in Xenstore. 110This controls the targeted number of pages that the domain should have. 111Note that this is only a target, and may not be achieved for a variety of 112reasons. 113.El 114.Sh DIAGNOSTICS 115.Bl -diag 116.It "WARNING: balloon could not reach target %zu (current %zu)" 117.Nm 118failed to reach the target reservation. 119This is typically due to a target set too low; the kernel prevented 120memory exhaustion by refusing further allocation. 121.It "increase reservation incomplete: was %zu, returned %d" 122The hypervisor only gave a partial set of memory pages to domain. 123This happens when host's memory consumption is high, and hypervisor 124is unable to give enough free pages back to domain. 125.It "memory 'hot-plug' unsupported - clipping reservation %zu => %zu pages." 126An attempt was made by domain to get more memory than initially obtained 127during boot. 128As physical memory pages cannot be added to memory management sub-system 129dynamically, 130.Nm 131will limit reservation up to the maximum value it can handle. 132.El 133.Sh ERRORS 134When setting the minimum threshold or target reservation entries through 135.Dq machdep.xen.balloon , 136the following errors can be returned: 137.Bl -tag -width Er 138.It Bq Er EPERM 139The value passed is beyond limits. 140The new value is either too low 141.Po Dq min 142is below driver's safeguard value, or 143.Dq target 144is below minimum value 145.Pc , 146or too high 147.Po Dq target 148is above maximum value 149.Pc . 150.El 151.Sh SEE ALSO 152.Xr xm 1 , 153.Xr xenbus 4 , 154.Xr uvm 9 155.Rs 156.%A Carl A. Waldspurger 157.%T "Memory Resource Management in VMware ESX Server" 158.%I USENIX Association 159.%B Proceedings of the 5th Symposium on \ 160Operating Systems Design and Implementation 161.%D December 9-11, 2002 162.%U http://www.usenix.org/events/osdi02/tech/full_papers/waldspurger/waldspurger.pdf 163.Re 164.\" 165.Sh HISTORY 166The 167.Nm 168driver first appeared in 169.Nx 6.0 . 170.Sh AUTHORS 171.An -nosplit 172The 173.Nm 174driver was written by 175.An Cherry G. Mathew Aq Mt cherry@NetBSD.org 176and 177.An Jean-Yves Migeon Aq Mt jym@NetBSD.org . 178.Sh BUGS 179There are a number of reasons why a domain may not attain the targeted 180memory reservation: 181.Nm 182can be empty and cannot be collapsed further, domain 183may not have enough free memory pages (due to memory fragmentation, 184memory exhaustion, ...) so it cannot give enough back to 185.Nm . 186.Pp 187Currently, the virtual memory sub-system of 188.Nx 189is not capable of ``hot-plugging'' new memory pages into place. 190This means that increasing a domain's memory reservation above 191its initial maximum value is pointless, as new memory pages 192cannot be consumed by the memory management sub-system. 193.Pp 194Over expanding 195.Nm 196generates high kernel memory pressure. 197While the driver tries to stay as conservative as possible to avoid 198crashes, a very low memory reservation will lead to unwanted swap or even 199.Fn panic . 200.Sh SECURITY CONSIDERATIONS 201Ballooning involves moving pages between different domains. 202This includes their content, which can lead to information leak. 203If you are running domains of different sensitivities on the same host, 204consider disabling the use of ballooning altogether. 205The 206.Nx 207kernel zeroes all pages before relinquishing them to 208.Nm 209but this may not be the case for other operating systems. 210