Re: [virtio-comment] [PATCH v8 4/8] transport-mmio: Refer to the vq by its number

[David Edmondson <david.edmondson@oracle.com>]

Parav Pandit <parav@nvidia.com> writes:

> Currently specification uses virtqueue index and
> number interchangeably to refer to the virtqueue.
>
> Instead refer to it by its number.
>
> 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:
> v6->v7:
> - remove text around first vq as it is already covered in the basic
>   virtqueues facility section
> ---
>  transport-mmio.tex | 21 ++++++++-------------
>  1 file changed, 8 insertions(+), 13 deletions(-)
>
> diff --git a/transport-mmio.tex b/transport-mmio.tex
> index 3047633..2aa6627 100644
> --- a/transport-mmio.tex
> +++ b/transport-mmio.tex
> @@ -108,13 +108,12 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
>      bits accessible by writing to \field{DriverFeatures}.
>    }
>    \hline
> -  \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{%
> +  \mmioreg{QueueSel}{Virtual queue number}{0x030}{W}{%
>      Writing to this register selects the virtual queue that the
>      following operations on \field{QueueSizeMax},
>      \field{QueueSize}, \field{QueueReady},
>      \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh},
> -    \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index
> -    number of the first queue is zero (0x0).
> +    \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to.
>    }
>    \hline
>    \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
> @@ -149,7 +148,7 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi
>      there are new buffers to process in a queue.
>  
>      When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
> -    the value written is the queue index.
> +    the value written is the queue number.

Should "queue number" become "virtqueue number" everywhere?

Perhaps the introduction should indicate that "queue number" is another
term for "virtqueue number".

>  
>      When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
>      the \field{Notification data} value has the following format:
> @@ -363,8 +362,7 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir
>  The driver will typically initialize the virtual queue in the following way:
>  
>  \begin{enumerate}
> -\item Select the queue writing its index (first queue is 0) to
> -   \field{QueueSel}.
> +\item Select the queue writing its number to \field{QueueSel}.

s/queue/queue by/

>  
>  \item Check if the queue is not already in use: read \field{QueueReady},
>     and expect a returned value of zero (0x0).
> @@ -392,7 +390,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 the queue to be notified to \field{QueueNotify}.
>  
>  When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
> @@ -470,13 +468,11 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
>      (see QueuePFN).
>    }
>    \hline
> -  \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{%
> +  \mmioreg{QueueSel}{Virtual queue number}{0x030}{W}{%
>      Writing to this register selects the virtual queue that the
>      following operations on the \field{QueueSizeMax},
>      \field{QueueSize}, \field{QueueAlign}
> -    and \field{QueuePFN} registers apply to. The index
> -    number of the first queue is zero (0x0).
> -.
> +    and \field{QueuePFN} registers apply to.
>    }
>    \hline
>    \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
> @@ -550,8 +546,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M
>  
>  The virtual queue is configured as follows:
>  \begin{enumerate}
> -\item Select the queue writing its index (first queue is 0) to
> -   \field{QueueSel}.
> +\item Select the queue writing its number to \field{QueueSel}.

s/queue/queue by/

>  
>  \item Check if the queue is not already in use: read \field{QueuePFN},
>     expecting a returned value of zero (0x0).
> -- 
> 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/
-- 
I move with the movement and I have the touch.