Currently queue_notify_data register indicates the device
internal queue notification identifier. 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).
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 vq identifier, rename it to queue_notify_id.
Reflect vq identifier in the driver notification structure by renaming
ambiguous vqn to vq_notify_id.
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>
---
Some side notes:
renaming vqn to vqnd is even more confusing because data is really the
queue identifier.
And NOTIFICATION_DATA really contains queue progress info (data).
(vqn - n is number or notification?, notification word in the
notification structure does not make sense).
Hence above renaming.
---
changelog:
v11->v12:
- new patch
---
content.tex | 17 ++++++++++++++---
notifications-be.c | 2 +-
notifications-le.c | 2 +-
transport-pci.tex | 24 ++++++++++++++----------
4 files changed, 30 insertions(+), 15 deletions(-)
diff --git a/content.tex b/content.tex
index cd93db2..d5f8026 100644
--- a/content.tex
+++ b/content.tex
@@ -405,8 +405,18 @@ \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 involves sending only the 16-bit virtqueue notification
+identifier (notification method depends on the transport).
+
+\begin{itemize}
+\item When VIRTIO_F_NOTIF_CONFIG_DATA is not negotiated, virtqueue
+notification identifier is a 16-bit vq index.
+
+\item When VIRTIO_F_NOTIF_CONFIG_DATA is negotiated, virtqueue
+notification identifier is a device supplied virtqueue identifier. A method
+to supply such virtqueue notification identifier is transport
+specific.
+\end{itemize}
However, some devices benefit from the ability to find out the
amount of available data in the queue without accessing the virtqueue in
memory:
@@ -417,7 +427,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_notify_id] VQ notification identifier of a
+ corresponding 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..0a7cbf1 100644
--- a/notifications-be.c
+++ b/notifications-be.c
@@ -1,5 +1,5 @@
be32 {
- vqn : 16;
+ vq_notify_id : 16; /* previously known as vqn */
next_off : 15;
next_wrap : 1;
};
diff --git a/notifications-le.c b/notifications-le.c
index fe51267..6cca8fb 100644
--- a/notifications-le.c
+++ b/notifications-le.c
@@ -1,5 +1,5 @@
le32 {
- vqn : 16;
+ vq_notify_id : 16; /* previously known as vqn */
next_off : 15;
next_wrap : 1;
};
diff --git a/transport-pci.tex b/transport-pci.tex
index 5d98467..6bbf61c 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_id; /* 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_id}]
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_id} to
+ vq 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_id.
\end{note}
\item[\field{queue_reset}]
@@ -468,7 +472,7 @@ \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_id}.
If VIRTIO_F_RING_PACKED has been negotiated,
the driver MUST NOT write the value 0 to \field{queue_size}.
@@ -1053,9 +1057,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
