[virtio-dev] [PATCH v5 0/3] virtio: introduce VIRTIO_F_RING_RESET for reset queue

[virtio-dev] [PATCH v5 0/3] virtio: introduce VIRTIO_F_RING_RESET for reset queue

[Xuan Zhuo]

Hi All:

This is a new version to support VIRTIO_F_RING_RESET. The feautre
extends the basic facility to allow the driver to reset a virtqueue.
This main motivation is to support the reset function of the queue of the
network device.

Please review.

v5:
   It is defined in the transports that the device can modify the default
   value after reset, and the driver can use a different configuration to
   re-enable the device.

v4:
   Cornelia Huck helped me more. Thanks.
   MMIO support this.

Thanks

Xuan Zhuo (3):
  virtio: introduce virtqueue reset as basic facility
  virtio: pci support virtqueue reset
  virtio: mmio support virtqueue reset

 content.tex | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 110 insertions(+), 1 deletion(-)

--
2.31.0


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] [PATCH v5 1/3] virtio: introduce virtqueue reset as basic facility

[Xuan Zhuo]

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 | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/content.tex b/content.tex
index 37c45d3..dd095f4 100644
--- a/content.tex
+++ b/content.tex
@@ -350,6 +350,48 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
 Every driver and device supports either the Packed or the Split
 Virtqueue format, or both.
 
+\subsection{Virtqueue Reset}\label{sec:Basic Facilities of a Virtio Device / 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 first resets a queue and
+can afterwards optionally re-enable it.
+
+\subsubsection{Virtqueue Reset}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset}
+
+\devicenormative{\paragraph}{Virtqueue Reset}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset}
+
+After a queue has been reset by the driver, the device MUST NOT execute
+any requests from that virtqueue, or notify the driver for it.
+
+The device MUST reset any state of a virtqueue to be reset to the default state,
+including the available state and the used state.
+
+\drivernormative{\paragraph}{Virtqueue Reset}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset}
+
+After the driver tells the device to reset a queue, the driver MUST verify that
+the queue has actually been reset.
+
+After the queue has been successfully reset, the driver MAY release any
+resource associated with that virtqueue.
+
+\subsubsection{Virtqueue Re-enable}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Re-enable}
+
+This process is the same as the initialization process of a single queue during
+the initialization of the entire device.
+
+\devicenormative{\paragraph}{Virtqueue Re-enable}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Re-enable}
+
+The device MUST observe any queue configuration that may have been
+changed by the driver, like the maximum queue size.
+
+\drivernormative{\paragraph}{Virtqueue Re-enable}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Re-enable}
+
+When re-enabling a queue, the driver MUST configure the queue resources
+as during initial virtqueue discovery, but optionally with different
+parameters.
+
 \input{split-ring.tex}
 
 \input{packed-ring.tex}
@@ -6673,6 +6715,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:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}.
+
 \end{description}
 
 \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
-- 
2.31.0


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [virtio-dev] [PATCH v5 1/3] virtio: introduce virtqueue reset as basic facility

[Cornelia Huck]

On Fri, Oct 01 2021, Xuan Zhuo <xuanzhuo@linux.alibaba.com> wrote:

> 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 | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
>
> diff --git a/content.tex b/content.tex
> index 37c45d3..dd095f4 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -350,6 +350,48 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
>  Every driver and device supports either the Packed or the Split
>  Virtqueue format, or both.
>  
> +\subsection{Virtqueue Reset}\label{sec:Basic Facilities of a Virtio Device / 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 first resets a queue and
> +can afterwards optionally re-enable it.
> +
> +\subsubsection{Virtqueue Reset}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset}
> +
> +\devicenormative{\paragraph}{Virtqueue Reset}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset}
> +
> +After a queue has been reset by the driver, the device MUST NOT execute
> +any requests from that virtqueue, or notify the driver for it.
> +
> +The device MUST reset any state of a virtqueue to be reset to the default state,

This sentence looks a bit strange; probably should be

