[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH 2/4] content: Introduce driver/device aux. notification cfg type for PCI
This includes the PCI device conformances for these notification
capabilities.
Signed-off-by: Usama Arif <usama.arif@bytedance.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Nikos Dragazis <ndragazis@arrikto.com>
---
conformance.tex | 2 +
content.tex | 134 +++++++++++++++++++++++++++++++++++++++++-------
2 files changed, 117 insertions(+), 19 deletions(-)
diff --git a/conformance.tex b/conformance.tex
index 42f8537..cddaf75 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -356,6 +356,8 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}
\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device-specific configuration}
+\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device auxiliary notification capability}
+\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Driver auxiliary notification capability}
\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
\item \ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver}
diff --git a/content.tex b/content.tex
index 85980ac..5430324 100644
--- a/content.tex
+++ b/content.tex
@@ -719,6 +719,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
\item ISR Status
\item Device-specific configuration (optional)
\item PCI configuration access
+\item Driver auxiliary notifications (optional)
+\item Device auxiliary notifications (optional)
\end{itemize}
Each structure can be mapped by a Base Address register (BAR) belonging to
@@ -765,19 +767,23 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option
\begin{lstlisting}
/* Common configuration */
-#define VIRTIO_PCI_CAP_COMMON_CFG 1
+#define VIRTIO_PCI_CAP_COMMON_CFG 1
/* Notifications */
-#define VIRTIO_PCI_CAP_NOTIFY_CFG 2
+#define VIRTIO_PCI_CAP_NOTIFY_CFG 2
/* ISR Status */
-#define VIRTIO_PCI_CAP_ISR_CFG 3
+#define VIRTIO_PCI_CAP_ISR_CFG 3
/* Device specific configuration */
-#define VIRTIO_PCI_CAP_DEVICE_CFG 4
+#define VIRTIO_PCI_CAP_DEVICE_CFG 4
/* PCI configuration access */
-#define VIRTIO_PCI_CAP_PCI_CFG 5
+#define VIRTIO_PCI_CAP_PCI_CFG 5
+/* Device auxiliary notification */
+#define VIRTIO_PCI_CAP_DEVICE_AUX_NOTIFY_CFG 6
+/* Driver auxiliary notification */
+#define VIRTIO_PCI_CAP_DRIVER_AUX_NOTIFY_CFG 7
/* Shared memory region */
-#define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
+#define VIRTIO_PCI_CAP_SHARED_MEMORY_CFG 8
/* Vendor-specific data */
-#define VIRTIO_PCI_CAP_VENDOR_CFG 9
+#define VIRTIO_PCI_CAP_VENDOR_CFG 9
\end{lstlisting}
Any other value is reserved for future use.
@@ -1212,6 +1218,92 @@ \subsubsection{Device-specific configuration}\label{sec:Virtio Transport Options
The \field{offset} for the device-specific configuration MUST be 4-byte aligned.
+\subsubsection{Device auxiliary notification capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device auxiliary notification capability}
+
+The device auxiliary notification \ref{sec:Basic Facilities of a Virtio Device / Notifications}
+location is found using the VIRTIO_PCI_CAP_DEVICE_AUX_NOTIFY_CFG capability. This
+capability is immediately followed by an additional field, like so:
+
+\begin{lstlisting}
+struct virtio_pci_dev_aux_notification_cap {
+ struct virtio_pci_cap cap;
+ le32 dev_aux_notification_off_multiplier;
+};
+\end{lstlisting}
+
+The device auxiliary notification address within a BAR is calculated as follows:
+
+\begin{lstlisting}
+cap.offset + dev_aux_notification_idx * dev_aux_notification_off_multiplier
+\end{lstlisting}
+
+The \field{cap.offset} and \field{dev_aux_notification_off_multiplier} are taken
+from the device auxiliary notification capability structure above, and the
+\field{dev_aux_notification_idx} is the device auxiliary notification index. There is no restriction for
+the mapping between device auxiliary notifications and dev_aux_notification_idx. The mapping is
+device-specific. One possible mapping would be to use the integers 0 to
+N-1 as the device auxiliary notification indices for a total of N device auxiliary notifications.
+The total number of device auxiliary notifications exposed by the device is also device-specific.
+
+\devicenormative{\paragraph}{Device auxiliary notification capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device auxiliary notification capability}
+
+The \field{cap.offset} MUST be 2-byte aligned.
+
+The device MUST either present \field{dev_aux_notification_off_multiplier} as an
+even power of 2, or present \field{dev_aux_notification_off_multiplier} as 0.
+
+The value \field{cap.length} presented by the device MUST be at least 2
+and MUST be large enough to support device auxiliary notification offsets for all supported
+device auxiliary notifications in all possible configurations.
+
+The value \field{cap.length} presented by the device MUST satisfy:
+
+\begin{lstlisting}
+cap.length >= max_dev_aux_notification_idx * dev_aux_notification_off_multiplier + 2
+\end{lstlisting}
+
+where \field{max_dev_aux_notification_idx} is the maximum device auxiliary notification index and is
+dependent on the device.
+
+\subsubsection{Driver auxiliary notification capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Driver auxiliary notification capability}
+
+The Driver auxiliary notification
+\ref{sec:Basic Facilities of a Virtio Device / Notifications} location
+is found using the VIRTIO_PCI_CAP_DRIVER_AUX_NOTIFY_CFG capability. The
+driver auxiliary notification structure allows MSI-X vectors to be
+configured for notification interrupts. If MSI-X is not available, bit 2
+of the ISR status \ref{sec:Virtio Transport Options / Virtio Over PCI
+Bus / PCI Device Layout / ISR status capability} indicates that a
+driver auxiliary notification occurred.
+
+The driver auxiliary notification structure is the following:
+
+\begin{lstlisting}
+struct virtio_pci_driver_aux_notification_cfg {
+ le16 driver_aux_notification_select; /* read-write */
+ le16 driver_aux_notification_msix_vector; /* read-write */
+};
+\end{lstlisting}
+
+The driver indicates which notification is of interest by writing the
+\field{driver_aux_notification_select} field. The driver then writes the MSI-X
+vector or VIRTIO_MSI_NO_VECTOR to \field{driver_aux_notification_msix_vector} to
+change the MSI-X vector for that notification.
+
+The mapping between notifications and notification indices is
+device-specific. The total number of notifications is also
+device-specific.
+
+\devicenormative{\paragraph}{Driver auxiliary notification capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Driver auxiliary notification capability}
+
+Device MUST ignore writes to \field{driver_aux_notification_msix_vector} if the
+value written to \field{driver_aux_notification_select} is not a valid notification
+index.
+
+Device MUST return VIRTIO_MSI_NO_VECTOR for reads from
+\field{driver_aux_notification_msix_vector} if the value written to
+\field{driver_aux_notification_select} is not a valid notification index.
+
\subsubsection{Shared memory capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Shared memory capability}
Shared memory regions \ref{sec:Basic Facilities of a Virtio
@@ -1523,15 +1615,17 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
\paragraph{MSI-X Vector Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration}
When MSI-X capability is present and enabled in the device
-(through standard PCI configuration space) \field{config_msix_vector} and \field{queue_msix_vector} are used to map configuration change and queue
-interrupts to MSI-X vectors. In this case, the ISR Status is unused.
+(through standard PCI configuration space) \field{config_msix_vector},
+\field{queue_msix_vector} and \field{driver_aux_notification_msix_vector} are used
+to map configuration change, queue and device-specific interrupts to
+MSI-X vectors respectively. In this case, the ISR Status is unused.
Writing a valid MSI-X Table entry number, 0 to 0x7FF, to
-\field{config_msix_vector}/\field{queue_msix_vector} maps interrupts triggered
-by the configuration change/selected queue events respectively to
-the corresponding MSI-X vector. To disable interrupts for an
-event type, the driver unmaps this event by writing a special NO_VECTOR
-value:
+\field{config_msix_vector}/\field{queue_msix_vector}/\field{driver_aux_notification_msix_vector}
+maps interrupts triggered by the configuration change/selected
+queue/device-specific events respectively to the corresponding MSI-X
+vector. To disable interrupts for an event type, the driver unmaps this
+event by writing a special NO_VECTOR value:
\begin{lstlisting}
/* Vector value used to disable MSI for queue */
@@ -1558,16 +1652,18 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
vector 0 to MSI-X \field{Table Size}.
Device MUST support unmapping any event type.
-The device MUST return vector mapped to a given event,
-(NO_VECTOR if unmapped) on read of \field{config_msix_vector}/\field{queue_msix_vector}.
-The device MUST have all queue and configuration change
-events are unmapped upon reset.
+The device MUST return the vector mapped to a given event,
+(NO_VECTOR if unmapped) on read of
+\field{config_msix_vector}/\field{queue_msix_vector}/\field{driver_aux_notification_msix_vector}.
+The device MUST have all queue/configuration change/device-specific
+events unmapped upon reset.
Devices SHOULD NOT cause mapping an event to vector to fail
unless it is impossible for the device to satisfy the mapping
request. Devices MUST report mapping
failures by returning the NO_VECTOR value when the relevant
-\field{config_msix_vector}/\field{queue_msix_vector} field is read.
+\field{config_msix_vector}/\field{queue_msix_vector}/\field{driver_aux_notification_msix_vector}
+field is read.
\drivernormative{\subparagraph}{MSI-X Vector Configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration}
--
2.25.1
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]