[PATCH v2 0/1] transport-mmio: Add optional reset completion polling

[PATCH v2 0/1] transport-mmio: Add optional reset completion polling

[Peter Hilber]

Let devices using the MMIO transport avoid stalling the driver (virtual)
CPU during device reset, which requires introducing a new MMIO transport
version. This proposal is similar to [1], but simpler.

v2, after discussion on the mailing list, describes some edge cases
differently and rewords some requirements.

If the device reset includes terminating device activity which may
interfere with the driver, the reset should always have completed by the
time the driver considers the reset complete. After device reset, the
driver may free previously exposed buffers. Per the current MMIO transport
specification, the device must hence complete the reset during the write of
zero to the Status register. If terminating the device activity takes long,
the (virtual) CPU doing this write to the Status register must be stalled
for extended time, which may violate real-time requirements (including
those for hypervisor trap-and-emulate).

Address this by introducing a new MMIO transport version, v3, where the
driver must poll for reset completion, and, hence, the device reset does
not have to finish during the write of zero to the Status register. Polling
for an operation to finish is a pattern also used for the PCI transport
device reset, device suspend, and MMIO transport QueueReset writes.

Unlike [1], this proposal does not require a reset-in-progress status bit.
Unlike [1], devices cannot indicate that the reset failed, which appears
unneeded.

This proposal has been verified with proof-of-concept implementations for
the Linux kernel and EDK2 OVMF Virtio drivers (supporting v2 and v3), and
for the QEMU Virtio devices.

[1] https://www.mail-archive.com/virtio-dev@lists.oasis-open.org/msg07677.html

v2:

- Add summary of MMIO v3 to Version register description (Matias)

- Align requirements on Status register transition to zero with transport-
  independent requirements (Matias)

- Change requirements relating to reset when status is already zero
  (Matias)

- In the commit message, document when v3 devices may be incompatible with
  v2 drivers (as per reply to Michael)

- Improve wording; refer to "zero" rather than "0"

Signed-off-by: Peter Hilber <peter.hilber@oss.qualcomm.com>


Peter Hilber (1):
  transport-mmio: Add v3, which polls for reset completion

 transport-mmio.tex | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)


base-commit: 5187698cc6f40fd2f2a714ca3faa6e998c5fc231
-- 
2.43.0

[PATCH v2 1/1] transport-mmio: Add v3, which polls for reset completion

[Peter Hilber]

Let devices using the MMIO transport avoid stalling the driver (virtual)
CPU during device reset, which requires introducing a new MMIO transport
version.

Unlike the PCI transport, the MMIO transport does not require the driver
to poll for reset completion. This requires a device using the MMIO
transport to complete reset during the write of zero to the Status
register. Device reset may take more than 100 ms if it involves
terminating ongoing device activity which accesses driver memory. When
the (virtual) CPU writing zero to the Status register needs to be
stalled during this, this may violate real-time requirements (including
those for hypervisor trap-and-emulate).

Address this by introducing a new MMIO transport version, v3, where the
driver must poll for reset completion, and, hence, the device reset does
not have to complete during the write to the Status register. Add a
requirement that resetting a device which already has Status zero is
synchronous to avoid ambiguity when such a reset would finish.

For clarity, also add some related requirements for v2. These
requirements are implied by the rest of the specification and therefore
do not alter the v2 semantics.

With MMIO transport v3, reset essentially works as with the PCI
transport, and the change is therefore not expected to cause problems.

Existing devices with MMIO transport v2 are not required to implement
v3, which will not work with current drivers. Only devices which require
asynchronous reset need to report MMIO transport v3, and therefore
require an updated driver.

Drivers have to support the MMIO transport versions of the used devices.
Portable MMIO transport drivers should therefore support both v2 and v3,
which is simple.

Signed-off-by: Peter Hilber <peter.hilber@oss.qualcomm.com>
---

Notes:
    v2:
    
    - Add summary of MMIO v3 to Version register description (Matias)
    
    - Align requirements on Status register transition to zero with transport-
      independent requirements (Matias)
    
    - Change requirements relating to reset when status is already zero
      (Matias)
    
    - In the commit message, document when v3 devices may be incompatible with
      v2 drivers (as per reply to Michael)
    
    - Improve wording; refer to "zero" rather than "0"

 transport-mmio.tex | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/transport-mmio.tex b/transport-mmio.tex
index 94a93a1..cddbcc9 100644
--- a/transport-mmio.tex
+++ b/transport-mmio.tex
@@ -64,7 +64,8 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
   }
   \hline
   \mmioreg{Version}{Device version number}{0x004}{R}{%
-    0x2.
+    0x2 or 0x3. With version 0x3, the driver waits until it reads zero from the
+    \field{Status} register before considering a reset complete.
     \begin{note}
       Legacy devices (see \ref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}) used 0x1.
     \end{note}
