[PATCH 2/6] transport-mmio: Add administration virtqueue registers

[Parav Pandit <parav@nvidia.com>]

Add two read-only registers to the MMIO device register layout which
let the driver discover the administration virtqueues of the device,
mirroring admin_queue_index and admin_queue_num of the PCI
common configuration structure:

AdminQueueIndex (0x0c4): index of the first administration virtqueue.
AdminQueueNum (0x0c8): number of administration virtqueues.

Both registers are valid only if VIRTIO_F_ADMIN_VQ has been
negotiated. The offsets are taken from the unused range between
QueueReset and ConfigGeneration, so the layout of existing registers
is unchanged and no new MMIO Version is needed: the presence of the
registers is indicated by VIRTIO_F_ADMIN_VQ.

Also mention in QueueSel that administration virtqueues are selected
like any other virtqueue, and describe the typical driver flow for
discovering and initializing administration virtqueues.

VIRTIO_F_ADMIN_VQ is still listed as reserved for MMIO; this is
addressed in the following patch.

Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 transport-mmio.tex | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/transport-mmio.tex b/transport-mmio.tex
index e015bd7..3c5aa6b 100644
--- a/transport-mmio.tex
+++ b/transport-mmio.tex
@@ -116,6 +116,8 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
     \field{QueueSize}, \field{QueueReady},
     \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh},
     \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to.
+    The selected virtqueue can also be an administration virtqueue,
+    see \field{AdminQueueIndex} and \field{AdminQueueNum}.
   }
   \hline
   \mmioreg{QueueSizeMax}{Maximum virtqueue size}{0x034}{R}{%
@@ -248,6 +250,24 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
     apply to the queue selected by writing to \field{QueueSel}.
   }
   \hline
+  \mmioreg{AdminQueueIndex}{Index of the first administration virtqueue}{0x0c4}{R}{%
+    Reading from this register returns the virtqueue index of the first
+    administration virtqueue of the device.
+    This register is valid only if VIRTIO_F_ADMIN_VQ has been negotiated.
+    See \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}.
+  }
+  \hline
+  \mmioreg{AdminQueueNum}{Number of administration virtqueues}{0x0c8}{R}{%
+    Reading from this register returns the number of administration
+    virtqueues supported by the device.
+    Virtqueues with index between \field{AdminQueueIndex} and
+    (\field{AdminQueueIndex} + \field{AdminQueueNum} - 1) inclusive serve
+    as administration virtqueues.
+    The value 0 indicates no supported administration virtqueues.
+    This register is valid only if VIRTIO_F_ADMIN_VQ has been negotiated.
+    See \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}.
+  }
+  \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.
@@ -467,6 +487,29 @@ \subsubsection{Administration Virtqueues}\label{sec:Virtio Transport Options / V
 This range is located beyond the indices of all other virtqueues of
 the device.
 
+A device that supports administration virtqueues offers the
+VIRTIO_F_ADMIN_VQ feature bit. If VIRTIO_F_ADMIN_VQ has been
+negotiated, the device reports the index of the first administration
+virtqueue in \field{AdminQueueIndex} and the number of administration
+virtqueues in \field{AdminQueueNum}.
+
+The driver typically discovers and initializes the administration
+virtqueues in the following way:
+
+\begin{enumerate}
+\item Negotiate VIRTIO_F_ADMIN_VQ as part of the feature negotiation.
+
+\item Read \field{AdminQueueIndex} and \field{AdminQueueNum}.
+   If \field{AdminQueueNum} is zero (0x0), the device does not support
+   any administration virtqueues.
+
+\item For each administration virtqueue the driver intends to use,
+   select a virtqueue index in the range \field{AdminQueueIndex} to
+   \field{AdminQueueIndex} + \field{AdminQueueNum} - 1 inclusive, and
+   configure the virtqueue as described in
+   \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Virtqueue Configuration}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Virtqueue Configuration}.
+\end{enumerate}
+
 \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}
 
 The legacy MMIO transport used page-based addressing, resulting
-- 
2.43.0