Parav Pandit <[email protected]> writes:
> 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
> Acked-by: Halil Pasic <[email protected]>
> Signed-off-by: Parav Pandit <[email protected]>
>
> ---
> changelog:
> v14->v15:
> - fixed white spaces at the end of lines
> - fixed next listed comments from Michael and Halil
> - renamed notifications-pci-le.c to notifications-data-le.c
> - removed unwanted \item tag
> 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-data-le.c | 8 +++++
> notifications-le.c | 2 +-
> transport-pci.tex | 72 ++++++++++++++++++++++++++++++-----------
> 5 files changed, 71 insertions(+), 24 deletions(-)
> create mode 100644 notifications-data-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
"a" or "the" virtqueue index.
> +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.
"The" notification method. "supplying any such"
>
> 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-data-le.c b/notifications-data-le.c
> new file mode 100644
> index 0000000..3ee80e4
> --- /dev/null
> +++ b/notifications-data-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/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/transport-pci.tex b/transport-pci.tex
> index 524bfff..b292fc3 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 */
"previously known as"?
(I'm not particularly bothered, but if we are going to be consistent, it
should be here.)
> 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,
"the" virtqueue index.
> + 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.
s/is/was/
> \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}
> +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-data-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.
"the" 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
s/not//
> +\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
>
>
> This publicly archived list offers a means to provide input to the
> OASIS Virtual I/O Device (VIRTIO) TC.
>
> In order to verify user consent to the Feedback License terms and
> to minimize spam in the list archive, subscription is required
> before posting.
>
> Subscribe: [email protected]
> Unsubscribe: [email protected]
> List help: [email protected]
> List archive: https://lists.oasis-open.org/archives/virtio-comment/
> Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
> List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
> Committee: https://www.oasis-open.org/committees/virtio/
> Join OASIS: https://www.oasis-open.org/join/
--
This is the time. This is the record of the time.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