@@ -185,6 +186,11 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
     Writing non-zero values to this register sets the status flags,
     indicating the driver progress. Writing zero (0x0) to this
     register triggers a device reset.
+
+    Starting with \field{Version} 0x3, the device reset need not
+    complete before the write returns, and the driver waits until it
+    reads back zero before considering a reset complete.
+
     See also p. \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}.
   }
   \hline
@@ -262,13 +268,31 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
 
 The device MUST return 0x74726976 in \field{MagicValue}.
 
-The device MUST return value 0x2 in \field{Version}.
+The device MUST return value 0x2 or 0x3 in \field{Version}.
 
 The device MUST present each event by setting the corresponding bit in \field{InterruptStatus} from the
 moment it takes place, until the driver acknowledges the interrupt
 by writing a corresponding bit mask to the \field{InterruptACK} register.  Bits which
 do not represent events which took place MUST be zero.
 
+The device MUST reset when zero is written to \field{Status}.
+
+The device MUST present zero in \field{Status} once it has finished the reset.
+
+For \field{Version} 0x2, the device MUST finish a reset before the driver's
+write of zero to \field{Status} has completed.
+
+For \field{Version} 0x3, if \field{Status} is non-zero before a reset, the
+device MAY continue with the reset after the driver's write of zero to
+\field{Status} has completed.
+
+For \field{Version} 0x3, if \field{Status} is zero before a reset, the device
+MUST finish the reset before the driver's write of zero to \field{Status} has
+completed.
+
+For \field{Version} 0x3, the device MUST change \field{Status} to zero as the
+last step of the reset.
+
 Upon reset, the device MUST clear all bits in \field{InterruptStatus} and ready bits in the
 \field{QueueReady} register for all queues in the device.
 
@@ -305,7 +329,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
 The driver MUST ignore a device with \field{MagicValue} which is not 0x74726976,
 although it MAY report an error.
 
-The driver MUST ignore a device with \field{Version} which is not 0x2,
+The driver MUST ignore a device whose \field{Version} is neither 0x2 nor 0x3,
 although it MAY report an error.
 
 The driver MUST ignore a device with \field{DeviceID} 0x0,
@@ -331,6 +355,9 @@ \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.
 
+For \field{Version} 0x3, the driver MUST NOT consider a reset complete before
+reading back zero in \field{Status}.
+
 If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
 \field{QueueReset} to reset the queue, the driver MUST NOT consider queue
 reset to be complete until it reads back 0 in \field{QueueReset}. The driver
-- 
2.43.0

Re: [PATCH v2 1/1] transport-mmio: Add v3, which polls for reset completion

[Matias Ezequiel Vara Larsen]

On Thu, Apr 16, 2026 at 06:52:56PM +0200, Peter Hilber wrote:
> Let devices using the MMIO transport avoid stalling the driver (virtual)
> CPU during device reset, which requires introducing a new MMIO transport
> version.
> 
> Unlike the PCI transport, the MMIO transport does not require the driver
> to poll for reset completion. This requires a device using the MMIO
> transport to complete reset during the write of zero to the Status
> register. Device reset may take more than 100 ms if it involves
> terminating ongoing device activity which accesses driver memory. When
> the (virtual) CPU writing zero to the Status register needs to be
> stalled during this, this may violate real-time requirements (including
> those for hypervisor trap-and-emulate).
> 
> Address this by introducing a new MMIO transport version, v3, where the
> driver must poll for reset completion, and, hence, the device reset does
> not have to complete during the write to the Status register. Add a
> requirement that resetting a device which already has Status zero is
> synchronous to avoid ambiguity when such a reset would finish.
> 
> For clarity, also add some related requirements for v2. These
> requirements are implied by the rest of the specification and therefore
> do not alter the v2 semantics.
> 
> With MMIO transport v3, reset essentially works as with the PCI
> transport, and the change is therefore not expected to cause problems.
> 
> Existing devices with MMIO transport v2 are not required to implement
> v3, which will not work with current drivers. Only devices which require
> asynchronous reset need to report MMIO transport v3, and therefore
> require an updated driver.
> 
> Drivers have to support the MMIO transport versions of the used devices.
> Portable MMIO transport drivers should therefore support both v2 and v3,
> which is simple.
> 
> Signed-off-by: Peter Hilber <peter.hilber@oss.qualcomm.com>
> ---


Reviewed-by: Matias Ezequiel Vara Larsen <mvaralar@redhat.com>

Matias

