Rename queue index to queue number
cover Rename queue index to queue number
1. Currently, virtqueue is identified between driver and device interchangeably using either number of 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 as Number.
Solution:
Use virtqueue number description, and rename MMIO register as QueueSize.
Patch summary:
patch-1 renames index to number for pci transport patch-2 renames mmio register from Num to Size patch-3 renames index to number for mmio transport
Please review.
This series fixes the issue [1].
This series is on top of [2].
[1] https://github.com/oasis-tcs/virtio-spec/issues/163
[2] https://lists.oasis-open.org/archives/virtio-dev/202302/msg00578.html
changelog:v0->v1:
- rebase on [2]
- added reviewed-by of Jiri
Parav Pandit (3):
transport-pci: Refer to the vq by its number
transport-mmio: Rename QueueNum register
transport-mmio: Refer to the vq by its number
transport-mmio.tex | 16 ++++++++-------- transport-pci.tex | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-)
Signature · 1 line
2.26.2
PATCH 1/3 transport-pci: Refer to the vq by its number
Currently specification uses virtqueue index and
number interchangeably to refer to the virtqueue.
Instead refer to it by its number.
This patch is on top of [1].
[1] https://lists.oasis-open.org/archives/virtio-dev/202302/msg00527.html
--- transport-pci.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
transport-pci.tex +3 -3
@@ -1005,7 +1005,7 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti The driver typically does this as follows, for each virtqueue a device has: \begin{enumerate} -\item Write the virtqueue index (first queue is 0) to \field{queue_select}. +\item Write the virtqueue number (first queue is 0) to \field{queue_select}. \item Read the virtqueue size from \field{queue_size}. This controls how big the virtqueue is (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues}). If this field is 0, the virtqueue does not exist.
@@ -1035,7 +1035,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 this virtqueue to the Queue Notify address. When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
@@ -1053,7 +1053,7 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option If VIRTIO_F_NOTIF_CONFIG_DATA has been negotiated: \begin{itemize} \item If VIRTIO_F_NOTIFICATION_DATA has not been negotiated, the driver MUST use the -\field{queue_notify_data} value instead of the virtqueue index. +\field{queue_notify_data} value instead of the virtqueue number. \item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver MUST set the \field{vqn} field to the \field{queue_notify_data} value. \end{itemize}
Signature · 1 line
2.26.2
PATCH 2/3 transport-mmio: Rename QueueNum register
In reply to Parav PanditCurrently specification uses virtqueue index and number interchangeably to refer to the virtqueue.
It is better to always refer to it the virtqueue in consistent manner.
Two registers QueueNumMax and QueueNum actually reflects the queue size or queue depth indicating max and actual number of entries in the queue.
These are further named differently between pci and mmio transport. PCI transport indicates queue size as queue_size.
To bring consistency between pci and mmio transport, and to avoid confusion between number and index, rename the QueueNumMax and QueueNum registers to QueueSizeMax and QueueSize respectively.
[1] https://lists.oasis-open.org/archives/virtio-dev/202302/msg00527.html
--- transport-mmio.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
transport-mmio.tex +4 -4
@@ -116,14 +116,14 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi number of the first queue is zero (0x0). } \hline - \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% + \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size (number of elements) of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to \field{QueueSel}. } \hline - \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% + \mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by
@@ -471,7 +471,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M . } \hline - \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% + \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to
@@ -479,7 +479,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M (0x0), so when the queue is not actively used. } \hline - \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% + \mmioreg{QueueSize}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by
Signature · 1 line
2.26.2
PATCH 3/3 transport-mmio: Refer to the vq by its number
In reply to Parav PanditCurrently specification uses virtqueue index and
number interchangeably to refer to the virtqueue.
Instead refer to it by its number.
This patch is on top of [1].
[1] https://lists.oasis-open.org/archives/virtio-dev/202302/msg00527.html
--- transport-mmio.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
transport-mmio.tex +4 -4
@@ -108,7 +108,7 @@ \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{QueueNumMax}, \field{QueueNum}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh},
@@ -142,7 +142,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. When VIRTIO_F_NOTIFICATION_DATA has been negotiated, the \field{Notification data} value has the following format:
@@ -385,7 +385,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,
@@ -463,7 +463,7 @@ \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{QueueNumMax}, \field{QueueNum}, \field{QueueAlign} and \field{QueuePFN} registers apply to. The index
Signature · 18 lines
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: [email protected] Unsubscribe: [email protected] List help: [email protected] 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/