From: Parav Pandit <parav@nvidia.com>
To: <mst@redhat.com>, <virtio-dev@lists.oasis-open.org>, <cohuck@redhat.com>
Cc: <sgarzare@redhat.com>, <pasic@linux.ibm.com>,
<virtio-comment@lists.oasis-open.org>, <shahafs@nvidia.com>,
Parav Pandit <parav@nvidia.com>
Subject: [virtio-dev] [PATCH v14 03/11] content: Rename confusing queue_notify_data and vqn names
Date: Wed, 19 Apr 2023 04:46:31 +0300 [thread overview]
Message-ID: <20230419014639.919458-4-parav@nvidia.com> (raw)
In-Reply-To: <20230419014639.919458-1-parav@nvidia.com>
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_notif_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.
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/163
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
changelog:
v13->v14:
- added pci transport specific union structure
- added normative lines for case when VIRTIO_F_NOTIF_CONFIG_DATA
is not negotiated.
- added normataive lines for clarify bit-width for driver notification
- replace left over _id with _config_data
- use _notif_config_data name to align to feature name
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 +-
notifications-pci-le.c | 8 +++++
transport-pci.tex | 72 +++++++++++++++++++++++++++++++-----------
5 files changed, 71 insertions(+), 24 deletions(-)
create mode 100644 notifications-pci-le.c
diff --git a/content.tex b/content.tex
index e79d722..e1345ea 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 config data if
+VIRTIO_F_NOTIF_CONFIG_DATA is negotiated.
+
+A notification method and suppling such virtqueue notification config 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..bf6d1cd 100644
--- a/notifications-be.c
+++ b/notifications-be.c
@@ -1,5 +1,5 @@
be32 {
- vqn : 16;
+ vq_index: 16; /* previously known as vqn */
next_off : 15;
next_wrap : 1;
};
diff --git a/notifications-le.c b/notifications-le.c
index fe51267..8a19389 100644
--- a/notifications-le.c
+++ b/notifications-le.c
@@ -1,5 +1,5 @@
le32 {
- vqn : 16;
+ vq_index: 16; /* previously known as vqn */
next_off : 15;
next_wrap : 1;
};
diff --git a/notifications-pci-le.c b/notifications-pci-le.c
new file mode 100644
index 0000000..ef60d15
--- /dev/null
+++ b/notifications-pci-le.c
@@ -0,0 +1,8 @@
+le32 {
+ union {
+ vq_index: 16; /* Used if VIRTIO_F_NOTIF_CONFIG_DATA not negotiated */
+ vq_notif_config_data: 16; /* Used if VIRTIO_F_NOTIF_CONFIG_DATA negotiated */
+ };
+ next_off : 15;
+ next_wrap : 1;
+};
diff --git a/transport-pci.tex b/transport-pci.tex
index 5d98467..04a9a80 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_notif_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_notif_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_notif_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_notif_config_data}.
If VIRTIO_F_RING_PACKED has been negotiated,
the driver MUST NOT write the value 0 to \field{queue_size}.
@@ -1035,13 +1041,22 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
the driver sends an available buffer notification to the device by writing
-the 16-bit virtqueue index
-of this virtqueue to the Queue Notify address.
+only the 16-bit notification value to the Queue Notify address of the
+virtqueue. A notification value depends on the negotiation of
+VIRTIO_F_NOTIF_CONFIG_DATA.
-When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
-the driver sends an available buffer notification to the device by writing
-the following 32-bit value to the Queue Notify address:
-\lstinputlisting{notifications-le.c}
+\item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver sends an
+available buffer notification to the device by writing the following 32-bit
+value to the Queue Notify address:
+\lstinputlisting{notifications-pci-le.c}
+
+\begin{itemize}
+\item When VIRTIO_F_NOTIF_CONFIG_DATA is not negotiated \field{vq_index} is set
+to the virtqueue index.
+
+\item When VIRTIO_F_NOTIFICATION_DATA is negotiated,
+\field{vq_notif_config_data} is set to \field{queue_notif_config_data}.
+\end{itemize}
See \ref{sec:Basic Facilities of a Virtio Device / Driver notifications}~\nameref{sec:Basic Facilities of a Virtio Device / Driver notifications}
for the definition of the components.
@@ -1050,12 +1065,31 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
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_NOTIF_CONFIG_DATA has been negotiated:
+
+If VIRTIO_F_NOTIFICATION_DATA is not negotiated, the driver notification
+MUST be a 16-bit notification.
+
+If VIRTIO_F_NOTIFICATION_DATA is negotiated, the driver notification
+MUST be a 32-bit notification.
+
+If VIRTIO_F_NOTIF_CONFIG_DATA is not negotiated:
+\begin{itemize}
+\item If VIRTIO_F_NOTIFICATION_DATA is not negotiated, the driver MUST set the
+notification value to virtqueue index.
+
+\item If VIRTIO_F_NOTIFICATION_DATA is negotiated, the driver MUST set the
+\field{vq_index} to the virtqueue index.
+
+\end{itemize}
+
+If VIRTIO_F_NOTIF_CONFIG_DATA is 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.
-\item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver MUST set the
-\field{vqn} field to the \field{queue_notify_data} value.
+\item If VIRTIO_F_NOTIFICATION_DATA is not negotiated, the driver MUST set
+the notification value to \field{queue_notif_config_data}.
+
+\item If VIRTIO_F_NOTIFICATION_DATA is not negotiated, the driver MUST set the
+\field{vq_notify_config_data} to the \field{queue_notif_config_data}
+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-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
next prev parent reply other threads:[~2023-04-19 1:47 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-19 1:46 [virtio-dev] [PATCH v14 00/11] Rename queue number to queue index Parav Pandit
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 01/11] content: Add vq index text Parav Pandit
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 02/11] content.tex Replace virtqueue number with index Parav Pandit
2023-04-19 16:08 ` [virtio-dev] " Halil Pasic
2023-04-19 16:11 ` [virtio-dev] " Parav Pandit
2023-04-19 1:46 ` Parav Pandit [this message]
2023-04-21 22:37 ` [virtio-dev] Re: [PATCH v14 03/11] content: Rename confusing queue_notify_data and vqn names Halil Pasic
2023-04-24 14:00 ` Michael S. Tsirkin
2023-04-24 16:11 ` [virtio-dev] " Parav Pandit
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 04/11] transport-pci: Avoid first vq index reference Parav Pandit
2023-04-24 13:29 ` [virtio-dev] Re: [virtio-comment] " Halil Pasic
2023-04-25 4:10 ` [virtio-dev] " Parav Pandit
2023-04-25 13:02 ` Halil Pasic
2023-04-25 13:15 ` Michael S. Tsirkin
2023-04-25 16:20 ` Halil Pasic
2023-04-25 21:11 ` Michael S. Tsirkin
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 05/11] transport-mmio: Rename QueueNum register Parav Pandit
2023-04-24 12:53 ` Halil Pasic
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 06/11] transport-mmio: Avoid referring to zero based index Parav Pandit
2023-04-25 10:59 ` [virtio-dev] Re: [virtio-comment] " Halil Pasic
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 07/11] transport-ccw: Rename queue depth/size to other transports Parav Pandit
2023-04-24 12:58 ` Halil Pasic
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 08/11] transport-ccw: Refer to the vq by its index Parav Pandit
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 09/11] virtio-net: Avoid duplicate receive queue example Parav Pandit
2023-04-24 13:10 ` Halil Pasic
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 10/11] virtio-net: Describe RSS using rss rq id Parav Pandit
2023-04-24 13:22 ` [virtio-dev] " Halil Pasic
2023-04-24 13:58 ` Michael S. Tsirkin
2023-04-24 15:30 ` [virtio-dev] " Parav Pandit
2023-04-24 15:54 ` [virtio-dev] " Michael S. Tsirkin
2023-04-24 16:02 ` [virtio-dev] " Parav Pandit
2023-04-19 1:46 ` [virtio-dev] [PATCH v14 11/11] virtio-net: Update vqn to vq_index for cvq cmds Parav Pandit
2023-04-24 13:26 ` Halil Pasic
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230419014639.919458-4-parav@nvidia.com \
--to=parav@nvidia.com \
--cc=cohuck@redhat.com \
--cc=mst@redhat.com \
--cc=pasic@linux.ibm.com \
--cc=sgarzare@redhat.com \
--cc=shahafs@nvidia.com \
--cc=virtio-comment@lists.oasis-open.org \
--cc=virtio-dev@lists.oasis-open.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).