Re: [PATCH v3 6/8] transport-ccw: Refer to the vq by its number

["Michael S. Tsirkin" <mst@redhat.com>]

On Tue, Mar 21, 2023 at 11:58:32PM +0200, Parav Pandit wrote:
> 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
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> 
> ---
> changelog:
> v2->v3:
> - added comment note for queue_select similar to max_queue_size
> v0->v1:
> - new patch
> ---
>  transport-ccw.tex | 27 ++++++++++++++++++++-------
>  1 file changed, 20 insertions(+), 7 deletions(-)
> 
> diff --git a/transport-ccw.tex b/transport-ccw.tex
> index c2e60b6..880b87f 100644
> --- a/transport-ccw.tex
> +++ b/transport-ccw.tex
> @@ -236,14 +236,18 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
>  
>  \begin{lstlisting}
>  struct vq_config_block {
> -        be16 index;
> +        be16 queue_select;
>          be16 max_queue_size;
>  };
>  \end{lstlisting}
>  
> -The requested number of buffers for queue \field{index} is returned in
> +The requested number of buffers for queue \field{queue_select} is returned in
>  \field{max_queue_size}.
>  
> +\begin{note}
> +\field{queue_select} was previously named as index.

sounds a bit strange, and \field{} is missing. If you insist I'd say
	in previous versions of this specification,
	field{queue_select} was also called queue \field{index}


e.g. in blk we have this:
  In the legacy interface, VIRTIO_BLK_F_FLUSH was also 
  called VIRTIO_BLK_F_WCE.


but I really feel this misses the point, the compat is needed
in the struct definition, not split out after usage
is described. This is why I proposed just making this a comment in the
struct. Why not?



> +\end{note}
> +
>  \begin{note}
>  \field{max_queue_size} was previously named as max_num.
>  \end{note}
> @@ -256,7 +260,7 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
>  struct vq_info_block {
>          be64 desc;
>          be32 res0;
> -        be16 index;
> +        be16 queue_select;
>          be16 size;
>          be64 driver;
>          be64 device;
> @@ -265,10 +269,14 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
>  
>  \field{desc}, \field{driver} and \field{device} contain the guest
>  addresses for the descriptor area,
> -available area and used area for queue \field{index}, respectively. The actual
> +available area and used area for queue number \field{queue_select}, respectively. The actual
>  virtqueue size (number of allocated buffers) is transmitted in
>  \field{size}.
>  
> +\begin{note}
> +\field{queue_select} was previously named as index.
> +\end{note}
> +
>  \begin{note}
>  \field{size} was previously named as num.
>  \end{note}
> @@ -286,15 +294,20 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
>  struct vq_info_block_legacy {
>          be64 queue;
>          be32 align;
> -        be16 index;
> +        be16 queue_select;
>          be16 size;
>  };
>  \end{lstlisting}
>  
> -\field{queue} contains the guest address for queue \field{index},
> +\field{queue} contains the guest address for queue number
> +\field{queue_select},
>  \field{size} the number of buffers
>  and \field{align} the alignment. The queue layout follows \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}.
>  
> +\begin{note}
> +\field{queue_select} was previously named as index.
> +\end{note}
> +
>  \begin{note}
>  \field{size} was previously named as num.
>  \end{note}
> @@ -583,7 +596,7 @@ \subsubsection{Guest->Host Notification}\label{sec:Virtio Transport Options / Vi
>  For example:
>  \begin{lstlisting}
>  info->cookie = do_notify(schid,
> -                         virtqueue_get_queue_index(vq),
> +                         virtqueue_get_queue_number(vq),
>                           info->cookie);
>  \end{lstlisting}
>  \end{note}
> -- 
> 2.26.2