virtio: introduce SUSPEND bit in device status
PATCH v4 1/1 virtio: introduce SUSPEND bit in device status
This commit allows the driver to suspend the device by introducing a new status bit SUSPEND in device_status.
This commit also introduce a new feature bit VIRTIO_F_SUSPEND which indicating whether the device support SUSPEND.
This SUSPEND bit is transport-independent.
--- content.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 10 deletions(-)
content.tex +59 -10
@@ -36,19 +36,22 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev this bit. For example, under Linux, drivers can be loadable modules. \end{note} -\item[FAILED (128)] Indicates that something went wrong in the guest, - and it has given up on the device. This could be an internal - error, or the driver didn't like the device for some reason, or - even a fatal error during device operation. +\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to + drive the device. \item[FEATURES_OK (8)] Indicates that the driver has acknowledged all the features it understands, and feature negotiation is complete. -\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to - drive the device. +\item[SUSPEND (16)] When VIRTIO_F_SUSPEND is negotiated, indicates that the + device has been suspended by the driver. \item[DEVICE_NEEDS_RESET (64)] Indicates that the device has experienced an error from which it can't recover. + +\item[FAILED (128)] Indicates that something went wrong in the guest, + and it has given up on the device. This could be an internal + error, or the driver didn't like the device for some reason, or + even a fatal error during device operation. \end{description} The \field{device status} field starts out as 0, and is reinitialized to 0 by
@@ -60,8 +63,9 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev initialization sequence specified in \ref{sec:General Initialization And Device Operation / Device Initialization}. -The driver MUST NOT clear a -\field{device status} bit. If the driver sets the FAILED bit, +The driver MUST NOT clear a \field{device status} bit other than SUSPEND +except when setting \field{device status} to 0 as a transport-specific way to +initiate a reset. If the driver sets the FAILED bit, the driver MUST later reset the device before attempting to re-initialize. The driver SHOULD NOT rely on completion of operations of a
@@ -99,10 +103,10 @@ \section{Feature Bits}\label{sec:Basic Facilities of a Virtio Device / Feature B \begin{description} \item[0 to 23, and 50 to 127] Feature bits for the specific device type -\item[24 to 41] Feature bits reserved for extensions to the queue and +\item[24 to 42] Feature bits reserved for extensions to the queue and feature negotiation mechanisms -\item[42 to 49, and 128 and above] Feature bits reserved for future extensions. +\item[43 to 49, and 128 and above] Feature bits reserved for future extensions. \end{description} \begin{note}
@@ -629,6 +633,47 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / Thus a driver MUST ensure a virtqueue isn't live (by device reset) before removing exposed buffers. +\section{Device Suspend}\label{sec:General Initialization And Device Operation / Device Suspend} + +When VIRTIO_F_SUSPEND is negotiated, the driver can set the +SUSPEND bit in \field{device status} to suspend a device, and can +clear the SUSPEND bit to resume a suspended device. + +\drivernormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The driver MUST NOT set SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +Once the driver sets SUSPEND to \field{device status} of the device: +\begin{itemize} +\item The driver MUST re-read \field{device status} to verify whether the SUSPEND bit is set. +If not, the device does not support the SUSPEND feature. +\item The driver MUST NOT make any more buffers available to the device. +\item The driver MUST NOT access any fields of any virtqueues or kick any virtqueues. +\item The driver MUST NOT access Device Configuration Space. +\end{itemize} + +\devicenormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The device MUST ignore SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +The device MUST ignore all access to its Configuration Space while +suspended, except for \field{device status}. + +A device MUST NOT send any notifications, access any virtqueues, or modify +any fields in its configuration space while suspended. + +If SUSPEND is set in \field{device status}, when the driver clears SUSPEND, +the device MUST either resume normal operation or set DEVICE_NEEDS_RESET. + +When the driver sets SUSPEND, +the device SHOULD perform the following actions before presenting SUSPEND bit in the \field{device status}: + +\begin{itemize} +\item Stop processing more buffers of any virtqueues +\item Wait until all buffers that are being processed have been used. +\item Send used buffer notifications to the driver. +\end{itemize} + \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} Virtio can use various different buses, thus the standard is split
@@ -872,6 +917,10 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits} for handling features reserved for future use. + \item[VIRTIO_F_SUSPEND(42)] This feature indicates that the driver can + set SUSPEND to the device. + See \ref{sec:Basic Facilities of a Virtio Device / Device Status Field}. + \end{description} \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
Signature · 1 line
2.45.1
Quoted 8 lines · Zhu Lingshan
This commit allows the driver to suspend the device by introducing a new status bit SUSPEND in
device_status.This commit also introduce a new feature bit
VIRTIO_F_SUSPENDwhich indicating whether the device support SUSPEND.This SUSPEND bit is transport-independent.
[...]
Quoted 6 lines
+\section{Device Suspend}\label{sec:General Initialization And Device Operation / Device Suspend}
content.tex +5
-0+ +When VIRTIO_F_SUSPEND is negotiated, the driver can set the +SUSPEND bit in \field{device status} to suspend a device, and can +clear the SUSPEND bit to resume a suspended device. +
content.tex \section{Device Cleanup}\label{sec:General Initialization And Device Operation / · line 651
Quoted 10 lines
content.tex +10
-0+\drivernormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The driver MUST NOT set SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +Once the driver sets SUSPEND to \field{device status} of the device: +\begin{itemize} +\item The driver MUST re-read \field{device status} to verify whether the SUSPEND bit is set. +If not, the device does not support the SUSPEND feature. +\item The driver MUST NOT make any more buffers available to the device. +\item The driver MUST NOT access any fields of any virtqueues or kick any virtqueues.
nit: "kick" is not the terminology used in the spec; perhaps this could be something like:
"The driver MUST NOT notify the device."
Thanks,
-- Daniel
Quoted 20 lines · Daniel Verkamp
Quoted 7 lines · Zhu Lingshan
This commit allows the driver to suspend the device by introducing a new status bit SUSPEND in
device_status.This commit also introduce a new feature bit
VIRTIO_F_SUSPENDwhich indicating whether the device support SUSPEND.This SUSPEND bit is transport-independent.
[...]
Quoted 11 lines
+\section{Device Suspend}\label{sec:General Initialization And Device Operation / Device Suspend}
content.tex +10
-0+ +When VIRTIO_F_SUSPEND is negotiated, the driver can set the +SUSPEND bit in \field{device status} to suspend a device, and can +clear the SUSPEND bit to resume a suspended device. + +\drivernormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The driver MUST NOT set SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +Once the driver sets SUSPEND to \field{device status} of the device:
Quoted 8 lines
Quoted 5 lines
+\begin{itemize}
+\item The driver MUST re-read \field{device status} to verify whether the SUSPEND bit is set. +If not, the device does not support the SUSPEND feature.
+\item The driver MUST NOT make any more buffers available to the device. +\item The driver MUST NOT access any fields of any virtqueues or kick any virtqueues.nit: "kick" is not the terminology used in the spec; perhaps this could be something like:
"The driver MUST NOT notify the device."
yeah, that's true, will be "notify" in V5. Thanks!
Quoted 3 lines
Thanks,
-- Daniel
Quoted 11 lines · Zhu Lingshan
This commit allows the driver to suspend the device by introducing a new status bit SUSPEND in
device_status.This commit also introduce a new feature bit
VIRTIO_F_SUSPENDwhich indicating whether the device support SUSPEND.This SUSPEND bit is transport-independent.
Signed-off-by Zhu Lingshan <[email protected]>Signed-off-by Eugenio Pérez <[email protected]>Signed-off-by Zhu Lingshan <[email protected]>
Pls put [PATCH v4] in the subject. git format-patch has a "-v" flag that does it.
Quoted 123 lines
--- content.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 10 deletions(-)content.tex +59
-10@@ -36,19 +36,22 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev this bit. For example, under Linux, drivers can be loadable modules. \end{note} -\item[FAILED (128)] Indicates that something went wrong in the guest, - and it has given up on the device. This could be an internal - error, or the driver didn't like the device for some reason, or - even a fatal error during device operation. +\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to + drive the device. \item[FEATURES_OK (8)] Indicates that the driver has acknowledged all the features it understands, and feature negotiation is complete. -\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to - drive the device. +\item[SUSPEND (16)] When VIRTIO_F_SUSPEND is negotiated, indicates that the + device has been suspended by the driver. \item[DEVICE_NEEDS_RESET (64)] Indicates that the device has experienced an error from which it can't recover. + +\item[FAILED (128)] Indicates that something went wrong in the guest, + and it has given up on the device. This could be an internal + error, or the driver didn't like the device for some reason, or + even a fatal error during device operation. \end{description} The \field{device status} field starts out as 0, and is reinitialized to 0 by@@ -60,8 +63,9 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev initialization sequence specified in \ref{sec:General Initialization And Device Operation / Device Initialization}. -The driver MUST NOT clear a -\field{device status} bit. If the driver sets the FAILED bit, +The driver MUST NOT clear a \field{device status} bit other than SUSPEND +except when setting \field{device status} to 0 as a transport-specific way to +initiate a reset. If the driver sets the FAILED bit, the driver MUST later reset the device before attempting to re-initialize. The driver SHOULD NOT rely on completion of operations of a@@ -99,10 +103,10 @@ \section{Feature Bits}\label{sec:Basic Facilities of a Virtio Device / Feature B \begin{description} \item[0 to 23, and 50 to 127] Feature bits for the specific device type -\item[24 to 41] Feature bits reserved for extensions to the queue and +\item[24 to 42] Feature bits reserved for extensions to the queue and feature negotiation mechanisms -\item[42 to 49, and 128 and above] Feature bits reserved for future extensions. +\item[43 to 49, and 128 and above] Feature bits reserved for future extensions. \end{description} \begin{note}@@ -629,6 +633,47 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / Thus a driver MUST ensure a virtqueue isn't live (by device reset) before removing exposed buffers. +\section{Device Suspend}\label{sec:General Initialization And Device Operation / Device Suspend} + +When VIRTIO_F_SUSPEND is negotiated, the driver can set the +SUSPEND bit in \field{device status} to suspend a device, and can +clear the SUSPEND bit to resume a suspended device. + +\drivernormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The driver MUST NOT set SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +Once the driver sets SUSPEND to \field{device status} of the device: +\begin{itemize} +\item The driver MUST re-read \field{device status} to verify whether the SUSPEND bit is set. +If not, the device does not support the SUSPEND feature. +\item The driver MUST NOT make any more buffers available to the device. +\item The driver MUST NOT access any fields of any virtqueues or kick any virtqueues. +\item The driver MUST NOT access Device Configuration Space. +\end{itemize} + +\devicenormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The device MUST ignore SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +The device MUST ignore all access to its Configuration Space while +suspended, except for \field{device status}. + +A device MUST NOT send any notifications, access any virtqueues, or modify +any fields in its configuration space while suspended. + +If SUSPEND is set in \field{device status}, when the driver clears SUSPEND, +the device MUST either resume normal operation or set DEVICE_NEEDS_RESET. + +When the driver sets SUSPEND, +the device SHOULD perform the following actions before presenting SUSPEND bit in the \field{device status}: + +\begin{itemize} +\item Stop processing more buffers of any virtqueues +\item Wait until all buffers that are being processed have been used. +\item Send used buffer notifications to the driver. +\end{itemize} + \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} Virtio can use various different buses, thus the standard is split@@ -872,6 +917,10 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits} for handling features reserved for future use. + \item[VIRTIO_F_SUSPEND(42)] This feature indicates that the driver can + set SUSPEND to the device. + See \ref{sec:Basic Facilities of a Virtio Device / Device Status Field}. + \end{description} \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}Signature · 1 line
2.45.1
Quoted 7 lines · Michael S. Tsirkin
Quoted 6 lines · Zhu Lingshan
This commit allows the driver to suspend the device by introducing a new status bit SUSPEND in
device_status.This commit also introduce a new feature bit
VIRTIO_F_SUSPENDwhich indicating whether the device support SUSPEND.
Quoted 8 lines
Quoted 5 lines
This SUSPEND bit is transport-independent.
Signed-off-by Zhu Lingshan <[email protected]>Signed-off-by Eugenio Pérez <[email protected]>Signed-off-by Zhu Lingshan <[email protected]>Pls put [PATCH v4] in the subject. git format-patch has a "-v" flag that does it.
will do in V5. Thanks!
Quoted 124 lines
Quoted 124 lines
--- content.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 10 deletions(-)content.tex +59
-10@@ -36,19 +36,22 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev this bit. For example, under Linux, drivers can be loadable modules. \end{note} -\item[FAILED (128)] Indicates that something went wrong in the guest, - and it has given up on the device. This could be an internal - error, or the driver didn't like the device for some reason, or - even a fatal error during device operation. +\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to + drive the device. \item[FEATURES_OK (8)] Indicates that the driver has acknowledged all the features it understands, and feature negotiation is complete. -\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to - drive the device. +\item[SUSPEND (16)] When VIRTIO_F_SUSPEND is negotiated, indicates that the + device has been suspended by the driver. \item[DEVICE_NEEDS_RESET (64)] Indicates that the device has experienced an error from which it can't recover. + +\item[FAILED (128)] Indicates that something went wrong in the guest, + and it has given up on the device. This could be an internal + error, or the driver didn't like the device for some reason, or + even a fatal error during device operation. \end{description} The \field{device status} field starts out as 0, and is reinitialized to 0 by@@ -60,8 +63,9 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev initialization sequence specified in \ref{sec:General Initialization And Device Operation / Device Initialization}. -The driver MUST NOT clear a -\field{device status} bit. If the driver sets the FAILED bit, +The driver MUST NOT clear a \field{device status} bit other than SUSPEND +except when setting \field{device status} to 0 as a transport-specific way to +initiate a reset. If the driver sets the FAILED bit, the driver MUST later reset the device before attempting to re-initialize. The driver SHOULD NOT rely on completion of operations of a@@ -99,10 +103,10 @@ \section{Feature Bits}\label{sec:Basic Facilities of a Virtio Device / Feature B \begin{description} \item[0 to 23, and 50 to 127] Feature bits for the specific device type -\item[24 to 41] Feature bits reserved for extensions to the queue and +\item[24 to 42] Feature bits reserved for extensions to the queue and feature negotiation mechanisms -\item[42 to 49, and 128 and above] Feature bits reserved for future extensions. +\item[43 to 49, and 128 and above] Feature bits reserved for future extensions. \end{description} \begin{note}@@ -629,6 +633,47 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / Thus a driver MUST ensure a virtqueue isn't live (by device reset) before removing exposed buffers. +\section{Device Suspend}\label{sec:General Initialization And Device Operation / Device Suspend} + +When VIRTIO_F_SUSPEND is negotiated, the driver can set the +SUSPEND bit in \field{device status} to suspend a device, and can +clear the SUSPEND bit to resume a suspended device. + +\drivernormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The driver MUST NOT set SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +Once the driver sets SUSPEND to \field{device status} of the device: +\begin{itemize} +\item The driver MUST re-read \field{device status} to verify whether the SUSPEND bit is set. +If not, the device does not support the SUSPEND feature. +\item The driver MUST NOT make any more buffers available to the device. +\item The driver MUST NOT access any fields of any virtqueues or kick any virtqueues. +\item The driver MUST NOT access Device Configuration Space. +\end{itemize} + +\devicenormative{\subsection}{Device Suspend}{General Initialization And Device Operation / Device Suspend} + +The device MUST ignore SUSPEND if FEATURES_OK is not set or VIRTIO_F_SUSPEND is not negotiated. + +The device MUST ignore all access to its Configuration Space while +suspended, except for \field{device status}. + +A device MUST NOT send any notifications, access any virtqueues, or modify +any fields in its configuration space while suspended. + +If SUSPEND is set in \field{device status}, when the driver clears SUSPEND, +the device MUST either resume normal operation or set DEVICE_NEEDS_RESET. + +When the driver sets SUSPEND, +the device SHOULD perform the following actions before presenting SUSPEND bit in the \field{device status}: + +\begin{itemize} +\item Stop processing more buffers of any virtqueues +\item Wait until all buffers that are being processed have been used. +\item Send used buffer notifications to the driver. +\end{itemize} + \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} Virtio can use various different buses, thus the standard is split@@ -872,6 +917,10 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits} for handling features reserved for future use. + \item[VIRTIO_F_SUSPEND(42)] This feature indicates that the driver can + set SUSPEND to the device. + See \ref{sec:Basic Facilities of a Virtio Device / Device Status Field}. + \end{description} \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}Signature · 1 line
2.45.1