[PATCH v5 1/2] virtio-blk: Add the control virtqueue

[Linlin Zhang <linlin.zhang@oss.qualcomm.com>]

From: linlzhan <linlin.zhang@oss.qualcomm.com>

Add VIRTIO_BLK_F_CTRL_VQ to advertise control virtqueue support.

Define the control virtqueue location, driver queue discovery,
and common control request buffer layout. This provides a
standard framework for block-device control commands.

Signed-off-by: linlzhan <linlin.zhang@oss.qualcomm.com>
---
 device-types/blk/description.tex        | 67 +++++++++++++++++++++++++
 device-types/blk/device-conformance.tex |  1 +
 device-types/blk/driver-conformance.tex |  1 +
 3 files changed, 69 insertions(+)

diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex
index 3b3a4e7..ed4c612 100644
--- a/device-types/blk/description.tex
+++ b/device-types/blk/description.tex
@@ -13,11 +13,16 @@ \subsection{Virtqueues}\label{sec:Device Types / Block Device / Virtqueues}
 \item[0] requestq1
 \item[\ldots]
 \item[N-1] requestqN
+\item[N] controlq, if VIRTIO_BLK_F_CTRL_VQ is negotiated
 \end{description}
 
  N=1 if VIRTIO_BLK_F_MQ is not negotiated, otherwise N is set by
  \field{num_queues}.
 
+If VIRTIO_BLK_F_CTRL_VQ is negotiated, the control virtqueue is appended
+after the request virtqueues. The control virtqueue is reserved for control
+requests defined by this specification.
+
 \subsection{Feature bits}\label{sec:Device Types / Block Device / Feature bits}
 
 \begin{description}
@@ -73,6 +78,8 @@ \subsection{Feature bits}\label{sec:Device Types / Block Device / Feature bits}
     VIRTIO_BLK_REQ_FLAG_OUT_FUA flag in the \field{flags} bitfield of the
     \field{virtio_blk_req} structure for VIRTIO_BLK_T_OUT requests.
 
+\item[VIRTIO_BLK_F_CTRL_VQ (20)] Device supports a control virtqueue.
+
 \end{description}
 
 \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Block Device / Feature bits / Legacy Interface: Feature bits}
@@ -274,6 +281,9 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
 \item If the VIRTIO_BLK_F_MQ feature is negotiated, \field{num_queues} field
     can be read to determine the number of queues.
 
+\item If the VIRTIO_BLK_F_CTRL_VQ feature is negotiated, the driver MUST
+    identify the control virtqueue as queue N, after all request virtqueues.
+
 \item If the VIRTIO_BLK_F_SECURE_ERASE feature is negotiated,
     \field{max_secure_erase_sectors} and \field{max_secure_erase_seg} can be read
     to determine the maximum secure erase sectors and maximum number of
@@ -1225,6 +1235,63 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 handles VIRTIO_BLK_T_ZONE_RESET request for the zone range specified in the
 VIRTIO_BLK_T_SECURE_ERASE request.
 
+\subsubsection{Control Virtqueue: Device Operation}\label{sec:Device Types / Block Device / Device Operation / Control Virtqueue: Device Operation}
+The driver uses the control virtqueue (if VIRTIO_BLK_F_CTRL_VQ is negotiated)
+to send control commands to the device.
+
+The device MUST return a status code as part of the control command result:
+either VIRTIO_BLK_S_OK for success, VIRTIO_BLK_S_IOERR for a device or driver
+error, or VIRTIO_BLK_S_UNSUPP for a request that is unsupported by the
+device.
+
+A control virtqueue request is composed of up to four separate buffers: a
+\field{type} field in an output buffer, an optional command-specific
+output buffer, an optional command-specific input buffer, and a
+\field{status} field in an input buffer. The \field{type} field and
+\field{status} field MUST each be in their own buffer, distinct from any
+command-specific buffer.
+
+All control commands are of the following form:
+\begin{lstlisting}
+struct virtio_blk_ctrl {
+        /* Device-readable part */
+
+        le32 type;
+
+        /* Command-specific, see below. */
+        u8 cmd_specific_out[cmd_specific_out_len];
+
+        /* Device-writable part */
+
+        /* Command-specific, see below. */
+        u8 cmd_specific_in[cmd_specific_in_len];
+
+        u8 status;
+};
+\end{lstlisting}
+
+\field{type} identifies the control command being requested.
+
+\field{status} uses the same status values as I/O requests (for
+example VIRTIO_BLK_S_OK, VIRTIO_BLK_S_IOERR, VIRTIO_BLK_S_UNSUPP).
+
+\field{cmd_specific_out_len} and \field{cmd_specific_in_len} depend on
+\field{type}, and are zero if the command specified by \field{type} has no
+command-specific output or input buffer respectively.
+
+\drivernormative{\paragraph}{Control Virtqueue}{Device Types / Block Device / Device Operation / Control Virtqueue: Device Operation}
+
+The driver MUST NOT set \field{type} to a value that does not correspond to
+a control command defined by this specification, or to a control command
+whose corresponding feature has not been negotiated with the device.
+
+\devicenormative{\paragraph}{Control Virtqueue}{Device Types / Block Device / Device Operation / Control Virtqueue: Device Operation}
+
+The device MUST complete a control virtqueue request with VIRTIO_BLK_S_UNSUPP
+status if it does not recognize the value of \field{type}, or if that
+control command corresponds to a feature that has not been negotiated with
+the driver.
+
 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}
 When using the legacy interface, transitional devices and drivers
 MUST format the fields in struct virtio_blk_req
diff --git a/device-types/blk/device-conformance.tex b/device-types/blk/device-conformance.tex
index b4fbc8b..55016e9 100644
--- a/device-types/blk/device-conformance.tex
+++ b/device-types/blk/device-conformance.tex
@@ -5,4 +5,5 @@
 \begin{itemize}
 \item \ref{devicenormative:Device Types / Block Device / Device Initialization}
 \item \ref{devicenormative:Device Types / Block Device / Device Operation}
+\item \ref{devicenormative:Device Types / Block Device / Device Operation / Control Virtqueue: Device Operation}
 \end{itemize}
diff --git a/device-types/blk/driver-conformance.tex b/device-types/blk/driver-conformance.tex
index 0f69866..e2d0753 100644
--- a/device-types/blk/driver-conformance.tex
+++ b/device-types/blk/driver-conformance.tex
@@ -5,4 +5,5 @@
 \begin{itemize}
 \item \ref{drivernormative:Device Types / Block Device / Device Initialization}
 \item \ref{drivernormative:Device Types / Block Device / Device Operation}
+\item \ref{drivernormative:Device Types / Block Device / Device Operation / Control Virtqueue: Device Operation}
 \end{itemize}
-- 
2.34.1