[virtio-comment] [PATCH v3] virtio-rng: add a control queue

[virtio-comment] [PATCH v3] virtio-rng: add a control queue

[Laurent Vivier]

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.4 Device Requirements: Control Virtqueue
  If VIRTIO_RNG_F_CTRL_VQ is negotiated, the device MUST implement the
  flush command.
  Any other value of cmd MUST be ignored by the device.

  5.4.6.5 Request Virtqueue Flushing
  When the device is not able to provide enough entropy to the driver, the
  driver may be stuck waiting for the device returning buffers, and cannot
  be removed to switch to another one. The flush command allows the driver
  to ask the device to release all the buffers sent to the device. This
  allows the driver to release resources allocated to receive data from
  the device.
  #define VIRTIO_RNG_CMD_FLUSH 0

  5.4.6.5.1 Device Requirements: Request Virtqueue Flushing
  When the driver sends a flush request, the device MUST release all
  outstanding buffers.

Bug-Link: https://github.com/oasis-tcs/virtio-spec/issues/83
Signed-off-by: Laurent Vivier <lvivier@redhat.com>
---

Notes:
    v3: Add devicenormative references in conformance part
        Move "Request Virtqueue Flushing" from \paragraph to \subsubsection
        to be behind "Control Virtqueue" and not behind
        "Device Requirements: Control Virtqueue"
    
    v2: Add devicenormative for the Control Virtqueue
        Add devicenormative for the Request Virtqueue Flushing
        Reword paragraph Request Virtqueue Flushing

 conformance.tex |  2 ++
 content.tex     | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/conformance.tex b/conformance.tex
index b6fdec090383..0c3b2f2283b4 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -321,6 +321,8 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 
 \begin{itemize}
 \item \ref{devicenormative:Device Types / Entropy Device / Device Operation}
+\item \ref{devicenormative:Device Types / Entropy Device / Device Operation / Control Virtqueue}
+\item \ref{devicenormative:Device Types / Entropy Device / Device Operation / Control Virtqueue / Request Virtqueue Flushing}
 \end{itemize}
 
 \conformance{\subsection}{Traditional Memory Balloon Device Conformance}\label{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance}
diff --git a/content.tex b/content.tex
index 91735e3eb018..e2e9f6cca381 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,39 @@ \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}
+
+\devicenormative{\subsubsection}{Control Virtqueue}{Device Types / Entropy Device / Device Operation / Control Virtqueue}
+
+If VIRTIO_RNG_F_CTRL_VQ is negotiated, the device MUST implement the flush command.
+
+Any other value of cmd MUST be ignored by the device.
+
+\subsubsection{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 may be stuck waiting for the device returning buffers, and cannot be removed to switch to another one.
+The flush command allows the driver to ask the device to release all the buffers sent to the
+device. This allows the driver to release resources allocated to receive data from the device.
+
+\begin{lstlisting}
+#define VIRTIO_RNG_CMD_FLUSH 0
+\end{lstlisting}
+
+\devicenormative{\paragraph}{Request Virtqueue Flushing}{Device Types / Entropy Device / Device Operation / Control Virtqueue / Request Virtqueue Flushing}
+
+When the driver sends a flush request, the device MUST release all outstanding buffers.
+
 \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


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v3] virtio-rng: add a control queue

[Cornelia Huck]

On Tue,  4 Aug 2020 17:41:27 +0200
Laurent Vivier <lvivier@redhat.com> wrote:

> 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.4 Device Requirements: Control Virtqueue
>   If VIRTIO_RNG_F_CTRL_VQ is negotiated, the device MUST implement the
>   flush command.
>   Any other value of cmd MUST be ignored by the device.
> 
>   5.4.6.5 Request Virtqueue Flushing
>   When the device is not able to provide enough entropy to the driver, the
>   driver may be stuck waiting for the device returning buffers, and cannot
>   be removed to switch to another one. The flush command allows the driver
>   to ask the device to release all the buffers sent to the device. This
>   allows the driver to release resources allocated to receive data from
>   the device.
>   #define VIRTIO_RNG_CMD_FLUSH 0
> 
>   5.4.6.5.1 Device Requirements: Request Virtqueue Flushing
>   When the driver sends a flush request, the device MUST release all
>   outstanding buffers.
> 
> Bug-Link: https://github.com/oasis-tcs/virtio-spec/issues/83
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>
> ---
> 
> Notes:
>     v3: Add devicenormative references in conformance part
>         Move "Request Virtqueue Flushing" from \paragraph to \subsubsection
>         to be behind "Control Virtqueue" and not behind
>         "Device Requirements: Control Virtqueue"

There are different ways to put the conformance statements (and what
should be a paragraph vs a subsubsection), and your layout seems
reasonable, avoiding nesting too deep.

>     
>     v2: Add devicenormative for the Control Virtqueue
>         Add devicenormative for the Request Virtqueue Flushing
>         Reword paragraph Request Virtqueue Flushing
> 
>  conformance.tex |  2 ++
>  content.tex     | 47 +++++++++++++++++++++++++++++++++++++++++++++--
>  2 files changed, 47 insertions(+), 2 deletions(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] [PATCH v3] virtio-rng: add a control queue

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1359 bytes --]

On Tue, Aug 04, 2020 at 05:41:27PM +0200, Laurent Vivier wrote:

Why can't the driver reset the device so that the buffers are no longer
owned by the device?

> +\subsubsection{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 may be stuck waiting for the device returning buffers, and cannot be removed to switch to another one.

s/returning/to return/

"cannot be removed to switch to another one"? Is this referring to
hot unplug?

> +The flush command allows the driver to ask the device to release all the buffers sent to the
> +device. This allows the driver to release resources allocated to receive data from the device.
> +
> +\begin{lstlisting}
> +#define VIRTIO_RNG_CMD_FLUSH 0
> +\end{lstlisting}
> +
> +\devicenormative{\paragraph}{Request Virtqueue Flushing}{Device Types / Entropy Device / Device Operation / Control Virtqueue / Request Virtqueue Flushing}
> +
> +When the driver sends a flush request, the device MUST release all outstanding buffers.

"releasing" a buffer is not term defined by the VIRTIO. I guess the full
explanation is:

  When the driver sends a flush request, the device MUST use all
  available requestq buffers and set the used length to 0.

?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]