Re: [PATCH v12 00/10] Rename queue number to queue index

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

On Wed, Apr 05, 2023 at 04:06:47AM +0300, Parav Pandit wrote:
> 1. Currently, virtqueue is identified between driver and device
> interchangeably using either number or index terminology.
> 
> 2. Between PCI and MMIO transport the queue size (depth) is
> defined as queue_size and QueueNum respectively.
> 
> To avoid confusion and to have consistency, unify them to use
> index.
> 
> 3. Filed name vqn in the driver notification structure is
> ambiguous as it is supposed to hold either vq index or device
> supplied vq identifier.
> 
> 4. Device is really supplying queue identifier in the 
> queue_notify_data register, and this often get confused with
> very similar looking feature bit NOTIFICATION_DATA.
> 
> Solution:
> a. Use virtqueue index description, and rename MMIO register as QueueSize.
> b. Replace virtqueue number with virtqueue index
> c. RSS area of virtio net has inherited some logic, describe it
> using abstract rss_rq_id.
> d. rename queue_notifify_data to queue_notify_id
> e. rename vqn to vq_notify_id to reflect it can hold either vq
> index of device supplied some id.
> 
> Patch summary:
> patch-1 introduce vq number as generic term
> patch-2 renames index to number for pci transport
> patch-3 rename queue_notify_data to queue_notify_id
> patch-4 remove first vq index reference
> patch-5 renames mmio register from Num to Size
> patch-6 renames index to number for mmio transport
> patch-7 renames num field to size for ccw transport
> patch-8 renames vq by its index for ccw transport
> patch-9 for virtio-net removes duplicate example from requirements
> patch-10 for virtio-net updates rss description to use vq index
> 
> This series only improves the documentation, it does not change any
> transport or device functionality.
> 
> Please review.
> This series fixes the issue [1].
> 
> [1] https://github.com/oasis-tcs/virtio-spec/issues/163

I feel there are now two patchsets here:
1. renaming of queue num to queue size
2. virtqueue index and rss clarification depending on it

1 seems mostly ready, for 2 I don't yet know how long it will take.
Split them up, also from POV of github issues?


> ---
> changelog:
> v11->v12:
> - replace number to index
> - avoid confusion around vqn field and rename to vq_notify_id
> - rename queue_notify_data to avoid confusing with NOTIFY_DATA
> v10->v11:
> - added Reviewed-by for all the reviewed patches
> - updated commit log of patch-8 to drop rq_handle reference
> - skipped comment to further use rss_rq_id, as rss_rq_id usage
>   and structure are self describing
> v9->v10:
> - added virtqueue number part in content in braces
> - replaced queue_select to vqn in ccw
> - avoided aggrasive alignment of 65 chars
> - updated commit log to drop reference to already merged patches
> - added review-by tag for already reviewed patches
> v8->v9:
> - addressed comments from David
> - few corrections with article
> - renaming 'virtqueue number' to 'vq number'
> - improving text and wording for rss_rq_id, avail notification
> - commit log of specific change in individual patches
> v7->v8:
> - remove note about first virtqueue number
> - skipped Max's comment to put word 'structure' in same line as its
>   crosses 65 chars limit per line
> - reworded queue_notification data set line, as '=' and vq number
>   wording was odd
> v6->v7:
> - remove text around first vq as it is already covered in the basic
>   virtqueues facility section
> v5->v6:
> - moved the vq number description from middle of vq operation
>   to beginning of vq introduction
> v4->v5:
> - fixed accidental removal of "unclassifed packets".
> - simplfied text around indirection_table mask
> - removed rss_rq_id references as indirection table and
>   unclassified_queue data type is self explanatory
> v3->v4:
> - moved note to comment for ccw
> - renamed rq_handle to rss_rq_id
> - moved rss_rq_id next to rss_config structure
> - define rss_config structure using rss_rq_id
> v2->v3:
> - addressed comments from Michael
> - added previous definitions for ccw fields
> - moved rq_handle definition before using it
> - added first patch to describe vq number
> - updated pci for available buffer notification section
> v1->v2:
> - added patches for virtio net for rss area
> - added patches for covering ccw transport
> - added missing entries to refer in mmio transport
> 
> 
> Parav Pandit (10):
>   content: Add vq index text
>   content.tex Replace virtqueue number with index
>   content: Rename confusing queue_notify_data and vqn names
>   transport-pci: Avoid first vq index reference
>   transport-mmio: Rename QueueNum register
>   transport-mmio: Avoid referring to zero based index
>   transport-ccw: Rename queue depth/size to other transports
>   transport-ccw: Refer to the vq by its index
>   virtio-net: Avoid duplicate receive queue example
>   virtio-net: Describe RSS using rss rq id
> 
>  content.tex                      | 27 ++++++++++++----
>  device-types/net/description.tex | 29 ++++++++++++-----
>  notifications-be.c               |  2 +-
>  notifications-le.c               |  2 +-
>  transport-ccw.tex                | 15 +++++----
>  transport-mmio.tex               | 55 +++++++++++++++++++-------------
>  transport-pci.tex                | 26 ++++++++-------
>  7 files changed, 99 insertions(+), 57 deletions(-)
> 
> -- 
> 2.26.2