Rename queue index to queue number
v8 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:
a. Use virtqueue number description, and rename MMIO register as QueueSize. b. Replace virtqueue index to virtqueue number
c. RSS area of virtio net has inherited some logic, describe it using abstract rq_handle.
Patch summary:
patch-1 introduce vq number as generic term
patch-2 renames index to number for pci transport patch-3 renames mmio register from Num to Size
patch-4 renames index to number for mmio transport patch-5 renames num field to size for ccw transport patch-6 renames index field to queue_select for ccw transport patch-7 for virtio-net removes duplicate example from requirements patch-8 for virtio-net updates rss description to use vq number
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: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 oddv6->v7:
- remove text around first vq as it is already covered in the basic virtqueues facility sectionv5->v6:
- moved the vq number description from middle of vq operation to beginning of vq introductionv4->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 explanatoryv3->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_idv2->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 (8):
content: Add vq number text
transport-pci: Refer to the vq by its number
transport-mmio: Rename QueueNum register
transport-mmio: Refer to the vq by its number
transport-ccw: Rename queue depth/size to other transports
transport-ccw: Refer to the vq by its number
virtio-net: Avoid duplicate receive queue example
virtio-net: Describe RSS using rss rq id
content.tex | 3 ++ device-types/net/description.tex | 28 ++++++++++---- transport-ccw.tex | 27 ++++++++------ transport-mmio.tex | 63 ++++++++++++++++++-------------- transport-pci.tex | 14 ++++--- 5 files changed, 82 insertions(+), 53 deletions(-)
Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
PATCH v8 1/8 content: Add vq number text
Introduce vq number and its range so that subsequent patches can refer to it.
---
changelog:v5->v6:
- moved description close to introduction, it was in middle of queue data transfer descriptionv2->v3:
- new patch
--- content.tex | 3 +++ 1 file changed, 3 insertions(+)
content.tex +3 -0
@@ -298,6 +298,9 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues} virtqueues\footnote{For example, the simplest network device has one virtqueue for transmit and one for receive.}. +Each virtqueue is identified by a vq number or also referred +to as a virtqueue number; vq number range is from 0 to 65535. + Driver makes requests available to device by adding an available buffer to the queue, i.e., adding a buffer describing the request to a virtqueue, and optionally triggering
Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
[virtio-comment] Re: [virtio-dev] [PATCH v8 1/8] content: Add vq number text
Quoted 21 lines · Parav Pandit
Introduce vq number and its range so that subsequent patches can refer to it.
Signed-off-by Parav Pandit <[email protected]>---
changelog:v5->v6:
- moved description close to introduction, it was in middle of queue data transfer descriptionv2->v3:
- new patch--- content.tex | 3 +++ 1 file changed, 3 insertions(+)content.tex +0
-0
content.tex \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues} · line 303
Quoted 6 lines
content.tex +3
-0@@ -298,6 +298,9 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues} virtqueues\footnote{For example, the simplest network device has one virtqueue for transmit and one for receive.}. +Each virtqueue is identified by a vq number or also referred +to as a virtqueue number; vq number range is from 0 to 65535. +
It would be nice to use the unabbreviated version first, and we could also include "vqn", as it's in use during discussions:
Each virtqueue is identified by a virtqueue number, also referred to as a vq number or vqn. The range of virtqueue numbers is 0 to 65535 inclusive.
Quoted 10 lines
content.tex +0
-0Driver makes requests available to device by adding an available buffer to the queue, i.e., adding a buffer describing the request to a virtqueue, and optionally triggeringSignature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Signature · 17 lines
The sound of a barking dog on a loop, a plane rises in the crystal blue. 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/
RE: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/8] content: Add vq number text
Quoted 30 lines
From: [email protected] <[email protected] open.org> On Behalf Of David Edmondson
Quoted 23 lines · Parav Pandit
Introduce vq number and its range so that subsequent patches can refer to it.
Signed-off-by Parav Pandit <[email protected]>---
changelog:v5->v6:
- moved description close to introduction, it was in middle of queue data transfer descriptionv2->v3:
- new patch--- content.tex | 3 +++ 1 file changed, 3 insertions(+)content.tex +0
-0@@ -298,6 +298,9 @@ \section{Virtqueues}\label{sec:Basic Facilities ofa Virtio Device / Virtqueues} virtqueues\footnote{For example, the simplest network device has one virtqueue for transmit and one for receive.}.
Quoted 7 lines
content.tex
Quoted 3 lines
content.tex +3
-0+Each virtqueue is identified by a vq number or also referred to as a +virtqueue number; vq number range is from 0 to 65535. +It would be nice to use the unabbreviated version first, and we could also include "vqn", as it's in use during discussions:
I prefer vq number first, as reader can pick that first when using somewhere else.
Quoted 3 lines
Each virtqueue is identified by a virtqueue number, also referred to as a vq number or vqn. The range of virtqueue numbers is 0 to 65535 inclusive.
"inclusive" is important to add.
Will add to v9.
Quoted 20 lines
Quoted 11 lines
Driver makes requests available to device by adding an available
buffer to the queue, i.e., adding a buffer describing the request to a virtqueue, and optionally triggering
--
2.26.2---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]--
The sound of a barking dog on a loop, a plane rises in the crystal blue.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.
Quoted 8 lines
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/
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
PATCH v8 2/8 transport-pci: 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
---
changelog: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 oddv2->v3:
- addressed comments from Michael
- changed vqn to virtqueue number in the Note
- refer to vqn field instead of virtqueue number
--- transport-pci.tex | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)
transport-pci.tex +8 -6
@@ -390,13 +390,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport \item[\field{queue_notify_data}] This field exists only if VIRTIO_F_NOTIF_CONFIG_DATA has been negotiated. - The driver will use this value to put it in the 'virtqueue number' field - in the available buffer notification structure. + The driver will use this value to put it in the field + \field{vqn} in the available buffer notification + structure. See section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Available Buffer Notifications}. \begin{note} This field provides the device with flexibility to determine how virtqueues will be referred to in available buffer notifications. - In a trivial case the device can set \field{queue_notify_data}=vqn. Some devices + In a trivial case the device can set + \field{queue_notify_data} to the vq number. Some devices may benefit from providing another value, for example an internal virtqueue identifier, or an internal offset related to the virtqueue number. \end{note}
@@ -1005,7 +1007,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 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 +1037,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 +1055,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 · 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/
[virtio-comment] Re: [virtio-dev] [PATCH v8 2/8] transport-pci: Refer to the vq by its number
Quoted 34 lines · Parav Pandit
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
Reviewed-by Max Gurtovoy <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Signed-off-by Parav Pandit <[email protected]>---
changelog: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
- rewordedqueue_notificationdata set line, as '=' and vq number wording was oddv2->v3:
- addressed comments from Michael
- changed vqn to virtqueue number in the Note
- refer to vqn field instead of virtqueue number--- transport-pci.tex | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)transport-pci.tex +0
-0
transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 395
Quoted 8 lines
transport-pci.tex +3
-2@@ -390,13 +390,15 @@ \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport \item[\field{queue_notify_data}] This field exists only if VIRTIO_F_NOTIF_CONFIG_DATA has been negotiated. - The driver will use this value to put it in the 'virtqueue number' field - in the available buffer notification structure. + The driver will use this value to put it in the field + \field{vqn} in the available buffer notification + structure.
The language here is a bit odd. Suggest:
The driver will use this value in the \field{vqn} field of the available buffer notification structure.
Quoted 44 lines
transport-pci.tex +5
-4See section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Available Buffer Notifications}. \begin{note} This field provides the device with flexibility to determine how virtqueues will be referred to in available buffer notifications. - In a trivial case the device can set \field{queue_notify_data}=vqn. Some devices + In a trivial case the device can set + \field{queue_notify_data} to the vq number. Some devices may benefit from providing another value, for example an internal virtqueue identifier, or an internal offset related to the virtqueue number. \end{note}@@ -1005,7 +1007,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 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 +1037,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 +1055,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 · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Signature · 17 lines
At least they're not lonely. 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/
PATCH v8 3/8 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.
---
changelog:v0->v1:
- replaced references of QueueNumMax to QueueSizeMax
- replaced references of QueueNum to QueueSize
- added note for renamed fields old name suggested by @Michael Tsirkin
--- transport-mmio.tex | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-)
transport-mmio.tex +28 -14
@@ -110,24 +110,31 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on \field{QueueNumMax}, \field{QueueNum}, \field{QueueReady}, + following operations on \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index 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}. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \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 writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{%
@@ -308,11 +315,11 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi Before writing to the \field{DriverFeatures} register, the driver MUST write a value to the \field{DriverFeaturesSel} register. -The driver MUST write a value to \field{QueueNum} which is less than -or equal to the value presented by the device in \field{QueueNumMax}. +The driver MUST write a value to \field{QueueSize} which is less than +or equal to the value presented by the device in \field{QueueSizeMax}. When \field{QueueReady} is not zero, the driver MUST NOT access -\field{QueueNum}, \field{QueueDescLow}, \field{QueueDescHigh}, +\field{QueueSize}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh}. To stop using the queue the driver MUST write zero (0x0) to this
@@ -363,14 +370,14 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir and expect a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue memory, making sure the memory is physically contiguous. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Write physical addresses of the queue's Descriptor Area, Driver Area and Device Area to (respectively) the
@@ -465,25 +472,32 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on the \field{QueueNumMax}, \field{QueueNum}, \field{QueueAlign} + following operations on the \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueAlign} and \field{QueuePFN} registers apply to. The index 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 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} and is allowed only when \field{QueuePFN} is set to zero (0x0), so when the queue is not actively used. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \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 writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueAlign}{Used Ring alignment in the virtual queue}{0x03c}{W}{%
@@ -543,16 +557,16 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M expecting a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue pages in contiguous virtual memory, aligning the Used Ring to an optimal boundary (usually page size). The driver should choose a queue size smaller than or - equal to \field{QueueNumMax}. + equal to \field{QueueSizeMax}. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Notify the device about the used alignment by writing its value in bytes to \field{QueueAlign}.
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/
Re: [virtio-comment] [PATCH v8 3/8] transport-mmio: Rename QueueNum register
Quoted 43 lines · Parav Pandit
Currently 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.
Reviewed-by Jiri Pirko <[email protected]>Signed-off-by Parav Pandit <[email protected]>---
changelog:v0->v1:
- replaced references of QueueNumMax to QueueSizeMax
- replaced references of QueueNum to QueueSize
- added note for renamed fields old name suggested by @Michael Tsirkin--- transport-mmio.tex | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-)transport-mmio.tex +2
-1@@ -110,24 +110,31 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on \field{QueueNumMax}, \field{QueueNum}, \field{QueueReady}, + following operations on \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index number of the first queue is zero (0x0).
transport-mmio.tex \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi · line 126
Quoted 10 lines
transport-mmio.tex +3
-1} \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}. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax.
Use \field for the old name (and in other places).
Quoted 122 lines
transport-mmio.tex +23
-12+ \end{note} } \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 writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{%@@ -308,11 +315,11 @@ \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi Before writing to the \field{DriverFeatures} register, the driver MUST write a value to the \field{DriverFeaturesSel} register. -The driver MUST write a value to \field{QueueNum} which is less than -or equal to the value presented by the device in \field{QueueNumMax}. +The driver MUST write a value to \field{QueueSize} which is less than +or equal to the value presented by the device in \field{QueueSizeMax}. When \field{QueueReady} is not zero, the driver MUST NOT access -\field{QueueNum}, \field{QueueDescLow}, \field{QueueDescHigh}, +\field{QueueSize}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverLow}, \field{QueueDriverHigh}, \field{QueueDeviceLow}, \field{QueueDeviceHigh}. To stop using the queue the driver MUST write zero (0x0) to this@@ -363,14 +370,14 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir and expect a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue memory, making sure the memory is physically contiguous. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Write physical addresses of the queue's Descriptor Area, Driver Area and Device Area to (respectively) the@@ -465,25 +472,32 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the - following operations on the \field{QueueNumMax}, \field{QueueNum}, \field{QueueAlign} + following operations on the \field{QueueSizeMax}, + \field{QueueSize}, \field{QueueAlign} and \field{QueuePFN} registers apply to. The index 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 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} and is allowed only when \field{QueuePFN} is set to zero (0x0), so when the queue is not actively used. + \begin{note} + \field{QueueSizeMax} was previously known as QueueNumMax. + \end{note} } \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 writing to \field{QueueSel}. + \begin{note} + \field{QueueSize} was previously known as QueueNum. + \end{note} } \hline \mmioreg{QueueAlign}{Used Ring alignment in the virtual queue}{0x03c}{W}{%@@ -543,16 +557,16 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M expecting a returned value of zero (0x0). \item Read maximum queue size (number of elements) from - \field{QueueNumMax}. If the returned value is zero (0x0) the + \field{QueueSizeMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue pages in contiguous virtual memory, aligning the Used Ring to an optimal boundary (usually page size). The driver should choose a queue size smaller than or - equal to \field{QueueNumMax}. + equal to \field{QueueSizeMax}. \item Notify the device about the queue size by writing the size to - \field{QueueNum}. + \field{QueueSize}. \item Notify the device about the used alignment by writing its value in bytes to \field{QueueAlign}.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/
Signature · 17 lines
I didn't get a lot in class, but I know it don't come in a shot glass. 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/
PATCH v8 4/8 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.
---
changelog:v6->v7:
- remove text around first vq as it is already covered in the basic virtqueues facility section
--- transport-mmio.tex | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-)
transport-mmio.tex +8 -13
@@ -108,13 +108,12 @@ \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{QueueSizeMax}, \field{QueueSize}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh}, - \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index - number of the first queue is zero (0x0). + \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. } \hline \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
@@ -149,7 +148,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:
@@ -363,8 +362,7 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir The driver will typically initialize the virtual queue in the following way: \begin{enumerate} -\item Select the queue writing its index (first queue is 0) to - \field{QueueSel}. +\item Select the queue writing its number to \field{QueueSel}. \item Check if the queue is not already in use: read \field{QueueReady}, and expect a returned value of zero (0x0).
@@ -392,7 +390,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,
@@ -470,13 +468,11 @@ \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{QueueSizeMax}, \field{QueueSize}, \field{QueueAlign} - and \field{QueuePFN} registers apply to. The index - number of the first queue is zero (0x0). -. + and \field{QueuePFN} registers apply to. } \hline \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
@@ -550,8 +546,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M The virtual queue is configured as follows: \begin{enumerate} -\item Select the queue writing its index (first queue is 0) to - \field{QueueSel}. +\item Select the queue writing its number to \field{QueueSel}. \item Check if the queue is not already in use: read \field{QueuePFN}, expecting a returned value of zero (0x0).
Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Re: [virtio-comment] [PATCH v8 4/8] transport-mmio: Refer to the vq by its number
Quoted 39 lines · Parav Pandit
Currently specification uses virtqueue index and
number interchangeably to refer to the virtqueue.Instead refer to it by its number.
Reviewed-by Jiri Pirko <[email protected]>Signed-off-by Parav Pandit <[email protected]>---
changelog:v6->v7:
- remove text around first vq as it is already covered in the basic virtqueues facility section--- transport-mmio.tex | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-)transport-mmio.tex +2
-3@@ -108,13 +108,12 @@ \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{QueueSizeMax}, \field{QueueSize}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueDriverlLow}, \field{QueueDriverHigh}, - \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. The index - number of the first queue is zero (0x0). + \field{QueueDeviceLow}, \field{QueueDeviceHigh} and \field{QueueReset} apply to. } \hline \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
transport-mmio.tex \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Vi · line 151
Quoted 5 lines
transport-mmio.tex +1
-1@@ -149,7 +148,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.
Should "queue number" become "virtqueue number" everywhere?
Perhaps the introduction should indicate that "queue number" is another term for "virtqueue number".
transport-mmio.tex \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir · line 365
Quoted 10 lines
transport-mmio.tex +1
-2When VIRTIO_F_NOTIFICATION_DATA has been negotiated, the \field{Notification data} value has the following format:@@ -363,8 +362,7 @@ \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Vir The driver will typically initialize the virtual queue in the following way: \begin{enumerate} -\item Select the queue writing its index (first queue is 0) to - \field{QueueSel}. +\item Select the queue writing its number to \field{QueueSel}.
s/queue/queue by/
Quoted 29 lines
transport-mmio.tex +3
-5\item Check if the queue is not already in use: read \field{QueueReady}, and expect a returned value of zero (0x0).@@ -392,7 +390,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,@@ -470,13 +468,11 @@ \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{QueueSizeMax}, \field{QueueSize}, \field{QueueAlign} - and \field{QueuePFN} registers apply to. The index - number of the first queue is zero (0x0). -. + and \field{QueuePFN} registers apply to. } \hline \mmioreg{QueueSizeMax}{Maximum virtual queue size}{0x034}{R}{%
transport-mmio.tex \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M · line 549
Quoted 6 lines
transport-mmio.tex +1
-2@@ -550,8 +546,7 @@ \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over M The virtual queue is configured as follows: \begin{enumerate} -\item Select the queue writing its index (first queue is 0) to - \field{QueueSel}. +\item Select the queue writing its number to \field{QueueSel}.
s/queue/queue by/
Quoted 22 lines
transport-mmio.tex +0
-0\item Check if the queue is not already in use: read \field{QueuePFN}, expecting a returned value of zero (0x0).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/
Signature · 17 lines
I move with the movement and I have the touch. 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/
PATCH v8 5/8 transport-ccw: Rename queue depth/size to other transports
In reply to Parav Panditmax_num field reflects the maximum queue size/depth. Hence align name of this field with similar field in PCI and MMIO transport to max_queue_size.
Similarly rename 'num' to 'size'.
---v3->v4:
- moved note to comment
--- transport-ccw.tex | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)
transport-ccw.tex +8 -6
@@ -237,12 +237,12 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir \begin{lstlisting} struct vq_config_block { be16 index; - be16 max_num; + be16 max_queue_size; /* Previously named as max_num */ }; \end{lstlisting} The requested number of buffers for queue \field{index} is returned in -\field{max_num}. +\field{max_queue_size}. Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the device about the location used for its queue. The transmitted
@@ -253,7 +253,7 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir be64 desc; be32 res0; be16 index; - be16 num; + be16 size; /* Previously named as num */ be64 driver; be64 device; };
@@ -262,7 +262,8 @@ \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 -virtqueue size (number of allocated buffers) is transmitted in \field{num}. +virtqueue size (number of allocated buffers) is transmitted in +\field{size}. \devicenormative{\paragraph}{Configuring a Virtqueue}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue}
@@ -278,11 +279,12 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir be64 queue; be32 align; be16 index; - be16 num; + be16 size; /* Previously named as num */ }; \end{lstlisting} -\field{queue} contains the guest address for queue \field{index}, \field{num} the number of buffers +\field{queue} contains the guest address for queue \field{index}, +\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}. \subsubsection{Communicating Status Information}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information}
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/
Re: [virtio-comment] [PATCH v8 5/8] transport-ccw: Rename queue depth/size to other transports
Quoted 20 lines · Parav Pandit
max_numfield reflects the maximum queue size/depth. Hence align name of this field with similar field in PCI and MMIO transport tomax_queue_size.
Similarly rename 'num' to 'size'.Signed-off-by Parav Pandit <[email protected]>---
v3->v4:
- moved note to comment--- transport-ccw.tex | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)transport-ccw.tex +0
-0
transport-ccw.tex \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir · line 240
Quoted 5 lines
transport-ccw.tex +1
-1@@ -237,12 +237,12 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir \begin{lstlisting} struct vq_config_block { be16 index; - be16 max_num; + be16 max_queue_size; /* Previously named as max_num */
"named as" doesn't feel like typical language use - you can remove "as", though I'd be inclined to use some kind of decoration for the name:
/* Previously named 'max_num'. */
Quoted 62 lines
transport-ccw.tex +7
-5}; \end{lstlisting} The requested number of buffers for queue \field{index} is returned in -\field{max_num}. +\field{max_queue_size}. Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the device about the location used for its queue. The transmitted@@ -253,7 +253,7 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir be64 desc; be32 res0; be16 index; - be16 num; + be16 size; /* Previously named as num */ be64 driver; be64 device; };@@ -262,7 +262,8 @@ \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 -virtqueue size (number of allocated buffers) is transmitted in \field{num}. +virtqueue size (number of allocated buffers) is transmitted in +\field{size}. \devicenormative{\paragraph}{Configuring a Virtqueue}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue}@@ -278,11 +279,12 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir be64 queue; be32 align; be16 index; - be16 num; + be16 size; /* Previously named as num */ }; \end{lstlisting} -\field{queue} contains the guest address for queue \field{index}, \field{num} the number of buffers +\field{queue} contains the guest address for queue \field{index}, +\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}. \subsubsection{Communicating Status Information}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information}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/
Signature · 5 lines
Slow me down, it's getting away from me. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
RE: [virtio-comment] [PATCH v8 5/8] transport-ccw: Rename queue depth/size to other transports
Quoted 16 lines
From: David Edmondson <[email protected]>
Sent: Tuesday, March 28, 2023 10:07 AMtransport-ccw.tex \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir · line 240
Quoted 8 lines
transport-ccw.tex +0
-0@@ -237,12 +237,12 @@ \subsubsection{Configuring aVirtqueue}\label{sec:Virtio Transport Options / Vir
\begin{lstlisting} struct vq_config_block { be16 index;transport-ccw.tex +1
-1- be16 max_num; + be16 max_queue_size; /* Previously named as max_num */"named as" doesn't feel like typical language use - you can remove "as", though I'd be inclined to use some kind of decoration for the name:
Quoted 4 lines
/* Previously named '
max_num'. */Quoted 2 lines
};
\end{lstlisting}
I really don't see any value in putting this change log material in the spec section, But anyways, Michael finds its useful for some users,
So how about,
/* Previously known as max_num. */
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/
RE: [virtio-comment] [PATCH v8 5/8] transport-ccw: Rename queue depth/size to other transports
Quoted 19 lines · Parav Pandit
Quoted 14 lines
From: David Edmondson <[email protected]>
Sent: Tuesday, March 28, 2023 10:07 AMtransport-ccw.tex \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir · line 240
Quoted 8 lines
transport-ccw.tex +0
-0@@ -237,12 +237,12 @@ \subsubsection{Configuring aVirtqueue}\label{sec:Virtio Transport Options / Vir
\begin{lstlisting} struct vq_config_block { be16 index;transport-ccw.tex +1
-1- be16 max_num; + be16 max_queue_size; /* Previously named as max_num */"named as" doesn't feel like typical language use - you can remove "as", though I'd be inclined to use some kind of decoration for the name:
Quoted 4 lines
/* Previously named '
max_num'. */Quoted 2 lines
};
\end{lstlisting}
Quoted 6 lines
I really don't see any value in putting this change log material in the spec section, But anyways, Michael finds its useful for some users,
So how about,
/* Previously known as
max_num. */
Seems fine.
Signature · 17 lines
And now I know what every step is for. 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/
RE: [virtio-comment] [PATCH v8 5/8] transport-ccw: Rename queue depth/size to other transports
Quoted 8 lines
From: David Edmondson <[email protected]>
Sent: Tuesday, March 28, 2023 12:17 PMQuoted 3 lines
So how about,
/* Previously known as
max_num. */Seems fine.
Ok. Thanks.
I agree to most of the other comments.
This is coalesced ack to rest of the patches. :)
Addressing them in v9 shortly.
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/
PATCH v8 6/8 transport-ccw: 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.
---
changelog:v3->v4:
- moved note to commentv2->v3:
- added comment note for queue_select similar to max_queue_size v0->v1:
- new patch
--- transport-ccw.tex | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
transport-ccw.tex +8 -7
@@ -236,12 +236,12 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir \begin{lstlisting} struct vq_config_block { - be16 index; + be16 queue_select; /* Previously named as index */ be16 max_queue_size; /* Previously named as max_num */ }; \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}. Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the
@@ -252,7 +252,7 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir struct vq_info_block { be64 desc; be32 res0; - be16 index; + be16 queue_select; /* Previously named as index */ be16 size; /* Previously named as num */ be64 driver; be64 device;
@@ -261,7 +261,7 @@ \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}.
@@ -278,12 +278,13 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir struct vq_info_block_legacy { be64 queue; be32 align; - be16 index; + be16 queue_select; /* Previously named as index */ be16 size; /* Previously named as num */ }; \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}.
@@ -571,7 +572,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}
Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
PATCH v8 7/8 virtio-net: Avoid duplicate receive queue example
In reply to Parav PanditReceive queue number/index example is duplicate which is already defined in the Setting RSS parameters section.
Hence, avoid such duplicate example and prepare it for the subsequent patch to describe using receive queue handle.
--- device-types/net/description.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
device-types/net/description.tex +2 -2
@@ -1467,8 +1467,8 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi The device MUST determine the destination queue for a network packet as follows: \begin{itemize} \item Calculate the hash of the packet as defined in \ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}. -\item If the device did not calculate the hash for the specific packet, the device directs the packet to the receiveq specified by \field{unclassified_queue} of virtio_net_rss_config structure (value of 0 corresponds to receiveq1). -\item Apply \field{indirection_table_mask} to the calculated hash and use the result as the index in the indirection table to get 0-based number of destination receiveq (value of 0 corresponds to receiveq1). +\item If the device did not calculate the hash for the specific packet, the device directs the packet to the receiveq specified by \field{unclassified_queue} of virtio_net_rss_config structure. +\item Apply \field{indirection_table_mask} to the calculated hash and use the result as the index in the indirection table to get 0-based number of destination receiveq. \item If the destination receive queue is being reset (See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}), the device MUST drop the packet. \end{itemize}
Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
PATCH v8 8/8 virtio-net: Describe RSS using rss rq id
In reply to Parav PanditThe content of indirection table and unclassified_queue which are based on math calculation historically. To better describe this, to avoid intermixing array index with virtqueue index and to use virtqueue number
introduce a field rq_handle (receive queue handle) and refer them to describe unclassified_queue and indirection_table fields.
As part of it, have the example that uses non zero virtqueue number which helps to have better mapping between receiveX object with virtqueue number and the actual value in the indirection table.
---
changelog:v4->v5:
- change subject to reflect rss_rq_id
- fixed accidental removal of "unclassifed packets".
- simplfied text around indirection_table mask to use the term destination receive virtqueue. This aligns with next line about queue reset.
- removed rss_rq_id references as indirection table and unclassified_queue data type is self explanatoryv3->v4:
- renamed rq_handle to rss_rq_id
- moved rss_rq_id definition close to its usage in rss_config struct v2->v3:
- moved rq_handle definition before using it
- removed duplicate example as rq_handle is now described first v0->v1:
- new patch suggested by Michael Tsirkin
--- device-types/net/description.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-)
device-types/net/description.tex +19 -7
@@ -1423,11 +1423,16 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi Driver sends a VIRTIO_NET_CTRL_MQ_RSS_CONFIG command using the following format for \field{command-specific-data}: \begin{lstlisting} +struct rss_rq_id { + le16 vqn_1_16: 15; /* Bits 1 to 16 of the virtqueue number */ + le16 reserved: 1; /* Set to zero */ +}; + struct virtio_net_rss_config { le32 hash_types; le16 indirection_table_mask; - le16 unclassified_queue; - le16 indirection_table[indirection_table_length]; + struct rss_rq_id unclassified_queue; + struct rss_rq_id indirection_table[indirection_table_length]; le16 max_tx_vq; u8 hash_key_length; u8 hash_key_data[hash_key_length];
@@ -1442,10 +1447,14 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \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{rss_rq_id} is a receive virtqueue id. \field{vqn_1_16} +consists of bits 1 to 16 of virtqueue number. For example, +\field{vqn_1_16} value of 3 corresponds to virtqueue number 6 maps to receiveq4. + +Field \field{unclassified_queue} contains the receive virtqueue +to place unclassified packets in. -Field \field{indirection_table} contains an array of 0-based indices of receive virtqueues. Index 0 corresponds to receiveq1. +Field \field{indirection_table} is an array of receive virtqueues. 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}).
@@ -1455,7 +1464,8 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi A driver MUST NOT send the VIRTIO_NET_CTRL_MQ_RSS_CONFIG command if the feature VIRTIO_NET_F_RSS has not been negotiated. -A driver MUST fill the \field{indirection_table} array only with indices of enabled queues. Index 0 corresponds to receiveq1. +A driver MUST fill the \field{indirection_table} array only with +enabled receive virtqueues. The number of entries in \field{indirection_table} (\field{indirection_table_mask} + 1) MUST be a power of two.
@@ -1468,7 +1478,9 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \begin{itemize} \item Calculate the hash of the packet as defined in \ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}. \item If the device did not calculate the hash for the specific packet, the device directs the packet to the receiveq specified by \field{unclassified_queue} of virtio_net_rss_config structure. -\item Apply \field{indirection_table_mask} to the calculated hash and use the result as the index in the indirection table to get 0-based number of destination receiveq. +\item Apply \field{indirection_table_mask} to the calculated hash +and use the result as the index in the indirection table to get +the destination receive virtqueue. \item If the destination receive queue is being reset (See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}), the device MUST drop the packet. \end{itemize}
Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
[virtio-comment] Re: [virtio-dev] [PATCH v8 8/8] virtio-net: Describe RSS using rss rq id
Quoted 62 lines · Parav Pandit
The content of indirection table and
unclassified_queuewhich are based on math calculation historically. To better describe this, to avoid intermixing array index with virtqueue index and to use virtqueue numberintroduce a field
rq_handle(receive queue handle) and refer them to describeunclassified_queueandindirection_tablefields.As part of it, have the example that uses non zero virtqueue number which helps to have better mapping between receiveX object with virtqueue number and the actual value in the indirection table.
Signed-off-by Parav Pandit <[email protected]>---
changelog:v4->v5:
- change subject to reflectrss_rq_id
- fixed accidental removal of "unclassifed packets".
- simplfied text aroundindirection_tablemask to use the term destination receive virtqueue. This aligns with next line about queue reset.
- removedrss_rq_idreferences as indirection table andunclassified_queuedata type is self explanatoryv3->v4:
- renamedrq_handletorss_rq_id
- movedrss_rq_iddefinition close to its usage inrss_configstructv2->v3:
- movedrq_handledefinition before using it
- removed duplicate example asrq_handleis now described firstv0->v1:
- new patch suggested by Michael Tsirkin--- device-types/net/description.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-)device-types/net/description.tex +7
-2@@ -1423,11 +1423,16 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi Driver sends a VIRTIO_NET_CTRL_MQ_RSS_CONFIG command using the following format for \field{command-specific-data}: \begin{lstlisting} +struct rss_rq_id { + le16 vqn_1_16: 15; /* Bits 1 to 16 of the virtqueue number */ + le16 reserved: 1; /* Set to zero */ +}; + struct virtio_net_rss_config { le32 hash_types; le16 indirection_table_mask; - le16 unclassified_queue; - le16 indirection_table[indirection_table_length]; + struct rss_rq_id unclassified_queue; + struct rss_rq_id indirection_table[indirection_table_length]; le16 max_tx_vq; u8 hash_key_length; u8 hash_key_data[hash_key_length];
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1452
Quoted 8 lines
device-types/net/description.tex +3
-2@@ -1442,10 +1447,14 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \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{rss_rq_id} is a receive virtqueue id. \field{vqn_1_16} +consists of bits 1 to 16 of virtqueue number. For example, +\field{vqn_1_16} value of 3 corresponds to virtqueue number 6 maps to receiveq4.
\field{rss_rq_id} is a receive virtqueue id. \field{vqn_1_16} consists of bits 1 to 16 of a virtqueue number. For example, a \field{vqn_1_16} value of 3 corresponds to virtqueue number 6, which maps to receiveq4.
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1455
Quoted 3 lines
device-types/net/description.tex +3
-0+ +Field \field{unclassified_queue} contains the receive virtqueue +to place unclassified packets in.
Field \field{unclassified_queue} contains the receive virtqueue in which to place unclassified packets.
Quoted 33 lines
device-types/net/description.tex +6
-3-Field \field{indirection_table} contains an array of 0-based indices of receive virtqueues. Index 0 corresponds to receiveq1. +Field \field{indirection_table} is an array of receive virtqueues. 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}).@@ -1455,7 +1464,8 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi A driver MUST NOT send the VIRTIO_NET_CTRL_MQ_RSS_CONFIG command if the feature VIRTIO_NET_F_RSS has not been negotiated. -A driver MUST fill the \field{indirection_table} array only with indices of enabled queues. Index 0 corresponds to receiveq1. +A driver MUST fill the \field{indirection_table} array only with +enabled receive virtqueues. The number of entries in \field{indirection_table} (\field{indirection_table_mask} + 1) MUST be a power of two.@@ -1468,7 +1478,9 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \begin{itemize} \item Calculate the hash of the packet as defined in \ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}. \item If the device did not calculate the hash for the specific packet, the device directs the packet to the receiveq specified by \field{unclassified_queue} of virtio_net_rss_config structure. -\item Apply \field{indirection_table_mask} to the calculated hash and use the result as the index in the indirection table to get 0-based number of destination receiveq. +\item Apply \field{indirection_table_mask} to the calculated hash +and use the result as the index in the indirection table to get +the destination receive virtqueue. \item If the destination receive queue is being reset (See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}), the device MUST drop the packet. \end{itemize}Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Signature · 17 lines
Tonight I think I'll walk alone, I'll find my soul as I go home. 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/
Quoted 2 lines · Parav Pandit
1. Currently, virtqueue is identified between driver and device interchangeably using either number of index terminology.
"number or index"
Quoted 5 lines
2. Between PCI and MMIO transport the queue size (depth) is defined as
queue_sizeand QueueNum respectively.To avoid confusion and to have consistency, unify them to use as Number.
s/as//
Quoted 4 lines
Solution:
a. Use virtqueue number description, and rename MMIO register as QueueSize. b. Replace virtqueue index to virtqueue number
s/to/with/
Quoted 81 lines
c. RSS area of virtio net has inherited some logic, describe it using abstract
rq_handle.Patch summary:
patch-1 introduce vq number as generic term
patch-2 renames index to number for pci transport patch-3 renames mmio register from Num to Size
patch-4 renames index to number for mmio transport patch-5 renames num field to size for ccw transport patch-6 renames index field toqueue_selectfor ccw transport patch-7 for virtio-net removes duplicate example from requirements patch-8 for virtio-net updates rss description to use vq numberThis 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: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
- rewordedqueue_notificationdata set line, as '=' and vq number wording was oddv6->v7:
- remove text around first vq as it is already covered in the basic virtqueues facility sectionv5->v6:
- moved the vq number description from middle of vq operation to beginning of vq introductionv4->v5:
- fixed accidental removal of "unclassifed packets".
- simplfied text aroundindirection_tablemask
- removedrss_rq_idreferences as indirection table andunclassified_queuedata type is self explanatoryv3->v4:
- moved note to comment for ccw
- renamedrq_handletorss_rq_id
- movedrss_rq_idnext torss_configstructure
- definerss_configstructure usingrss_rq_idv2->v3:
- addressed comments from Michael
- added previous definitions for ccw fields
- movedrq_handledefinition before using it
- added first patch to describe vq number
- updated pci for available buffer notification sectionv1->v2:
- added patches for virtio net for rss area
- added patches for covering ccw transport
- added missing entries to refer in mmio transportParav Pandit (8):
content: Add vq number text
transport-pci: Refer to the vq by its number
transport-mmio: Rename QueueNum register
transport-mmio: Refer to the vq by its number
transport-ccw: Rename queue depth/size to other transports
transport-ccw: Refer to the vq by its number
virtio-net: Avoid duplicate receive queue example
virtio-net: Describe RSS using rss rq idcontent.tex | 3 ++ device-types/net/description.tex | 28 ++++++++++---- transport-ccw.tex | 27 ++++++++------ transport-mmio.tex | 63 ++++++++++++++++++-------------- transport-pci.tex | 14 ++++--- 5 files changed, 82 insertions(+), 53 deletions(-)Signature · 6 lines
2.26.2 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Signature · 17 lines
When the laugh track starts then the fun starts. 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/