[PATCH virtio-spec] balloon: trannsitional device support

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

Virtio 1.0 doesn't include a modern balloon device.  At some point we'll likely
define an incompatible interface with a different ID and different
semantics.  But for now, it's not a big effort to support a transitional
balloon device: this has the advantage of supporting existing drivers,
transparently, as well as transports that don't allow mixing virtio 0 and
virtio 1 devices. And balloon is an easy device to test, so it's also useful
for people to test virtio core handling of transitional devices.

The only interface issue is with the stats buffer, which has misaligned
fields. We could leave it as is, but this sets a bad precedent that
others might copy by mistake.

As we need to change stats code to do byteswaps for virtio 1.0, it seems easy
to fix by prepending a 6 byte reserved field.  I also had to change config
structure field types from __le32 to __u32 to match other devices. This means
we need a couple of __force tags for legacy path but that seems minor.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 content.tex | 73 +++++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 56 insertions(+), 17 deletions(-)

diff --git a/content.tex b/content.tex
index 48d735d..d66785a 100644
--- a/content.tex
+++ b/content.tex
@@ -1023,7 +1023,7 @@ Transitional PCI Device ID  &  Virtio Device    \\
 \hline
 0x1001     &   block device     \\
 \hline
-0x1002     & memory ballooning (legacy)  \\
+0x1002     & memory ballooning (traditional)  \\
 \hline
 0x1003     &      console       \\
 \hline
@@ -2934,7 +2934,7 @@ Device ID  &  Virtio Device    \\
 \hline
 4          &  entropy source    \\
 \hline
-5          & memory ballooning (legacy)  \\
+5          & memory ballooning (traditional)  \\
 \hline
 6          &     ioMemory       \\
 \hline
@@ -4300,14 +4300,13 @@ how many random bytes were received.
 The device MUST place one or more random bytes into the buffer, but it
 MAY use less than the entire buffer length.
 
-\section{Legacy Interface: Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device}
+\section{Traditional Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device}
 
-This device is deprecated, and thus only exists as a legacy device
-illustrated here for reference.  The device number 13 is reserved for
-a new memory balloon interface which is expected in a future version
-of the standard.
+This is the traditional balloon device.  The device number 13 is
+reserved for a new memory balloon interface, with different
+semantics, which is expected in a future version of the standard.
 
-The virtio memory balloon device is a primitive device for
+The traditional virtio memory balloon device is a primitive device for
 managing guest memory: the device asks for a certain amount of
 memory, and the driver supplies it (or withdraws it, if the device
 has more than it asks for). This allows the guest to adapt to
@@ -4329,13 +4328,33 @@ guest memory statistics to the host.
 
 \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
 \begin{description}
-\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host MUST be told before
-    pages from the balloon are used.
+\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host has to be told before
+    pages from the balloon are used by guest.
 
 \item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
     memory statistics is present.
 \end{description}
 
+\drivernormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
+The driver SHOULD accept the VIRTIO_BALLOON_F_MUST_TELL_HOST
+feature if offered by the device.
+
+\devicenormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
+If the device offers the VIRTIO_BALLOON_F_MUST_TELL_HOST feature
+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 FEATURES_OK into
+\field{device status}.
+\subparagraph{Legacy Interface: Feature bits}\label{sec:Device
+Types / Memory Balloon Device / Feature bits / Legacy Interface:
+Feature bits}
+As the legacy interface does not have a way to gracefully report feature
+negotiation failure, when using the legacy interface,
+transitional devices MUST support guests which do not negotiate
+VIRTIO_BALLOON_F_MUST_TELL_HOST feature, and SHOULD
+allow guest to use memory before notifying host if
+VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
+
 \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
   Both fields of this configuration
   are always available.
@@ -4347,24 +4366,29 @@ struct virtio_balloon_config {
 };
 \end{lstlisting}
 
-Note that these fields are always little endian, despite convention
-that legacy device fields are guest endian.
+\subparagraph{Legacy Interface: Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device
+configuration layout / Legacy Interface: Device configuration layout}
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_balloon_config
+according to the little-endian format.
 
 \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Device / Device Initialization}
 
+The device initialization process is outlined below:
+
 \begin{enumerate}
 \item The inflate and deflate virtqueues are identified.
 
 \item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated:
   \begin{enumerate}
   \item Identify the stats virtqueue.
-
-  \item Add one empty buffer to the stats virtqueue and notify the
-    device.
+  \item Add one empty buffer to the stats virtqueue.
+  \item DRIVER_OK is set: device operation begins.
+  \item Notify the device about the stats virtqueue buffer.
   \end{enumerate}
 \end{enumerate}
 
-Device operation begins immediately.
+\drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
 
 \subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation}
 
@@ -4460,12 +4484,27 @@ struct virtio_balloon_stat {
 #define VIRTIO_BALLOON_S_MINFLT   3
 #define VIRTIO_BALLOON_S_MEMFREE  4
 #define VIRTIO_BALLOON_S_MEMTOT   5
+        le16 tag;
+        u8 reserved[6];
+        le64 val;
+};
+\end{lstlisting}
+
+\paragraph{Legacy Interface: Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics}
+
+When using the legacy interface, transitional devices and drivers
+MUST use the following alternative format for struct
+virtio_balloon_stat:
+
+\begin{lstlisting}
+struct virtio_balloon_stat {
         u16 tag;
         u64 val;
 } __attribute__((packed));
 \end{lstlisting}
 
-\paragraph{Legacy Interface: Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics}
+The same tag values are used.
+
 When using the legacy interface, transitional devices and drivers
 MUST format the fields in struct virtio_balloon_stat
 according to the native endian of the guest rather than
-- 
MST