> 
> Notes:
>     v2:
>     
>     - Add summary of MMIO v3 to Version register description (Matias)
>     
>     - Align requirements on Status register transition to zero with transport-
>       independent requirements (Matias)
>     
>     - Change requirements relating to reset when status is already zero
>       (Matias)
>     
>     - In the commit message, document when v3 devices may be incompatible with
>       v2 drivers (as per reply to Michael)
>     
>     - Improve wording; refer to "zero" rather than "0"
> 
>  transport-mmio.tex | 33 ++++++++++++++++++++++++++++++---
>  1 file changed, 30 insertions(+), 3 deletions(-)
> 
> diff --git a/transport-mmio.tex b/transport-mmio.tex
> index 94a93a1..cddbcc9 100644
> --- a/transport-mmio.tex
> +++ b/transport-mmio.tex
> @@ -64,7 +64,8 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
>    }
>    \hline
>    \mmioreg{Version}{Device version number}{0x004}{R}{%
> -    0x2.
> +    0x2 or 0x3. With version 0x3, the driver waits until it reads zero from the
> +    \field{Status} register before considering a reset complete.
>      \begin{note}
>        Legacy devices (see \ref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}) used 0x1.
>      \end{note}
> @@ -185,6 +186,11 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
>      Writing non-zero values to this register sets the status flags,
>      indicating the driver progress. Writing zero (0x0) to this
>      register triggers a device reset.
> +
> +    Starting with \field{Version} 0x3, the device reset need not
> +    complete before the write returns, and the driver waits until it
> +    reads back zero before considering a reset complete.
> +
>      See also p. \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}.
>    }
>    \hline
> @@ -262,13 +268,31 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
>  
>  The device MUST return 0x74726976 in \field{MagicValue}.
>  
> -The device MUST return value 0x2 in \field{Version}.
> +The device MUST return value 0x2 or 0x3 in \field{Version}.
>  
>  The device MUST present each event by setting the corresponding bit in \field{InterruptStatus} from the
>  moment it takes place, until the driver acknowledges the interrupt
>  by writing a corresponding bit mask to the \field{InterruptACK} register.  Bits which
>  do not represent events which took place MUST be zero.
>  
> +The device MUST reset when zero is written to \field{Status}.
> +
> +The device MUST present zero in \field{Status} once it has finished the reset.
> +
> +For \field{Version} 0x2, the device MUST finish a reset before the driver's
> +write of zero to \field{Status} has completed.
> +
> +For \field{Version} 0x3, if \field{Status} is non-zero before a reset, the
> +device MAY continue with the reset after the driver's write of zero to
> +\field{Status} has completed.
> +
> +For \field{Version} 0x3, if \field{Status} is zero before a reset, the device
> +MUST finish the reset before the driver's write of zero to \field{Status} has
> +completed.
> +
> +For \field{Version} 0x3, the device MUST change \field{Status} to zero as the
> +last step of the reset.
> +
>  Upon reset, the device MUST clear all bits in \field{InterruptStatus} and ready bits in the
>  \field{QueueReady} register for all queues in the device.
>  
> @@ -305,7 +329,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
>  The driver MUST ignore a device with \field{MagicValue} which is not 0x74726976,
>  although it MAY report an error.
>  
> -The driver MUST ignore a device with \field{Version} which is not 0x2,
> +The driver MUST ignore a device whose \field{Version} is neither 0x2 nor 0x3,
>  although it MAY report an error.
>  
>  The driver MUST ignore a device with \field{DeviceID} 0x0,
> @@ -331,6 +355,9 @@ \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.
>  
> +For \field{Version} 0x3, the driver MUST NOT consider a reset complete before
> +reading back zero in \field{Status}.
> +
>  If VIRTIO_F_RING_RESET has been negotiated, after the driver writes 1 to
>  \field{QueueReset} to reset the queue, the driver MUST NOT consider queue
>  reset to be complete until it reads back 0 in \field{QueueReset}. The driver
> -- 
> 2.43.0
> 

Re: [PATCH v2 1/1] transport-mmio: Add v3, which polls for reset completion

[Peter Hilber]

On Thu, Apr 16, 2026 at 06:52:56PM +0200, Peter Hilber wrote:
> Let devices using the MMIO transport avoid stalling the driver (virtual)
> CPU during device reset, which requires introducing a new MMIO transport
> version.
> 
> Unlike the PCI transport, the MMIO transport does not require the driver
> to poll for reset completion. This requires a device using the MMIO
> transport to complete reset during the write of zero to the Status
> register. Device reset may take more than 100 ms if it involves
> terminating ongoing device activity which accesses driver memory. When
> the (virtual) CPU writing zero to the Status register needs to be
> stalled during this, this may violate real-time requirements (including
> those for hypervisor trap-and-emulate).
> 
> Address this by introducing a new MMIO transport version, v3, where the
> driver must poll for reset completion, and, hence, the device reset does
> not have to complete during the write to the Status register. Add a
> requirement that resetting a device which already has Status zero is
> synchronous to avoid ambiguity when such a reset would finish.
> 

Could you please open a voting ballot for this change?

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/246

This version got a Reviewed-by from Matias Ezequiel Vara Larsen [1].

Best regards,

Peter

[1] https://lore.kernel.org/virtio-comment/aeX0hPTBQh%2FtgLOp@fedora/#t