cloud-hypervisor/docs/balloon.md

Balloon

Cloud Hypervisor implements a balloon device based on the VIRTIO specification. Its main purpose is to provide the host a way to reclaim memory by controlling the amount of memory visible to the guest. But it also provides some interesting features related to guest memory management.

Parameters

BalloonConfig (known as --balloon from the CLI perspective) contains the list of parameters available for the balloon device.

struct BalloonConfig {
    pub size: u64,
    pub deflate_on_oom: bool,
    pub free_page_reporting: bool,
}

--balloon <balloon>	Balloon parameters "size=<balloon_size>,deflate_on_oom=on|off,free_page_reporting=on|off"

size

Size of the balloon device. It is subtracted from the VM's total size. For instance, if creating a VM with 4GiB of RAM, along with a balloon of 1GiB, the guest will be able to use 3GiB of accessible memory. The guest sees all the RAM and unless it is balloon enlightened is entitled to all of it.

This parameter is mandatory.

Value is an unsigned integer of 64 bits corresponding to the balloon size in bytes.

Example

--balloon size=1G

deflate_on_oom

Allow the guest to deflate the balloon if running Out Of Memory (OOM). Assuming the balloon size is greater than 0, this means the guest is allowed to reduce the balloon size all the way down to 0 if this can help recover from the OOM event.

This parameter is optional.

Value is a boolean set to off by default.

Example

--ballloon size=2G,deflate_on_oom=on

free_page_reporting

Allow the guest to report lists of free pages. This feature doesn't require the balloon to be of any specific size as it doesn't impact the balloon size. The guest can let the VMM know about pages that are free after they have been used. Based on this information, the VMM can advise the host that it doesn't need these pages anymore.

This parameter is optional.

Value is a boolean set to off by default.

Example

--ballloon size=0,free_page_reporting=on