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 v13 03/11] content: Rename confusing queue_notify_data and vqn names
Date: Tue, 11 Apr 2023 22:23:33 +0300 [thread overview]
Message-ID: <20230411192341.751841-4-parav@nvidia.com> (raw)
In-Reply-To: <20230411192341.751841-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_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 <parav@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-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-11 19:24 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-11 19:23 [virtio-dev] [PATCH v13 00/11] Rename queue number to queue index Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 01/11] content: Add vq index text Parav Pandit
2023-04-18 14:12 ` [virtio-dev] " Halil Pasic
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 02/11] content.tex Replace virtqueue number with index Parav Pandit
2023-04-11 19:23 ` Parav Pandit [this message]
2023-04-17 3:41 ` [virtio-dev] [PATCH v13 03/11] content: Rename confusing queue_notify_data and vqn names Halil Pasic
2023-04-17 20:53 ` Parav Pandit
2023-04-18 6:04 ` Michael S. Tsirkin
2023-04-18 11:39 ` Halil Pasic
2023-04-18 11:43 ` Michael S. Tsirkin
2023-04-18 12:13 ` Parav Pandit
2023-04-18 12:06 ` Parav Pandit
2023-04-18 12:31 ` [virtio-dev] Re: [virtio-comment] " Cornelia Huck
2023-04-18 13:17 ` Cornelia Huck
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 04/11] transport-pci: Avoid first vq index reference Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 05/11] transport-mmio: Rename QueueNum register Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 06/11] transport-mmio: Avoid referring to zero based index Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 07/11] transport-ccw: Rename queue depth/size to other transports Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 08/11] transport-ccw: Refer to the vq by its index Parav Pandit
2023-04-18 16:54 ` [virtio-dev] " Halil Pasic
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 09/11] virtio-net: Avoid duplicate receive queue example Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 10/11] virtio-net: Describe RSS using rss rq id Parav Pandit
2023-04-11 19:23 ` [virtio-dev] [PATCH v13 11/11] virtio-net: Update vqn to vq_index for cvq cmds Parav Pandit
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=20230411192341.751841-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).