[PATCH 0/6] transport-mmio: Support administration virtqueues

[PATCH 0/6] transport-mmio: Support administration virtqueues

[Parav Pandit]

Administration virtqueues and group administration commands are
defined in a transport independent way, but only the PCI transport
describes how a device exposes administration virtqueues. For
MMIO, VIRTIO_F_ADMIN_VQ is listed as reserved for future use.

Group administration commands for the Self group type, such as device
capabilities and device resource objects, are equally useful for
memory mapped virtio devices. This series adds administration
virtqueue support to the MMIO transport. Only the Self group type is
applicable to MMIO.

Two read-only registers are added in the unused range between
QueueReset and ConfigGeneration, mirroring the PCI admin_queue_index
and admin_queue_num fields:

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

Their presence is indicated by VIRTIO_F_ADMIN_VQ, so no new MMIO
Version is required and existing devices and drivers are unaffected.
Administration virtqueues are configured, enabled, reset and notified
like any other virtqueue.

Patch summary:
1. Introduce administration virtqueues for the MMIO transport, limited
   to the Self group type.
2. Add the AdminQueueIndex and AdminQueueNum registers.
3. Remove VIRTIO_F_ADMIN_VQ from the MMIO reserved features and update
   the feature bit description.
4. Reference the transport specific discovery from the generic
   administration virtqueues section.
5. Add the missing PCI driver requirement for admin_queue_index and
   admin_queue_num, which the spec already describes as valid only if
   VIRTIO_F_ADMIN_VQ has been negotiated.
6. Add MMIO device and driver requirements and conformance references.

Parav Pandit (6):
  transport-mmio: Introduce administration virtqueues
  transport-mmio: Add administration virtqueue registers
  transport-mmio: Remove ADMIN_VQ from features reserved for future use
  admin: Reference transport specific administration virtqueue discovery
  transport-pci: Add missing driver requirement for admin queue fields
  transport-mmio: Add administration virtqueue requirements

 admin.tex          |  6 ++-
 conformance.tex    |  2 +
 content.tex        |  3 ++
 transport-mmio.tex | 96 ++++++++++++++++++++++++++++++++++++++++------
 transport-pci.tex  |  3 ++
 5 files changed, 97 insertions(+), 13 deletions(-)

-- 
2.43.0

[PATCH 1/6] transport-mmio: Introduce administration virtqueues

[Parav Pandit]

Administration virtqueues and group administration commands are
defined in a transport independent way, but so far only the PCI
transport describes how a device exposes administration virtqueues.

As the first step towards supporting them over MMIO, describe how
administration virtqueues fit into the MMIO transport: they are
regular virtqueues identified by an index, which are configured,
enabled, reset and notified like any other virtqueue, and which occupy
a contiguous range of indices beyond all other virtqueues.

Only the Self group type is applicable to the MMIO transport; state
this explicitly.

Subsequent patches add the registers to discover the administration
virtqueues and the related requirements.

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

diff --git a/transport-mmio.tex b/transport-mmio.tex
index cddbcc9..e015bd7 100644
--- a/transport-mmio.tex
+++ b/transport-mmio.tex
@@ -446,6 +446,27 @@ \subsubsection{Notifications From The Device}\label{sec:Virtio Transport Options
 it by writing a bit mask corresponding to the handled events to the
 InterruptACK register.
 
+\subsubsection{Administration Virtqueues}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}
+
+A memory mapped virtio device can expose one or more administration
+virtqueues (see
+\ref{sec:Basic Facilities of a Virtio Device / Administration Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Administration Virtqueues}),
+which the driver uses to submit group administration commands (see
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands}~\nameref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands}).
+
+Only group administration commands of the Self group type are
+applicable to a memory mapped virtio device.
+
+An administration virtqueue is a virtqueue like any other: it is
+identified by its virtqueue index and
+the driver configures, enables, resets and notifies it using the same
+registers and procedures as for any other virtqueue of the device, see
+\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}.
+
+The device reports a contiguous range of administration virtqueues.
+This range is located beyond the indices of all other virtqueues of
+the device.
+
 \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

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

[Parav Pandit]

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

[PATCH 3/6] transport-mmio: Remove ADMIN_VQ from features reserved for future use

[Parav Pandit]

Commit a9a59f70be46 ("mmio: document ADMIN_VQ as reserved") listed
VIRTIO_F_ADMIN_VQ as reserved for devices and drivers using the MMIO
transport, because MMIO had no registers to expose administration
virtqueues.

Now that the MMIO transport defines AdminQueueIndex and AdminQueueNum,
VIRTIO_F_ADMIN_VQ is no longer reserved for MMIO. Remove it from the
MMIO list of features reserved for future use; as it was the only
entry, remove the whole section.

