[PATCH 1/2] virtio-balloon: add an event queue

[David Stevens <stevensd@chromium.org>]

Add an event queue to the balloon to allow the driver to send events to
the device, which allows the device to be more responsive to the memory
needs of the guest.

There are two defined events. The first event is an out of memory event.
This event provides a way for the guest to handle out of memory events
on a system where the host does not support deflate-on-oom. The second
event is an out of puff event, which the guest can send when it fails to
allocate memory while trying to inflate the balloon. This serves as an
indication to the device that the driver may not be able to inflate the
balloon in a timely manner.

Signed-off-by: David Stevens <stevensd@chromium.org>
---
 conformance.tex |  2 ++
 content.tex     | 59 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/conformance.tex b/conformance.tex
index 42f853762ebe..5e0baa5ae7df 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -181,6 +181,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
 \item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Page Poison}
 \item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Events}
 \end{itemize}
 
 \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
@@ -440,6 +441,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
 \item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Page Poison}
 \item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Events}
 \end{itemize}
 
 \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
diff --git a/content.tex b/content.tex
index 32de6685c50b..3aeb319d31a7 100644
--- a/content.tex
+++ b/content.tex
@@ -5420,6 +5420,7 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
 \item[2] statsq
 \item[3] free_page_vq
 \item[4] reporting_vq
+\item[5] event_vq
 \end{description}
 
   statsq only exists if VIRTIO_BALLOON_F_STATS_VQ is set.
@@ -5428,6 +5429,8 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
 
   reporting_vq only exists if VIRTIO_BALLOON_F_PAGE_REPORTING is set.
 
+  event_vq only exists if VIRTIO_BALLOON_F_EVENT_VQ is set.
+
 \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
 \begin{description}
 \item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host has to be told before
@@ -5446,6 +5449,8 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
     Configuration field \field{poison_val} is valid.
 \item[ VIRTIO_BALLOON_F_PAGE_REPORTING(5) ] The device has support for free
     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.
 
 \end{description}
 
@@ -5529,6 +5534,8 @@ \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Devic
   notify the device about the stats virtqueue buffer.
 \item If the VIRTIO_BALLOON_F_PAGE_REPORTING feature bit is negotiated, then
   begin reporting free pages to the device.
+\item If the VIRTIO_BALLOON_F_EVENT_VQ feature bit is negotiated, then
+  begin reporting events to the device.
 \end{enumerate}
 
 \subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation}
@@ -6031,6 +6038,58 @@ \subsubsection{Free Page Reporting}\label{sec:Device Types / Memory Balloon Devi
 MUST NOT modify the the content of a reported page to a value other than
 \field{poison_val}.
 
+\subsubsection{Events}\label{sec:Device Types / Memory Balloon Device / Device Operation / Events}
+
+The events virtqueue allows the driver to signal events to the
+device.
+
+\begin{lstlisting}
+struct virtio_balloon_event {
+        u32 type;
+        u32 data;
+};
+
+#define VIRTIO_BALLOON_EVENT_OOM        1
+#define VIRTIO_BALLOON_EVENT_OOPUFF     2
+\end{lstlisting}
+
+The \field{type} determines how to interpret the event. The following
+events are defined:
+
+\begin{itemize}
+\item Out of memory
+\begin{lstlisting}
+#define VIRTIO_BALLOON_EVENT_OOM        1
+\end{lstlisting}
+The driver has encountered a situation in which using pages from the balloon
+is necessary for system stability (e.g. if memory is required by applications
+running within the guest). The \field{data} value indicates how many pages
+the driver requires to maintain system stability.
+\item Out of puff
+\begin{lstlisting}
+#define VIRTIO_BALLOON_EVENT_OOPUFF     2
+\end{lstlisting}
+The driver has encountered an allocation failure when trying to inflate
+the balloon. The \field{data} value is unused. This event serves as a signal
+that the balloon may not be able to inflate in a timely manner.
+\end{itemize}
+
+\drivernormative{\paragraph}{Events}{Device Types / Memory Balloon Device / Device Operation / Events}
+
+The driver MUST update \field{actual} with any allocated pages before
+sending a VIRTIO_BALLOON_EVENT_OOPUFF event.
+
+The driver SHOULD wait for the device to acknowledge the event
+before trying to further inflate or deflate the balloon.
+
+If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the driver
+SHOULD send an OOM event before using pages from the balloon.
+
+\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.
+
 \section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
 
 The virtio SCSI host device groups together one or more virtual
-- 
2.35.0.rc0.227.g00780c9af4-goog