[PATCH 2/2] virtio-balloon: add a responsive host feature

[David Stevens <stevensd@chromium.org>]

Add a feature bit that the device can use to indicate that it will
monitor and respond to memory pressure in the guest. This flag allows
the driver to assume that the device will provide memory when necessary
and will not permanently remove memory from the guest via inflating the
balloon.

Signed-off-by: David Stevens <stevensd@chromium.org>
---
 content.tex | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/content.tex b/content.tex
index 3aeb319d31a7..dcb2b71a2b6a 100644
--- a/content.tex
+++ b/content.tex
@@ -5451,6 +5451,8 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
     page reporting. A virtqueue for reporting free guest memory is present.
 \item[ VIRTIO_BALLOON_F_EVENT_VQ(6) ] A virtqueue for sending events from
     the driver to the device.
+\item[ VIRTIO_BALLOON_F_RESPONSIVE_HOST(7) ] The device will respond to memory
+    pressure in the guest by deflating the balloon.
 
 \end{description}
 
@@ -5471,6 +5473,14 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
 bit, and if the driver did not accept this feature bit, the
 device MAY signal failure by failing to set FEATURES_OK
 \field{device status} bit when the driver writes it.
+
+If the device offers the VIRTIO_BALLOON_F_RESPONSIVE_HOST feature
+bit, it MUST also offer the VIRTIO_BALLOON_F_STATS_VQ and
+VIRTIO_BALLOON_F_EVENT_VQ feature bits. Although the device may not
+always be able to immediately respond to memory pressure in the
+guest, the device SHOULD be able to fully deflate the balloon if
+memory pressure persists in the guest.
+
 \subparagraph{Legacy Interface: Feature bits}\label{sec:Device
 Types / Memory Balloon Device / Feature bits / Legacy Interface:
 Feature bits}
@@ -6087,8 +6097,14 @@ \subsubsection{Events}\label{sec:Device Types / Memory Balloon Device / Device O
 
 \devicenormative{\paragraph}{Events}{Device Types / Memory Balloon Device / Device Operation / Events}
 
-When the device receives a VIRTIO_BALLOON_EVENT_OOM event, it SHOULD deflate
-the balloon by \field{data} pages before acknowledging the event.
+If VIRTIO_BALLOON_F_RESPONSIVE_HOST has not been negotiated, when the device
+receives a VIRTIO_BALLOON_EVENT_OOM event, it SHOULD deflate the balloon by
+\field{data} pages before acknowledging the event.
+
+If VIRTIO_BALLOON_F_RESPONSIVE_HOST has been negotiated, when the device
+receives a VIRTIO_BALLOON_EVENT_OOM event, it MUST deflate the balloon
+by \field{data} pages before acknowledging the event, unless doing so
+would jeopardize stability of the host.
 
 \section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
 
-- 
2.35.0.rc0.227.g00780c9af4-goog