[PATCH v3 1/2] virtio: introduce virtqueue reset as basic facility

[Xuan Zhuo <xuanzhuo@linux.alibaba.com>]

This patch allows the driver to reset a queue individually.

This is very common on general network equipment. By disabling a queue,
you can quickly reclaim the buffer currently on the queue. If necessary,
we can reinitialize the queue separately.

For example, when virtio-net implements support for AF_XDP, we need to
disable a queue to release all the original buffers when AF_XDP setup.
And quickly release all the AF_XDP buffers that have been placed in the
queue when AF_XDP exits.

Signed-off-by: Xuan Zhuo <xuanzhuo@linux.alibaba.com>
---
 content.tex | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/content.tex b/content.tex
index 37c45d3..603b1f1 100644
--- a/content.tex
+++ b/content.tex
@@ -407,6 +407,43 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo
 types. It is RECOMMENDED that devices generate version 4
 UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}.
 
+\section{Virtqueue Reset}\label{sec:Virtqueues / Virtqueue Reset}
+
+When VIRTIO_F_RING_RESET is negotiated, the driver can reset a virtqueue
+individually. The way to reset the virtqueue is transport specific.
+
+Virtqueue reset is divided into two parts. The driver MUST reset stop a queue
+first, and then re-enable the queue. The re-enable part is optional.
+
+\devicenormative{\subsection}{Virtqueue Reset Stop}{Virtqueues / Virtqueue Reset}
+The device MUST not executes the requests from this virtqueue, and notify the
+driver.
+
+And the device MUST initialize all states of this virtqueue, including the
+available state and the used state.
+
+\drivernormative{\subsection}{Virtqueue Reset Stop}{Virtqueues / Virtqueue Reset}
+
+The driver MUST first notify the device and confirm that we have successfully
+stopped a queue.
+
+Then the driver can release all the resources occupied by this virtqueue.
+And reinitialize the state of this queue.
+
+\devicenormative{\subsection}{Virtqueue Reset Re-enable}{Virtqueues / Virtqueue Reset}
+
+This process is the same as the initialization process of a single queue during
+the initialization of the entire device. After the device has accepted all the
+configuration from the driver, it will start working under the notification of the
+driver.
+
+\drivernormative{\subsection}{Virtqueue Reset Re-enable}{Virtqueues / Virtqueue Reset}
+
+This process is the same as the initialization process of a single queue during
+the entire device initialization process. After the driver allocates resources
+and completes the configuration of the queue status, it notifies the device to
+start working.
+
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
 
 We start with an overview of device initialization, then expand on the
@@ -6673,6 +6710,10 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
   transport specific.
   For more details about driver notifications over PCI see \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Available Buffer Notifications}.
 
+  \item[VIRTIO_F_RING_RESET(40)] This feature indicates
+  that the driver can reset a queue individually.
+  See \ref{sec:Virtqueues / Virtqueue Reset}.
+
 \end{description}
 
 \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
-- 
2.31.0