[PATCH] balloon: document deflate on oom

Document the new option, and also clarify behaviour without it.  In particular, I noticed that actual field is not the actual number of pages in the balloon as driver might do inflate followed by deflate.  Signed-off-by: Michael S. Tsirkin <> ---  content.tex
25 +++++++++++++++++++++++--  1 file changed, 23 insertions(+), 2 deletions(-)  diff --git a/content.tex b/content.tex index 036f38c..98d5486 100644 --- a/content.tex +++ b/content.tex @@ -4390,6 +4390,9 @@ guest memory statistics to the host.
item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
memory statistics is present. +item[VIRTIO_BALLOON_F_DEFLATE_ON_OOM (2) ] Deflate balloon on +
OOM. +  end{description}
drivernormative{subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits} @@ -4489,10 +4492,25 @@ requests by using the descriptor.
drivernormative{subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}  The driver SHOULD supply pages to the balloon when field{num_pages} is -greater than field{actual}. +greater than the actual number of pages in the balloon.
The driver MAY use pages from the balloon when field{num_pages} is -less than field{actual}. +less than the actual number of pages in the balloon. + +The driver MAY supply pages to the balloon when field{num_pages} is +greater than or equal to the actual number of pages in the balloon. + +If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the +driver MUST NOT use pages from the balloon when field{num_pages} +is less than or equal to the actual number of pages in the +balloon. + +If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the +driver MAY use pages from the balloon when field{num_pages} +is less than or equal to the actual number of pages in the +balloon if this is required for system stability +(e.g. if memory is required by applications running within + the guest).
The driver MUST use the deflateq to inform the device of pages that it  wants to use from the balloon. @@ -4517,6 +4535,9 @@ request.  The driver MUST update field{actual} after changing the number  of pages in the balloon.
+The driver MAY update field{actual} once after multiple +inflate and deflate operations. +  devicenormative{subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
The device MAY modify the contents of a page in the balloon

--
MST