BALLOON(4)            NetBSD/xen Kernel Interfaces Manual           BALLOON(4)

NAME
     balloon -- Xen memory balloon driver

SYNOPSIS
     balloon* at xenbus?

DESCRIPTION
     The balloon driver supports the memory ballooning operations offered in
     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''.

     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 mem-
     ory, except that the pages are not available to domain anymore.

     Any domain is free to request memory from balloon up to the maximum value
     set by the host's administrator through the mem-max command of xm(1).
     Alternatively, the host's administrator is free to request to a particu-
     lar domain to give some memory back.  This command requires the targeted
     domain's cooperation and requires balloon support within it.  This can be
     done through the mem-set command of xm(1).  Alternatively, one can con-
     trol the ballooning directly by writing under the ``memory/target'' node
     inside Xenstore.  This entry controls the target memory reservation of a
     given domain, indicated in kilobytes (KiB).

     An interface to control balloon is also available through sysctl(8) under
     ``machdep.xen.balloon'' (all values being in kilobytes):

     current  (read-only) The current memory reservation of the domain.

     min      (read-write) The minimum reservation value acceptable by the
              domain's 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.

     max      (read-only) The maximum reservation accessible to a domain.  Its
              value can only be changed by the dom0's administrator, through
              the mem-max command of xm(1).

     target   (read-write) The target reservation of the domain.  This entry
              serves the same purpose as the ``memory/target'' entry in Xen-
              store.  This controls the targeted 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.

DIAGNOSTICS
     WARNING: balloon could not reach target %zu (current %zu)  balloon failed
     to reach the target reservation.  This is typically due to a target set
     too low; the kernel prevented memory exhaustion by refusing further allo-
     cation.

     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.

     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 manage-
     ment sub-system dynamically, balloon will limit reservation up to the
     maximum value it can handle.

ERRORS
     When setting the minimum threshold or target reservation entries through
     ``machdep.xen.balloon'', the following errors can be returned:

     [EPERM]            The value passed is beyond limits.  The new value is
                        either too low (``min'' is below driver's safeguard
                        value, or ``target'' is below minimum value), or too
                        high (``target'' is above maximum value).

SEE ALSO
     xm(1), xenbus(4), uvm(9)

     Carl A. Waldspurger, "Memory Resource Management in VMware ESX Server",
     Proceedings of the 5th Symposium on Operating Systems Design and
     Implementation, USENIX Association,
     http://www.usenix.org/events/osdi02/tech/full_papers/waldspurger/waldspurger.pdf,
     December 9-11, 2002.

HISTORY
     The balloon driver first appeared in NetBSD 6.0.

AUTHORS
     The balloon driver was written by Cherry G. Mathew <cherry@NetBSD.org>
     and Jean-Yves Migeon <jym@NetBSD.org>.

BUGS
     There are a number of reasons why a domain may not attain the targeted
     memory reservation: balloon can be empty and cannot be collapsed further,
     domain may not have enough free memory pages (due to memory fragmenta-
     tion, memory exhaustion, ...) so it cannot give enough back to balloon.

     Currently, the virtual memory sub-system of NetBSD 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 point-
     less, as new memory pages cannot be consumed by the memory management
     sub-system.

     Over expanding balloon generates high kernel memory pressure.  While the
     driver tries to stay as conservative as possible to avoid crashes, a very
     low memory reservation will lead to unwanted swap or even panic().

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 NetBSD kernel zeroes all
     pages before relinquishing them to balloon but this may not be the case
     for other operating systems.

NetBSD 6.0                       July 30, 2011                      NetBSD 6.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen