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. Field name vqn in the driver notification structure is
ambiguous as it is supposed to hold either vq index or device
supplied vq config data.
4. Device is really supplying queue identifier or a opaque data 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_config_data.
e. rename vqn to vq_notify_config_data 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_config_data
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
patch-11 for virtio-net to update cvq notifications coalescing commands
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---
changelog:
v16->v17:
- improved item name
- dropped to itemize two normatives as it reads odd in the pdf at start
v15->v16:
- rewrote vq index range for better reading
- fixed adding article
- replaced is with was
- fixed incorrect type of 'not'
- replaced receive virtqueue with receive virtqueue id
v14->v15:
- added RB and ack tag from Halil to several patches
- fixed next listed comments from Michael and Halil
- renamed notifications-pci-le.c to notifications-data-le.c
- removed unwanted \item tag
- fixed white spaces at the end of lines
- address next comment from Michael and Halil
- changed description of unclassified_queue to use 'specifies'
v13->v14:
- added Halil's RB tag
- added pci transport specific union structure
- added normative lines for case when VIRTIO_F_NOTIF_CONFIG_DATA
is not negotiated.
- added normataive lines for clarify bit-width for driver notification
- replace left over _id with _config_data
- use _notif_config_data name to align to feature name
v12->v13:
- renamed queue_notify_id to queue_notify_config_data
- added patch to cover notifications coalescing commands after rebase
- fixed left out virtqueue number to virtqueue index
- dropped abbreviation of virtqueue to vq
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 (11):
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
virtio-net: Update vqn to vq_index for cvq cmds
content.tex | 21 ++++++---
device-types/net/description.tex | 53 ++++++++++++++---------
notifications-be.c | 2 +-
notifications-data-le.c | 8 ++++
notifications-le.c | 2 +-
transport-ccw.tex | 15 ++++---
transport-mmio.tex | 55 ++++++++++++++----------
transport-pci.tex | 73 +++++++++++++++++++++++---------
8 files changed, 151 insertions(+), 78 deletions(-)
create mode 100644 notifications-data-le.c
--
2.26.2