Also update the VIRTIO_F_ADMIN_VQ description to state that the feature
is supported for both the PCI and the MMIO transports, and remains
reserved for other transports.

Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 content.tex        |  3 +++
 transport-mmio.tex | 12 ------------
 2 files changed, 3 insertions(+), 12 deletions(-)

diff --git a/content.tex b/content.tex
index 243ce2d..3af0b30 100644
--- a/content.tex
+++ b/content.tex
@@ -935,6 +935,9 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
   At the moment this feature is only supported for devices using
   \ref{sec:Virtio Transport Options / Virtio Over PCI
 	  Bus}~\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus}
+	  or
+  \ref{sec:Virtio Transport Options / Virtio Over
+	  MMIO}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO}
 	  as the transport and is reserved for future use for
 	  devices using other transports (see
 	  \ref{drivernormative:Basic Facilities of a Virtio Device / Feature Bits}
diff --git a/transport-mmio.tex b/transport-mmio.tex
index 3c5aa6b..c537e85 100644
--- a/transport-mmio.tex
+++ b/transport-mmio.tex
@@ -664,15 +664,3 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
 \end{enumerate}
 
 Notification mechanisms did not change.
-
-\subsection{Features reserved for future use}\label{sec:Virtio Transport Options / Virtio Over MMIO / Features reserved for future use}
-
-Devices and drivers utilizing Virtio Over MMIO
-do not support the following features:
-\begin{itemize}
-
-\item VIRTIO_F_ADMIN_VQ
-
-\end{itemize}
-
-These features are reserved for future use.
-- 
2.43.0

[PATCH 4/6] admin: Reference transport specific administration virtqueue discovery

[Parav Pandit]

The administration virtqueues section states that the number and
locations of administration virtqueues are exposed in a transport
specific manner, without pointing to where this is described.

Now that both the PCI and the MMIO transports describe it, add
references to the respective transport sections.

Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 admin.tex | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/admin.tex b/admin.tex
index cfca5e3..a639c17 100644
--- a/admin.tex
+++ b/admin.tex
@@ -493,7 +493,11 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic
 If VIRTIO_F_ADMIN_VQ has been negotiated, an owner device exposes one
 or more administration virtqueues. The number and locations of the
 administration virtqueues are exposed by the owner device in a transport
-specific manner.
+specific manner, see
+\ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}~\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
+for the PCI transport and
+\ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}
+for the MMIO transport.
 
 The driver enqueues requests to an arbitrary administration
 virtqueue, and they are used by the device on that same
-- 
2.43.0

[PATCH 5/6] transport-pci: Add missing driver requirement for admin queue fields

[Parav Pandit]

The description of admin_queue_index and admin_queue_num in the common
configuration structure already states that these fields are valid
only if VIRTIO_F_ADMIN_VQ has been negotiated. However, the
corresponding driver requirement was missing from the normative
statements.

Add this missing requirement: the driver must not access
admin_queue_index and admin_queue_num unless VIRTIO_F_ADMIN_VQ has
been negotiated. This does not change the existing behaviour; it only
captures what was already part of the specification as a normative
statement, and aligns the PCI transport with the equivalent MMIO
transport requirement for AdminQueueIndex and AdminQueueNum.

Fixes: 677aeaebf6a7 ("pci: add admin vq registers to virtio over pci")
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 transport-pci.tex | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/transport-pci.tex b/transport-pci.tex
index 95b08b8..0cd9eab 100644
--- a/transport-pci.tex
+++ b/transport-pci.tex
@@ -523,6 +523,9 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
 were used before the queue reset.
 (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}).
 
+The driver MUST NOT access \field{admin_queue_index} and
+\field{admin_queue_num} unless VIRTIO_F_ADMIN_VQ has been negotiated.
+
 If VIRTIO_F_ADMIN_VQ has been negotiated, and if the driver
 configures any administration virtqueues, the driver MUST
 configure the administration virtqueues using the index
-- 
2.43.0

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

[Parav Pandit]

Add device and driver normative statements for administration
virtqueues over the MMIO transport, and reference them from the MMIO
device and driver conformance clauses.

Device requirements:
- AdminQueueIndex is beyond all other virtqueues.

Driver requirements:
- AdminQueueIndex and AdminQueueNum are only accessed when
  VIRTIO_F_ADMIN_VQ has been negotiated, so that drivers never read
  these registers on devices which do not implement them.
- Administration virtqueues are configured only within the reported
  range; the driver may use fewer than supported, same as for PCI.

Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 conformance.tex    |  2 ++
 transport-mmio.tex | 20 ++++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/conformance.tex b/conformance.tex
