RE: [PATCH v2 7/7] virtio-net: Describe RSS using receive queue handle

[Parav Pandit <parav@nvidia.com>]

> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: Tuesday, March 21, 2023 4:56 AM

[..]
> \field{indirection_table} array.
> >  Number of entries in \field{indirection_table} is
> (\field{indirection_table_mask} + 1).
> >
> > -Field \field{unclassified_queue} contains the 0-based index of -the
> > receive virtqueue to place unclassified packets in. Index 0 corresponds to
> receiveq1.
> > +Field \field{unclassified_queue} contains the receive queue handle
> > +\field{rq_handle} described below.
> >
> > -Field \field{indirection_table} contains an array of 0-based indices of receive
> virtqueues. Index 0 corresponds to receiveq1.
> > +Field \field{indirection_table} contains an array of receive queue
> > +handles described below in \field{rq_handle}.
> 
> 
> This is only used once, here.  I understand that we need a name for this but it
> need not be so generic, I feel it's just confusing.
> I propose "indirection table entry".
> 
Unclassified_queue field also refers to it.
Need to duplicate the below description there too.
So using rq_handle simplified it.
May be it can be duplicated as 
Unclassified_queue consists of vq number value divided by two.

And avoid rq_handle definition.

> Thus:
> 	Field \field{indirection_table} contains an array of
> 	indirection table entries. Each indirection table entry consists of a
> 	vq number value divided by 2. Thus, an entry value of 3 maps to
> virtqueue number 6
> 	which corresponds to receiveq4
> 
> 
> 
> > For example at
> > +array index 0,
> 
> why mention array index here?
> 
Since we are mentioning an indirection table array, referring to an array entry without referring to the array index was little odd.
After reading your above example, it doesn't look that odd.

> > a value of 3 maps to virtqueue number 6
> > +which corresponds to receiveq4.
> 
> It's a good idea to first describe a concept then provide an example.
> 
True, but it was not too far with pointer to describe below.
> 
> >  A driver sets \field{max_tx_vq} to inform a device how many transmit
> virtqueues it may use (transmitq1\ldots transmitq \field{max_tx_vq}).
> >
> >  Fields \field{hash_key_length} and \field{hash_key_data} define the key to be
> used in hash calculation.
> >
> > +\begin{lstlisting}
> > +le16 rq_handle;
> > +\end{lstlisting}
> > +
> > +\field{rq_handle} is a receive virtqueue handle. It is calculated as
> > +virtqueue number divided by 2. For example a receive virtqueue handle
> > +value of 3 corresponds to virtqueue number 6 maps to receiveq4.
> > +
> 
> it's a bit disconnected from the rest of the description. why not adjacent to it?
> 
Sure it can move up before max_tx_vq or before introducing unclassified_queue.

But I guess we can describe by duplicating the text and avoiding rq_handle as you suggest.
Will simplify this in v3.