docs: Add balloon documentation

Document the reason why someone might need to use the balloon device and
detail the different parameters associated with it.

Fixes #3807

Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>

docs/balloon.md

@@ -0,0 +1,76 @@
+# 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.
+
+```rust
+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
+```