[src/trunk]: src/share/man/man4 Sigh, removing balloon(4) there was already o...

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

details:   https://anonhg.NetBSD.org/src/rev/3e3b9207fce9
branches:  trunk
changeset: 764401:3e3b9207fce9
user:      jym <jym%NetBSD.org@localhost>
date:      Wed Apr 20 00:04:54 2011 +0000

description:
Sigh, removing balloon(4) there was already one living under x86.
Not marking the entry in set lists as obsolete, the man page stayed
in there for approx. 5min.

(apologies for the noise)

diffstat:

 share/man/man4/balloon.4 |  190 -----------------------------------------------
 1 files changed, 0 insertions(+), 190 deletions(-)

diffs (194 lines):

diff -r 7ea9357e068e -r 3e3b9207fce9 share/man/man4/balloon.4
--- a/share/man/man4/balloon.4  Tue Apr 19 23:54:38 2011 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,190 +0,0 @@
-.\"    $NetBSD: balloon.4,v 1.1 2011/04/19 23:54:38 jym Exp $
-.\"
-.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
-.\" All rights reserved.
-.\"
-.\" This code is derived from software contributed to The NetBSD Foundation
-.\" by 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 April 20, 2011
-.Dt BALLOON 4 xen
-.Os
-.Sh NAME
-.Nm balloon
-.Nd Xen memory balloon driver
-.Sh SYNOPSIS
-.Cd "balloon* at xenbus?"
-.Sh DESCRIPTION
-The
-.Nm
-driver supports the memory ballooning operations offered in
-.Tn Xen
-environments.
-It allows shrinking or extending a domain's available memory by passing
-pages between different domains.
-At any time, the total memory available to a domain is called the
-``reservation''.
-.Pp
-Pages are moved via the use of the balloon, a reserved quantity
-of memory available to all domains that can be freely deflated (or inflated)
-at a domain's will.
-Deflating balloon means that pages are moved out from it, and bound to
-domain's virtual memory.
-Respectively, inflating balloon indicates that pages are moved out of
-domain's memory and pushed inside balloon.
-This is similar to a dynamic allocation of wired physical memory, except
-that the pages are not available to domain anymore.
-.Pp
-Any domain is free to request memory from
-.Nm
-up to the maximum value set by the host's administrator through the
-.Ic mem-max
-command of
-.Xr xm 1 .
-Alternatively, the host's administrator is free to request to a particular
-domain to give some memory back.
-This command requires the targetted domain's cooperation and requires
-.Nm balloon
-support within it.
-This can be done through the
-.Ic mem-set
-command of
-.Xr xm 1 .
-Alternatively, one can control the ballooning directly by writing
-under the
-.Dq memory/target
-node inside Xenstore.
-This entry controls the target memory reservation
-of a given domain, indicated in kilobytes (KiB).
-.Pp
-An interface to control
-.Nm
-is also available through
-.Xr sysctl 8
-under
-.Dq kern.xen.balloon
-(all values being in kilobytes):
-.Bl -tag indent -width xxxxxxx
-.It min
-(read-write) The minimum reservation value acceptable by the domain's
-.Nm balloon
-driver.
-Any request that would require domain to reduce its reservation below
-this threshold will be refused by the driver.
-This can be used by a domain's administrator to control the number of memory
-pages that will be kept available to domain.
-.It max
-(read-only) The maximum reservation accessible to a domain.
-Its value can only be changed by the dom0's administrator, through the
-.Ic mem-max
-command of
-.Xr xm 1 .
-.It target
-(read-write) The target reservation of the domain.
-This entry serves the same purpose as the
-.Dq memory/target
-entry in Xenstore.
-This controls the targetted number of pages that the domain should have.
-Note that this is only a target, and may not be achieved for a variety of
-reasons.
-.It current
-(read-only) The current memory reservation of the domain.
-.Sh ERRORS
-When setting the minimum threshold or target reservation entries through
-.Dq kern.xen.balloon ,
-the following errors can be returned:
-.Bl -tag -width Er
-.It Bq Er EPERM
-The value passed is beyond limits.
-The new value is either too low
-.Po Dq min
-is below driver's safeguard value, or
-.Dq target
-is below minimum value
-.Pc ,
-or too high
-.Po Dq target
-is above maximum value
-.Pc .
-.Sh BUGS
-There are a number of reasons why a domain may not attain the targetted
-memory reservation:
-.Nm
-can be empty and cannot be collapsed further, domain
-may not have enough free memory pages (due to memory fragmentation,
-memory exhaustion, ...) so it cannot give enough back to
-.Nm .
-.Pp
-Currently, the virtual memory sub-system of
-.Nx
-is not capable of ``hot-plugging'' new memory pages into place.
-This means that increasing a domain's memory reservation above
-its initial maximum value is pointless, as new memory pages
-cannot be consumed by the memory management sub-system.
-.Pp
-.Sh DIAGNOSTICS
-.Bl -diag
-.It "WARNING: balloon could not reach target %zu (current %zu)"
-.Nm
-failed to reach the target reservation.
-This is typically due to a target set too low; the kernel prevented
-memory exhaustion by refusing further allocation.
-.It "increase reservation incomplete: was %zu, returned %d"
-The hypervisor only gave a partial set of memory pages to domain.
-This happens when host's memory consumption is high, and hypervisor
-is unable to give enough free pages back to domain.
-.It "memory 'hot-plug' unsupported - clipping reservation %zu => %zu pages."
-An attempt was made by domain to get more memory than initially obtained
-during boot.
-As physical memory pages cannot be added to memory management sub-system
-dynamically,
-.Nm
-will limit reservation up to the maximum value it can handle.
-.El
-.Sh SEE ALSO
-.Xr xm 1 ,
-.Xr xenbus 4
-.Sh HISTORY
-The
-.Nm
-driver first appeared in
-.Nx 6.0 .
-.Sh AUTHORS
-.An -nosplit
-The
-.Nm
-driver was written by
-.An Cherry G. Mathew Aq cherry%NetBSD.org@localhost
-and
-.An Jean-Yves Migeon Aq jym%NetBSD.org@localhost .
-.Sh SECURITY CONSIDERATIONS
-Ballooning involves moving pages between different domains.
-This includes their content, which can lead to information leak.
-If you are running domains of different sensitivities on the same host,
-consider disabling the use of ballooning altogether.
-The
-.Nx
-kernel zeroes all pages before relinquishing them to
-.Nm
-but this may not be the case for other operating systems.