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