[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [PATCH v17 03/11] content: Rename confusing queue_notify_data and vqn names
Parav Pandit <parav@nvidia.com> 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 <pasic@linux.ibm.com> > Signed-off-by: Parav Pandit <parav@nvidia.com> > Reviewed-by: David Edmondson <david.edmondson@oracle.com> > --- > changelog: > v16->v17: > - improved item name > - dropped suggestion to itemize two normatives as it reads odd in pdf > v15->v16: > - fixed adding article > - replaced is with was > - fixed incorrect type of 'not' > 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 | 71 ++++++++++++++++++++++++++++++----------- > 5 files changed, 70 insertions(+), 24 deletions(-) > create mode 100644 notifications-data-le.c > > diff --git a/content.tex b/content.tex > index 9cf938c..327926f 100644 > --- a/content.tex > +++ b/content.tex > @@ -405,8 +405,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 a 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. > + > +The notification method and suppling any 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: > @@ -417,7 +421,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 or vq_notif_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..aa9842f 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 > + the 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 was 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} > +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,30 @@ \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 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 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 -- You know it's not the twilight zone.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]