[PATCH] balloon: document deflate on oom

["Michael S. Tsirkin" <mst@redhat.com>]

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 <mst@redhat.com>
---
 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