[PATCH v2] virtio-net: Add support for the flexible driver notification

[Vitaly Mireyno <vmireyno@marvell.com>]

Currently, the driver notification (available buffer notification) has a fixed structure.
If VIRTIO_F_NOTIFICATION_DATA has been negotiated, it includes: vqn, next_off and next_wrap.
If notify_off_multiplier > 0, the VQ number can be derived by the device from the Queue Notify address, so vqn may be redundant.

Some devices benefit from receiving an additional data with driver notifications. This data can optionally replace the vqn field in the driver notification structure.
In its simplest form, it would be sufficient for this data to be a per-device constant value.

Changes from v1 - added more details about motivation and usage examples.

Signed-off-by: Vitaly Mireyno <vmireyno@marvell.com>
---
 content.tex | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/content.tex b/content.tex
index b91a132..5abff30 100644
--- a/content.tex
+++ b/content.tex
@@ -965,6 +965,9 @@ \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options
 struct virtio_pci_notify_cap {
         struct virtio_pci_cap cap;
         le32 notify_off_multiplier; /* Multiplier for queue_notify_off. */
+        le16 notify_data; /* Data to be placed in the vqn field */
+        u8 notify_data_valid;
+        u8 padding; /* Pad to a dword */
 };
 \end{lstlisting}
 
@@ -984,6 +987,20 @@ \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options
 the same Queue Notify address for all queues.
 \end{note}
 
+If \field{notify_data_valid} != 0, the driver will set the \field{vqn} field
+in the available buffer notification structure to the \field{notify_data} value.
+
+\begin{note}
+If \field{notify_off_multiplier} > 0, the virtqueue number can potentially be
+derived by the device from the Queue Notify address, so \field{vqn} may be
+redundant. Some devices benefit from receiving the additional data with driver
+notifications. An example could be a hardware device implementing multiple
+protocols (with virtio being one of them), so extra notification data could serve as
+a notification type indication or a protocol indication.
+Another example could be using shared hardware memory space for driver notifications
+for multiple virtio devices in a trusted environment.
+\end{note}
+
 \devicenormative{\paragraph}{Notification capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 The device MUST present at least one notification capability.
 
@@ -1020,6 +1037,12 @@ \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options
 cap.length >= queue_notify_off * notify_off_multiplier + 4
 \end{lstlisting}
 
+The device MAY set \field{notify_data_valid} to any non-zero value, to request
+the driver to set the \field{vqn} to the \field{notify_data} value.
+If the device sets \field{notify_data_valid} to a non-zero value, it MUST set
+\field{notify_data} to a valid value.
+For a normal operation, the device MUST set \field{notify_data_valid} to zero.
+
 \subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}
 
 The VIRTIO_PCI_CAP_ISR_CFG capability
@@ -1519,6 +1542,11 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
 See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 for how to calculate the Queue Notify address.
 
+\drivernormative{\paragraph}{Available Buffer Notifications}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Available Buffer Notifications}
+If VIRTIO_F_NOTIFICATION_DATA has been negotiated, and if
+\field{notify_data_valid} != 0, the driver MUST set the \field{vqn} field of
+the available buffer notification structure to the \field{notify_data} value.
+
 \subsubsection{Used Buffer Notifications}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Used Buffer Notifications}
 
 If a used buffer notification is necessary for a virtqueue, the device would typically act as follows:
--