[PATCH] virtio-rng: add a control queue

[Laurent Vivier <lvivier@redhat.com>]

A control queue is needed to send command to ask the device to
release the request buffers if it cannot provide data.

Changes:

  5.4.2 Virtqueues
  0 requestq
  1 controlq
  controlq only exists if VIRTIO_RNG_F_CTRL_VQ set.

  5.4.3 Feature bits
  VIRTIO_RNG_F_CTRL_VQ (0)
  Device has a control queue

  5.4.5 Device Initialization
  Identify and initialize the request virtqueue.
  If the VIRTIO_RNG_F_CTRL_VQ feature bit is negotiated,
  identify the control virtqueue.

  5.4.6.3 Control Virtqueue
  The driver uses the control virtqueue (if VIRTIO_RNG_F_CTRL_VQ is negotiated)
  to send commands to control the device.
  All commands are of the following form:
  struct virtio_rng_ctrl_hdr {
         u8 cmd;
  };

  5.4.6.3.1 Request Virtqueue Flushing
  When the device is not able to provide enough entropy to the driver,
  the driver can be stuck. And for instance, it cannot be removed from the
  system to switch to another one. The flush command allows the driver to ask
  the device to release all the buffers sent to the device and to unlock the
  driver.
  #define VIRTIO_RNG_CMD_FLUSH 0

Bug-Link: https://github.com/oasis-tcs/virtio-spec/issues/83
Signed-off-by: Laurent Vivier <lvivier@redhat.com>
---
 content.tex | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/content.tex b/content.tex
index 91735e3eb018..e37078650be8 100644
--- a/content.tex
+++ b/content.tex
@@ -4952,10 +4952,16 @@ \subsection{Device ID}\label{sec:Device Types / Entropy Device / Device ID}
 \subsection{Virtqueues}\label{sec:Device Types / Entropy Device / Virtqueues}
 \begin{description}
 \item[0] requestq
+\item[1] controlq
 \end{description}
 
+controlq only exists if VIRTIO_RNG_F_CTRL_VQ set.
+
 \subsection{Feature bits}\label{sec:Device Types / Entropy Device / Feature bits}
-  None currently defined
+
+\begin{description}
+\item[VIRTIO_RNG_F_CTRL_VQ (0)] Device has a control queue
+\end{description}
 
 \subsection{Device configuration layout}\label{sec:Device Types / Entropy Device / Device configuration layout}
   None currently defined.
@@ -4963,7 +4969,11 @@ \subsection{Device configuration layout}\label{sec:Device Types / Entropy Device
 \subsection{Device Initialization}\label{sec:Device Types / Entropy Device / Device Initialization}
 
 \begin{enumerate}
-\item The virtqueue is initialized
+\item Identify and initialize the request virtqueue.
+
+\item If the VIRTIO_RNG_F_CTRL_VQ feature bit is negotiated,
+  identify the control virtqueue.
+
 \end{enumerate}
 
 \subsection{Device Operation}\label{sec:Device Types / Entropy Device / Device Operation}
@@ -4984,6 +4994,30 @@ \subsection{Device Operation}\label{sec:Device Types / Entropy Device / Device O
 The device MUST place one or more random bytes into the buffer, but it
 MAY use less than the entire buffer length.
 
+\subsubsection{Control Virtqueue}\label{sec:Device Types / Entropy Device / Device Operation / Control Virtqueue}
+
+The driver uses the control virtqueue (if VIRTIO_RNG_F_CTRL_VQ is
+negotiated) to send commands to control the device.
+
+All commands are of the following form:
+
+\begin{lstlisting}
+struct virtio_rng_ctrl_hdr {
+       u8 cmd;
+};
+\end{lstlisting}
+
+\paragraph{Request Virtqueue Flushing}\label{sec:Device Types / Entropy Device / Device Operation / Control Virtqueue / Request Virtqueue Flushing}
+
+When the device is not able to provide enough entropy to the driver, the driver can be stuck.
+And for instance, it cannot be removed from the system to switch to another one.
+The flush command allows the driver to ask the device to release all the buffers sent to the
+device and to unlock the driver.
+
+\begin{lstlisting}
+#define VIRTIO_RNG_CMD_FLUSH 0
+\end{lstlisting}
+
 \section{Traditional Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device}
 
 This is the traditional balloon device.  The device number 13 is
-- 
2.26.2