Sat Jul 30 09:39:20 2011 UTC ()
Reflect my change for Xen sysctl(7) nodes:
kern.xen.balloon -> machdep.xen.balloon.


(jym)
diff -r1.6 -r1.7 src/share/man/man4/man4.x86/balloon.4
cvs diff -r1.6 -r1.7 src/share/man/man4/man4.x86/balloon.4 (switch to unified diff)

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