Re: [virtio-comment] [PATCH v5 2/8] transport-pci: Refer to the vq by its number

[Stefano Garzarella <sgarzare@redhat.com>]

On Mon, Mar 27, 2023 at 11:50:07AM +0200, Stefano Garzarella wrote:
> Hi Parav,
>
> On Thu, Mar 23, 2023 at 02:59:38AM +0200, Parav Pandit wrote:
> > Currently specification uses virtqueue index and
> > number interchangeably to refer to the virtqueue.
> >
> > Instead refer to it by its number.
> >
> > This patch is on top of [1].
> >
> > [1] https://lists.oasis-open.org/archives/virtio-dev/202302/msg00527.html
> >
> > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/163
> > Reviewed-by: Jiri Pirko <jiri@nvidia.com>
> > Signed-off-by: Parav Pandit <parav@nvidia.com>
> > ---
> > changelog:
> > v2->v3:
> > - addressed comments from Michael
> > - changed vqn to virtqueue number in the Note
> > - refer to vqn field instead of virtqueue number
> > ---
> > content.tex       |  2 +-
> > transport-pci.tex | 14 ++++++++------
> > 2 files changed, 9 insertions(+), 7 deletions(-)
> >
> > diff --git a/content.tex b/content.tex
> > index 1ab7794..0f634ac 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -321,7 +321,7 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
> > VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge
> > might allow optimizations or simplify driver and/or device code.
> >
> > -Each virtqueue is identified as vq number or also referred
> > +Each virtqueue is identified by a vq number or also referred
>
> Could we merge this change into patch 1?

Ooops, I see now that v6 addressed this.

> Thanks,
> Stefano
>
> > to as a virtqueue number; vq number range is from 0 to 65535.
> >
> > Each virtqueue can consist of up to 3 parts:
> > diff --git a/transport-pci.tex b/transport-pci.tex
> > index b07a822..044c085 100644
> > --- a/transport-pci.tex
> > +++ b/transport-pci.tex
> > @@ -390,13 +390,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport
> >
> > \item[\field{queue_notify_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 to put it in the field
> > +        \field{vqn} in the available buffer notification
> > +        structure.
> >        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
> > +        In a trivial case the device can set
> > +        \field{queue_notify_data}=vq number. Some devices
> >        may benefit from providing another value, for example an internal virtqueue
> >        identifier, or an internal offset related to the virtqueue number.
> >        \end{note}
> > @@ -1005,7 +1007,7 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
> > The driver typically does this as follows, for each virtqueue a device has:
> >
> > \begin{enumerate}
> > -\item Write the virtqueue index (first queue is 0) to \field{queue_select}.
> > +\item Write the virtqueue number (first queue is 0) to \field{queue_select}.
> >
> > \item Read the virtqueue size from \field{queue_size}. This controls how big the virtqueue is
> >  (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues}). If this field is 0, the virtqueue does not exist.
> > @@ -1035,7 +1037,7 @@ \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
> > +the 16-bit virtqueue number
> > of this virtqueue to the Queue Notify address.
> >
> > When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
> > @@ -1053,7 +1055,7 @@ \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_data} value instead of the virtqueue number.
> > \item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver MUST set the
> > \field{vqn} field to the \field{queue_notify_data} value.
> > \end{itemize}
> > --
> > 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: virtio-comment-subscribe@lists.oasis-open.org
> > Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
> > List help: virtio-comment-help@lists.oasis-open.org
> > 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/