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

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 <[email protected]>
---

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