"The device MUST reset any state of a virtqueue to the default state",
or
"The device MUST cause any state of a virtqueue to be reset to the
default state"

> +including the available state and the used state.

Otherwise, the generic description now looks good to me.


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[PATCH v5 2/3] virtio: pci support virtqueue reset

[Xuan Zhuo]

PCI support virtqueue reset.

virtio_pci_common_cfg add "queue_reset" to support virtqueue reset.
The driver uses this to selectively reset the queue.

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

diff --git a/content.tex b/content.tex
index dd095f4..d014420 100644
--- a/content.tex
+++ b/content.tex
@@ -901,6 +901,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         le64 queue_driver;              /* read-write */
         le64 queue_device;              /* read-write */
         le16 queue_notify_data;         /* read-only for driver */
+        le16 queue_reset;               /* read-write */
 };
 \end{lstlisting}
 
@@ -980,6 +981,12 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
         may benefit from providing another value, for example an internal virtqueue
         identifier, or an internal offset related to the virtqueue number.
         \end{note}
+
+\item[\field{queue_reset}]
+        The driver uses this to selectively reset the queue.
+        This field exists only if VIRTIO_F_RING_RESET has been
+        negotiated. (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
+
 \end{description}
 
 \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
@@ -1021,6 +1028,22 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
 
 The device MUST present a 0 in \field{queue_enable} on reset.
 
+If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
+\field{queue_enable} after the driver has reset the virtqueue via
+\field{queue_reset}.
+
+If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
+\field{queue_reset} on reset.
+
+If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
+\field{queue_reset} after the virtqueue is enabled with \field{queue_enable}.
+
+The device MUST reset the queue when 1 is written to \field{queue_reset}, and
+present a 1 in \field{queue_reset} after the queue has been reset, until the
+driver re-enables the queue via \field{queue_enable} or the device is reset.
+The device MAY present different default values after queue reset.
+(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
+
 The device MUST present a 0 in \field{queue_size} if the virtqueue
 corresponding to the current \field{queue_select} is unavailable.
 
@@ -1045,6 +1068,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
 
 The driver MUST NOT write a 0 to \field{queue_enable}.
 
+If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
+\field{queue_reset} to reset the queue, it MUST verify that the queue
+has been reset by reading back \field{queue_reset} and ensuring that it
+is 1. The driver MAY re-enable the queue by writing a 1 to
+\field{queue_enable} after ensuring that the other virtqueue fields have
+been set up correctly. The driver MAY set driver-writeable queue configuration
+values to different values than those that were used before the queue reset.
+(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
+
 \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 
 The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG
-- 
2.31.0

Re: [PATCH v5 2/3] virtio: pci support virtqueue reset

[Jason Wang]

On Fri, Oct 1, 2021 at 1:50 AM Xuan Zhuo <xuanzhuo@linux.alibaba.com> wrote:
>
> PCI support virtqueue reset.
>
> virtio_pci_common_cfg add "queue_reset" to support virtqueue reset.
> The driver uses this to selectively reset the queue.
>
> Signed-off-by: Xuan Zhuo <xuanzhuo@linux.alibaba.com>
> ---
>  content.tex | 32 ++++++++++++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
>
> diff --git a/content.tex b/content.tex
> index dd095f4..d014420 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -901,6 +901,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
>          le64 queue_driver;              /* read-write */
>          le64 queue_device;              /* read-write */
>          le16 queue_notify_data;         /* read-only for driver */
> +        le16 queue_reset;               /* read-write */
>  };
>  \end{lstlisting}
>
> @@ -980,6 +981,12 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
>          may benefit from providing another value, for example an internal virtqueue
>          identifier, or an internal offset related to the virtqueue number.
>          \end{note}
> +
> +\item[\field{queue_reset}]
> +        The driver uses this to selectively reset the queue.
> +        This field exists only if VIRTIO_F_RING_RESET has been
> +        negotiated. (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> +
>  \end{description}
>
>  \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
> @@ -1021,6 +1028,22 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
>
>  The device MUST present a 0 in \field{queue_enable} on reset.
>
> +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> +\field{queue_enable} after the driver has reset the virtqueue via
> +\field{queue_reset}.
> +
> +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> +\field{queue_reset} on reset.
> +
> +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> +\field{queue_reset} after the virtqueue is enabled with \field{queue_enable}.
> +
> +The device MUST reset the queue when 1 is written to \field{queue_reset}, and
> +present a 1 in \field{queue_reset} after the queue has been reset, until the
> +driver re-enables the queue via \field{queue_enable} or the device is reset.
> +The device MAY present different default values after queue reset.

I'm not sure I get the meaning of this. The device should stick to
consistent default values.

Thanks

> +(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> +
>  The device MUST present a 0 in \field{queue_size} if the virtqueue
>  corresponding to the current \field{queue_select} is unavailable.
>
> @@ -1045,6 +1068,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
>
>  The driver MUST NOT write a 0 to \field{queue_enable}.
>
> +If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
> +\field{queue_reset} to reset the queue, it MUST verify that the queue
> +has been reset by reading back \field{queue_reset} and ensuring that it
> +is 1. The driver MAY re-enable the queue by writing a 1 to
> +\field{queue_enable} after ensuring that the other virtqueue fields have
> +been set up correctly. The driver MAY set driver-writeable queue configuration
> +values to different values than those that were used before the queue reset.
> +(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> +
>  \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
>
>  The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG
> --
> 2.31.0
>

[virtio-dev] Re: [PATCH v5 2/3] virtio: pci support virtqueue reset

[Xuan Zhuo]

On Wed, 13 Oct 2021 14:05:14 +0800, Jason Wang <jasowang@redhat.com> wrote:
> On Fri, Oct 1, 2021 at 1:50 AM Xuan Zhuo <xuanzhuo@linux.alibaba.com> wrote:
> >
> > PCI support virtqueue reset.
> >
> > virtio_pci_common_cfg add "queue_reset" to support virtqueue reset.
> > The driver uses this to selectively reset the queue.
> >
> > Signed-off-by: Xuan Zhuo <xuanzhuo@linux.alibaba.com>
> > ---
> >  content.tex | 32 ++++++++++++++++++++++++++++++++
> >  1 file changed, 32 insertions(+)
> >
> > diff --git a/content.tex b/content.tex
> > index dd095f4..d014420 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -901,6 +901,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> >          le64 queue_driver;              /* read-write */
> >          le64 queue_device;              /* read-write */
> >          le16 queue_notify_data;         /* read-only for driver */
> > +        le16 queue_reset;               /* read-write */
> >  };
> >  \end{lstlisting}
> >
> > @@ -980,6 +981,12 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> >          may benefit from providing another value, for example an internal virtqueue
> >          identifier, or an internal offset related to the virtqueue number.
> >          \end{note}
> > +
> > +\item[\field{queue_reset}]
> > +        The driver uses this to selectively reset the queue.
> > +        This field exists only if VIRTIO_F_RING_RESET has been
> > +        negotiated. (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> > +
> >  \end{description}
> >
> >  \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
> > @@ -1021,6 +1028,22 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> >
> >  The device MUST present a 0 in \field{queue_enable} on reset.
> >
> > +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> > +\field{queue_enable} after the driver has reset the virtqueue via
> > +\field{queue_reset}.
> > +
> > +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> > +\field{queue_reset} on reset.
> > +
> > +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> > +\field{queue_reset} after the virtqueue is enabled with \field{queue_enable}.
> > +
> > +The device MUST reset the queue when 1 is written to \field{queue_reset}, and
> > +present a 1 in \field{queue_reset} after the queue has been reset, until the
> > +driver re-enables the queue via \field{queue_enable} or the device is reset.
> > +The device MAY present different default values after queue reset.
>
> I'm not sure I get the meaning of this. The device should stick to
> consistent default values.

I do consider whether it is possible to allow the device to present different
default values at this time.

I thought about it carefully, it might cause some trouble. My
next version will emphasize that the same default values should be presented.

Thanks.

>
> Thanks
>
> > +(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> > +
> >  The device MUST present a 0 in \field{queue_size} if the virtqueue
> >  corresponding to the current \field{queue_select} is unavailable.
> >
> > @@ -1045,6 +1068,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> >
> >  The driver MUST NOT write a 0 to \field{queue_enable}.
> >
> > +If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
> > +\field{queue_reset} to reset the queue, it MUST verify that the queue
> > +has been reset by reading back \field{queue_reset} and ensuring that it
> > +is 1. The driver MAY re-enable the queue by writing a 1 to
> > +\field{queue_enable} after ensuring that the other virtqueue fields have
> > +been set up correctly. The driver MAY set driver-writeable queue configuration
> > +values to different values than those that were used before the queue reset.
> > +(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> > +
> >  \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
> >
> >  The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG
> > --
> > 2.31.0
> >
>

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

Re: [PATCH v5 2/3] virtio: pci support virtqueue reset

[Jason Wang]

On Wed, Oct 13, 2021 at 2:55 PM Xuan Zhuo <xuanzhuo@linux.alibaba.com> wrote:
>
> On Wed, 13 Oct 2021 14:05:14 +0800, Jason Wang <jasowang@redhat.com> wrote:
> > On Fri, Oct 1, 2021 at 1:50 AM Xuan Zhuo <xuanzhuo@linux.alibaba.com> wrote:
> > >
> > > PCI support virtqueue reset.
> > >
> > > virtio_pci_common_cfg add "queue_reset" to support virtqueue reset.
> > > The driver uses this to selectively reset the queue.
> > >
> > > Signed-off-by: Xuan Zhuo <xuanzhuo@linux.alibaba.com>
> > > ---
> > >  content.tex | 32 ++++++++++++++++++++++++++++++++
> > >  1 file changed, 32 insertions(+)
> > >
> > > diff --git a/content.tex b/content.tex
> > > index dd095f4..d014420 100644
> > > --- a/content.tex
> > > +++ b/content.tex
> > > @@ -901,6 +901,7 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> > >          le64 queue_driver;              /* read-write */
> > >          le64 queue_device;              /* read-write */
> > >          le16 queue_notify_data;         /* read-only for driver */
> > > +        le16 queue_reset;               /* read-write */
> > >  };
> > >  \end{lstlisting}
> > >
> > > @@ -980,6 +981,12 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> > >          may benefit from providing another value, for example an internal virtqueue
> > >          identifier, or an internal offset related to the virtqueue number.
> > >          \end{note}
> > > +
> > > +\item[\field{queue_reset}]
> > > +        The driver uses this to selectively reset the queue.
> > > +        This field exists only if VIRTIO_F_RING_RESET has been
> > > +        negotiated. (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> > > +
> > >  \end{description}
> > >
> > >  \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
> > > @@ -1021,6 +1028,22 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> > >
> > >  The device MUST present a 0 in \field{queue_enable} on reset.
> > >
> > > +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> > > +\field{queue_enable} after the driver has reset the virtqueue via
> > > +\field{queue_reset}.
> > > +
> > > +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> > > +\field{queue_reset} on reset.
> > > +
> > > +If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
> > > +\field{queue_reset} after the virtqueue is enabled with \field{queue_enable}.
> > > +
> > > +The device MUST reset the queue when 1 is written to \field{queue_reset}, and
> > > +present a 1 in \field{queue_reset} after the queue has been reset, until the
> > > +driver re-enables the queue via \field{queue_enable} or the device is reset.
> > > +The device MAY present different default values after queue reset.
> >
> > I'm not sure I get the meaning of this. The device should stick to
> > consistent default values.
>
> I do consider whether it is possible to allow the device to present different
> default values at this time.

If we do this, it needs to be detected by the driver, otherwise we
break the driver.

>
> I thought about it carefully, it might cause some trouble. My
> next version will emphasize that the same default values should be presented.

That's fine.

Thanks

>
> Thanks.
>
> >
> > Thanks
> >
> > > +(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> > > +
> > >  The device MUST present a 0 in \field{queue_size} if the virtqueue
> > >  corresponding to the current \field{queue_select} is unavailable.
> > >
> > > @@ -1045,6 +1068,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> > >
> > >  The driver MUST NOT write a 0 to \field{queue_enable}.
> > >
> > > +If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
> > > +\field{queue_reset} to reset the queue, it MUST verify that the queue
> > > +has been reset by reading back \field{queue_reset} and ensuring that it
> > > +is 1. The driver MAY re-enable the queue by writing a 1 to
> > > +\field{queue_enable} after ensuring that the other virtqueue fields have
> > > +been set up correctly. The driver MAY set driver-writeable queue configuration
> > > +values to different values than those that were used before the queue reset.
> > > +(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
> > > +
> > >  \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
> > >
> > >  The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG
> > > --
> > > 2.31.0
> > >
> >
>

[PATCH v5 3/3] virtio: mmio support virtqueue reset

[Xuan Zhuo]

mmio support virtqueue reset.

MMIO Device Register Layout "QueueReady" to support virtqueue reset.
The driver uses this to selectively reset the queue.

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

diff --git a/content.tex b/content.tex
index d014420..025e932 100644
--- a/content.tex
+++ b/content.tex
@@ -1853,7 +1853,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
     Writing to this register selects the virtual queue that the
     following operations on \field{QueueNumMax}, \field{QueueNum}, \field{QueueReady},
     \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh},
-    \field{QueueDeviceLow} and \field{QueueDeviceHigh} apply to. The index
+    \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index
     number of the first queue is zero (0x0). 
   }
   \hline 
@@ -1970,6 +1970,12 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
     0xffffffffffffffff.
   }
   \hline 
+  \mmioreg{QueueReset}{Virtual queue reset bit}{0x0c0}{RW}{%
+    If VIRTIO_F_RING_RESET has been negotiated, writing one (0x1) to this
+    register selectively resets the queue. Both read and write accesses
+    apply to the queue selected by writing to \field{QueueSel}.
+  }
+  \hline
   \mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{
     Reading from this register returns a value describing a version of the device-specific configuration space (see \field{Config}).
     The driver can then access the configuration space and, when finished, read \field{ConfigGeneration} again.
@@ -2005,6 +2011,22 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
 
 The device MUST NOT access virtual queue contents when \field{QueueReady} is zero (0x0).
 
+If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
+\field{QueueReady} after the driver has reset the virtqueue via
+\field{QueueReset}.
+
+If VIRTIO_F_RING_RESET has been negotiated, the device MUST present a 0 in
+\field{QueueReset} on reset.
+
+If VIRTIO_F_RING_RESET has been negotiated, The device MUST present a 0 in
+\field{QueueReset} after the virtqueue is enabled with \field{QueueReady}.
+
+The device MUST reset the queue when 1 is written to \field{QueueReset}, and
+present a 1 in \field{QueueReset} after the queue has been reset, until the
+driver re-enables the queue via \field{QueueReady} or until the device is reset.
+The device MAY present different default values after queue reset.
+(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
+
 \drivernormative{\subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout}
 The driver MUST NOT access memory locations not described in the
 table \ref{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}
@@ -2047,6 +2069,15 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
 The driver MUST write a value with a bit mask describing events it handled into \field{InterruptACK} when
 it finishes handling an interrupt and MUST NOT set any of the undefined bits in the value.
 
+If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
+\field{QueueReset} to reset the queue, it MUST verify that the queue
+has been reset by reading back \field{QueueReset} and ensuring that it
+is 1. The driver MAY re-enable the queue by writing a 1 to
+\field{QueueReady} after ensuring that the other virtqueue fields have
+been set up correctly. The driver MAY set driver-writeable queue configuration
+values to different values than those that were used before the queue reset.
+(see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
+
 \subsection{MMIO-specific Initialization And Device Operation}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation}
 
 \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}
-- 
2.31.0