index 9af31e2..b1dd83a 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -132,6 +132,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout}
 \item \ref{drivernormative:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}
 \item \ref{drivernormative:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Notifications From The Device}
+\item \ref{drivernormative:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}
 \end{itemize}
 
 \conformance{\subsection}{Channel I/O Driver Conformance}\label{sec:Conformance / Driver Conformance / Channel I/O Driver Conformance}
@@ -224,6 +225,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 
 \begin{itemize}
 \item \ref{devicenormative:Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout}
+\item \ref{devicenormative:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}
 \end{itemize}
 
 \conformance{\subsection}{Channel I/O Device Conformance}\label{sec:Conformance / Device Conformance / Channel I/O Device Conformance}
diff --git a/transport-mmio.tex b/transport-mmio.tex
index c537e85..40fda97 100644
--- a/transport-mmio.tex
+++ b/transport-mmio.tex
@@ -510,6 +510,26 @@ \subsubsection{Administration Virtqueues}\label{sec:Virtio Transport Options / V
    \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}
 
+\devicenormative{\paragraph}{Administration Virtqueues}{Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}
+
+If VIRTIO_F_ADMIN_VQ has been negotiated, the device MUST present
+in \field{AdminQueueIndex} a value which is bigger than the index of
+any virtqueue of the device that is not an administration virtqueue.
+
+\drivernormative{\paragraph}{Administration Virtqueues}{Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Administration Virtqueues}
+
+The driver MUST NOT access \field{AdminQueueIndex} and
+\field{AdminQueueNum} unless VIRTIO_F_ADMIN_VQ has been negotiated.
+
+If VIRTIO_F_ADMIN_VQ has been negotiated, and if the driver
+configures any administration virtqueues, the driver MUST
+configure the administration virtqueues using the index
+in the range \field{AdminQueueIndex} to
+\field{AdminQueueIndex} + \field{AdminQueueNum} - 1 inclusive.
+
+The driver MAY configure fewer administration virtqueues than
+supported by the device.
+
 \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

Re: [PATCH 0/6] transport-mmio: Support administration virtqueues

[Michael S. Tsirkin]

On Sat, Oct 17, 2026 at 02:45:50PM +0300, Parav Pandit wrote:
> Administration virtqueues and group administration commands are
> defined in a transport independent way, but only the PCI transport
> describes how a device exposes administration virtqueues. For
> MMIO, VIRTIO_F_ADMIN_VQ is listed as reserved for future use.
> 
> Group administration commands for the Self group type, such as device
> capabilities and device resource objects, are equally useful for
> memory mapped virtio devices. This series adds administration
> virtqueue support to the MMIO transport. Only the Self group type is
> applicable to MMIO.
> 
> Two read-only registers are added in the unused range between
> QueueReset and ConfigGeneration, mirroring the PCI admin_queue_index
> and admin_queue_num fields:
> 
>   AdminQueueIndex (0x0c4) - index of the first administration virtqueue
>   AdminQueueNum   (0x0c8) - number of administration virtqueues
> 
> Their presence is indicated by VIRTIO_F_ADMIN_VQ, so no new MMIO
> Version is required and existing devices and drivers are unaffected.
> Administration virtqueues are configured, enabled, reset and notified
> like any other virtqueue.
> 
> Patch summary:
> 1. Introduce administration virtqueues for the MMIO transport, limited
>    to the Self group type.
> 2. Add the AdminQueueIndex and AdminQueueNum registers.
> 3. Remove VIRTIO_F_ADMIN_VQ from the MMIO reserved features and update
>    the feature bit description.
> 4. Reference the transport specific discovery from the generic
>    administration virtqueues section.
> 5. Add the missing PCI driver requirement for admin_queue_index and
>    admin_queue_num, which the spec already describes as valid only if
>    VIRTIO_F_ADMIN_VQ has been negotiated.
> 6. Add MMIO device and driver requirements and conformance references.


Thanks, will review. We also need ccw please.

> Parav Pandit (6):
>   transport-mmio: Introduce administration virtqueues
>   transport-mmio: Add administration virtqueue registers
>   transport-mmio: Remove ADMIN_VQ from features reserved for future use
>   admin: Reference transport specific administration virtqueue discovery
>   transport-pci: Add missing driver requirement for admin queue fields
>   transport-mmio: Add administration virtqueue requirements
> 
>  admin.tex          |  6 ++-
>  conformance.tex    |  2 +
>  content.tex        |  3 ++
>  transport-mmio.tex | 96 ++++++++++++++++++++++++++++++++++++++++------
>  transport-pci.tex  |  3 ++
>  5 files changed, 97 insertions(+), 13 deletions(-)
> 
> -- 
> 2.43.0