Currently queue_notify_data register indicates the device
internal queue notification content. This register is
meaningful only when feature bit VIRTIO_F_NOTIF_CONFIG_DATA is
negotiated.
However, above register name often get confusing association with
very similar feature bit VIRTIO_F_NOTIFICATION_DATA.
When VIRTIO_F_NOTIFICATION_DATA feature bit is negotiated,
notification really involves sending additional queue progress
related information (not queue identifier or index).
Hence
1. to avoid any misunderstanding and association of
queue_notify_data with similar name VIRTIO_F_NOTIFICATION_DATA,
and
2. to reflect that queue_notify_data is the actual device
internal virtqueue identifier/index/data/cookie,
a. rename queue_notify_data to queue_notify_config_data.
queue_notify_config_data.
b. rename ambiguous vqn to a union of vq_index and vq_config_data
c. The driver notification section assumes that queue notification contains
vq index always. CONFIG_DATA feature bit introduction missed to
update the driver notification section. Hence, correct it.
Signed-off-by: Parav Pandit <pa...@nvidia.com>
---
changelog:
v12->v13:
- replace _id with _config_data
- dropped vq identifier
- dropped the idea of union as description is for config data feature
v11->v12:
- new patch
---
content.tex | 11 ++++++++---
notifications-be.c | 2 +-
notifications-le.c | 2 +-
transport-pci.tex | 26 ++++++++++++++++----------
4 files changed, 26 insertions(+), 15 deletions(-)
diff --git a/content.tex b/content.tex
index e79d722..601c069 100644
--- a/content.tex
+++ b/content.tex
@@ -404,8 +404,12 @@ \section{Driver Notifications} \label{sec:Basic Facilities
of a Virtio Device /
notification to the device.
When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
-this notification involves sending the
-virtqueue index to the device (method depending on the transport).
+this notification contains either virtqueue
+index if VIRTIO_F_NOTIF_CONFIG_DATA is not negotiated or device
+supplied virtqueue notification data if
+VIRTIO_F_NOTIF_CONFIG_DATA is negotiated.
+
+A method to supply such virtqueue notification data is transport specific.
However, some devices benefit from the ability to find out the
amount of available data in the queue without accessing the virtqueue in
memory:
@@ -416,7 +420,8 @@ \section{Driver Notifications} \label{sec:Basic Facilities
of a Virtio Device /
the following information:
\begin{description}
-\item [vqn] VQ number to be notified.
+\item [vq_index_config_data] either virtqueue index or device supplied
+ queue notification config data corresponding to a virtqueue.
\item [next_off] Offset
within the ring where the next available ring entry
will be written.
diff --git a/notifications-be.c b/notifications-be.c
index 5be947e..02f0624 100644
--- a/notifications-be.c
+++ b/notifications-be.c
@@ -1,5 +1,5 @@
be32 {
- vqn : 16;
+ vq_config_data: 16; /* previously known as vqn */
next_off : 15;
next_wrap : 1;
};
diff --git a/notifications-le.c b/notifications-le.c
index fe51267..f73c6a5 100644
--- a/notifications-le.c
+++ b/notifications-le.c
@@ -1,5 +1,5 @@
le32 {
- vqn : 16;
+ vq_config_data: 16; /* previously known as vqn */
next_off : 15;
next_wrap : 1;
};
diff --git a/transport-pci.tex b/transport-pci.tex
index 5d98467..53c8ee6 100644
--- a/transport-pci.tex
+++ b/transport-pci.tex
@@ -319,7 +319,7 @@ \subsubsection{Common configuration structure
layout}\label{sec:Virtio Transport
le64 queue_desc; /* read-write */
le64 queue_driver; /* read-write */
le64 queue_device; /* read-write */
- le16 queue_notify_data; /* read-only for driver */
+ le16 queue_notify_config_data; /* read-only for driver */
le16 queue_reset; /* read-write */
};
\end{lstlisting}
@@ -388,17 +388,21 @@ \subsubsection{Common configuration structure
layout}\label{sec:Virtio Transport
\item[\field{queue_device}]
The driver writes the physical address of Device Area here. See
section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
-\item[\field{queue_notify_data}]
+\item[\field{queue_notify_config_data}]
This field exists only if VIRTIO_F_NOTIF_CONFIG_DATA has been
negotiated.
- The driver will use this value to put it in the 'virtqueue number'
field
- in the available buffer notification structure.
+ The driver will use this value when driver sends available buffer
+ notification to the device.
See section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus /
PCI-specific Initialization And Device Operation / Available Buffer
Notifications}.
\begin{note}
This field provides the device with flexibility to determine how
virtqueues
will be referred to in available buffer notifications.
- In a trivial case the device can set \field{queue_notify_data}=vqn.
Some devices
- may benefit from providing another value, for example an internal
virtqueue
- identifier, or an internal offset related to the virtqueue number.
+ In a trivial case the device can set \field{queue_notify_config_data}
to
+ virtqueue index. Some devices may benefit from providing another value,
+ for example an internal virtqueue identifier, or an internal offset
+ related to the virtqueue index.
+ \end{note}
+ \begin{note}
+ This field is previously known as queue_notify_data.
\end{note}
\item[\field{queue_reset}]
@@ -468,7 +472,9 @@ \subsubsection{Common configuration structure
layout}\label{sec:Virtio Transport
\drivernormative{\paragraph}{Common configuration structure layout}{Virtio
Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common
configuration structure layout}
-The driver MUST NOT write to \field{device_feature}, \field{num_queues},
\field{config_generation}, \field{queue_notify_off} or
\field{queue_notify_data}.
+The driver MUST NOT write to \field{device_feature}, \field{num_queues},
+\field{config_generation}, \field{queue_notify_off} or
+\field{queue_notify_config_data}.
If VIRTIO_F_RING_PACKED has been negotiated,
the driver MUST NOT write the value 0 to \field{queue_size}.
@@ -1053,9 +1059,9 @@ \subsubsection{Available Buffer
Notifications}\label{sec:Virtio Transport Option
If VIRTIO_F_NOTIF_CONFIG_DATA has been negotiated:
\begin{itemize}
\item If VIRTIO_F_NOTIFICATION_DATA has not been negotiated, the driver MUST
use the
-\field{queue_notify_data} value instead of the virtqueue index.
+\field{queue_notify_id} value instead of the virtqueue index.
\item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver MUST set
the
-\field{vqn} field to the \field{queue_notify_data} value.
+\field{vq_notify_id} field to the \field{queue_notify_id} value.
\end{itemize}
\subsubsection{Used Buffer Notifications}\label{sec:Virtio Transport Options /
Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Used
Buffer Notifications}
--
2.26.2
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
