1cfc6e6e8SSebastien Boeuf# Balloon 2cfc6e6e8SSebastien Boeuf 3cfc6e6e8SSebastien BoeufCloud Hypervisor implements a balloon device based on the VIRTIO specification. 4cfc6e6e8SSebastien BoeufIts main purpose is to provide the host a way to reclaim memory by controlling 5cfc6e6e8SSebastien Boeufthe amount of memory visible to the guest. But it also provides some interesting 6cfc6e6e8SSebastien Boeuffeatures related to guest memory management. 7cfc6e6e8SSebastien Boeuf 8cfc6e6e8SSebastien Boeuf## Parameters 9cfc6e6e8SSebastien Boeuf 10cfc6e6e8SSebastien Boeuf`BalloonConfig` (known as `--balloon` from the CLI perspective) contains the 11cfc6e6e8SSebastien Boeuflist of parameters available for the balloon device. 12cfc6e6e8SSebastien Boeuf 13cfc6e6e8SSebastien Boeuf```rust 14cfc6e6e8SSebastien Boeufstruct BalloonConfig { 15cfc6e6e8SSebastien Boeuf pub size: u64, 16cfc6e6e8SSebastien Boeuf pub deflate_on_oom: bool, 17cfc6e6e8SSebastien Boeuf pub free_page_reporting: bool, 18cfc6e6e8SSebastien Boeuf} 19cfc6e6e8SSebastien Boeuf``` 20cfc6e6e8SSebastien Boeuf 21cfc6e6e8SSebastien Boeuf``` 22cfc6e6e8SSebastien Boeuf--balloon <balloon> Balloon parameters "size=<balloon_size>,deflate_on_oom=on|off,free_page_reporting=on|off" 23cfc6e6e8SSebastien Boeuf``` 24cfc6e6e8SSebastien Boeuf 25cfc6e6e8SSebastien Boeuf### `size` 26cfc6e6e8SSebastien Boeuf 27cfc6e6e8SSebastien BoeufSize of the balloon device. It is subtracted from the VM's total size. For 28cfc6e6e8SSebastien Boeufinstance, if creating a VM with 4GiB of RAM, along with a balloon of 1GiB, the 29cfc6e6e8SSebastien Boeufguest will be able to use 3GiB of accessible memory. The guest sees all the RAM 30cfc6e6e8SSebastien Boeufand unless it is balloon enlightened is entitled to all of it. 31cfc6e6e8SSebastien Boeuf 32cfc6e6e8SSebastien BoeufThis parameter is mandatory. 33cfc6e6e8SSebastien Boeuf 34cfc6e6e8SSebastien BoeufValue is an unsigned integer of 64 bits corresponding to the balloon size in 35cfc6e6e8SSebastien Boeufbytes. 36cfc6e6e8SSebastien Boeuf 37cfc6e6e8SSebastien Boeuf_Example_ 38cfc6e6e8SSebastien Boeuf 39cfc6e6e8SSebastien Boeuf``` 40cfc6e6e8SSebastien Boeuf--balloon size=1G 41cfc6e6e8SSebastien Boeuf``` 42cfc6e6e8SSebastien Boeuf 43cfc6e6e8SSebastien Boeuf### `deflate_on_oom` 44cfc6e6e8SSebastien Boeuf 45cfc6e6e8SSebastien BoeufAllow the guest to deflate the balloon if running Out Of Memory (OOM). Assuming 46cfc6e6e8SSebastien Boeufthe balloon size is greater than 0, this means the guest is allowed to reduce 47cfc6e6e8SSebastien Boeufthe balloon size all the way down to 0 if this can help recover from the OOM 48cfc6e6e8SSebastien Boeufevent. 49cfc6e6e8SSebastien Boeuf 50cfc6e6e8SSebastien BoeufThis parameter is optional. 51cfc6e6e8SSebastien Boeuf 52cfc6e6e8SSebastien BoeufValue is a boolean set to `off` by default. 53cfc6e6e8SSebastien Boeuf 54cfc6e6e8SSebastien Boeuf_Example_ 55cfc6e6e8SSebastien Boeuf 56cfc6e6e8SSebastien Boeuf``` 57*beeb2f51SDario Nieuwenhuis--balloon size=2G,deflate_on_oom=on 58cfc6e6e8SSebastien Boeuf``` 59cfc6e6e8SSebastien Boeuf 60cfc6e6e8SSebastien Boeuf### `free_page_reporting` 61cfc6e6e8SSebastien Boeuf 62cfc6e6e8SSebastien BoeufAllow the guest to report lists of free pages. This feature doesn't require the 63cfc6e6e8SSebastien Boeufballoon to be of any specific size as it doesn't impact the balloon size. The 64cfc6e6e8SSebastien Boeufguest can let the VMM know about pages that are free after they have been used. 65cfc6e6e8SSebastien BoeufBased on this information, the VMM can advise the host that it doesn't need 66cfc6e6e8SSebastien Boeufthese pages anymore. 67cfc6e6e8SSebastien Boeuf 68cfc6e6e8SSebastien BoeufThis parameter is optional. 69cfc6e6e8SSebastien Boeuf 70cfc6e6e8SSebastien BoeufValue is a boolean set to `off` by default. 71cfc6e6e8SSebastien Boeuf 72cfc6e6e8SSebastien Boeuf_Example_ 73cfc6e6e8SSebastien Boeuf 74cfc6e6e8SSebastien Boeuf``` 75*beeb2f51SDario Nieuwenhuis--balloon size=0,free_page_reporting=on 76cfc6e6e8SSebastien Boeuf``` 77