Skip to contentSkip to conversation

Rename queue index to queue number

PATCH Superseded Parav Pandit 3 participants 14 messages Mar 22, 2023 – Mar 27, 2023

v4 of 17 Superseded Latest is v17 →

lore
Share & tools
lore

Parav Pandit

author
#0 lore raw

v4 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:
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 (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 receive queue handle

 content.tex                      |  3 ++
 device-types/net/description.tex | 29 ++++++++++++-----
 transport-ccw.tex                | 27 ++++++++-------
 transport-mmio.tex               | 56 +++++++++++++++++++-------------
 transport-pci.tex                | 14 ++++----
 5 files changed, 81 insertions(+), 48 deletions(-)
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/
author
#1 lore raw

PATCH v4 1/8 content: Add vq number text

Introduce vq number and its range so that subsequent patches can refer to it.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Signed-off-by Parav Pandit <[email protected]>

---
changelog:
v2->v3:
- new patch

---
 content.tex | 3 +++
 1 file changed, 3 insertions(+)
content.tex +3 -0
index cff548a..1ab7794 100644
@@ -321,6 +321,9 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
 VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge
 might allow optimizations or simplify driver and/or device code.
 
+Each virtqueue is identified as vq number or also referred
+to as a virtqueue number; vq number range is from 0 to 65535.
+
 Each virtqueue can consist of up to 3 parts:
 \begin{itemize}
 \item Descriptor Area - used for describing buffers
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/
author
#2 lore raw

PATCH v4 2/8 transport-pci: Refer to the vq by its number

In reply to 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

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Reviewed-by Jiri Pirko <[email protected]>
Signed-off-by Parav Pandit <[email protected]>

---
changelog:
v2->v3:
- addressed comments from Michael
- changed vqn to virtqueue number in the Note
- refer to vqn field instead of virtqueue number

---
 content.tex       |  2 +-
 transport-pci.tex | 14 ++++++++------
 2 files changed, 9 insertions(+), 7 deletions(-)
content.tex +1 -1
index 1ab7794..0f634ac 100644
@@ -321,7 +321,7 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
 VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge
 might allow optimizations or simplify driver and/or device code.
 
-Each virtqueue is identified as vq number or also referred
+Each virtqueue is identified by a vq number or also referred
 to as a virtqueue number; vq number range is from 0 to 65535.
 
 Each virtqueue can consist of up to 3 parts:
transport-pci.tex +8 -6
index b07a822..044c085 100644
@@ -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}=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 (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 +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/
Reviewed-by on v4 2/8
#3 lore raw

Re: [virtio-comment] [PATCH v4 2/8] transport-pci: Refer to the vq by its number

Quoted 28 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

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Reviewed-by Jiri Pirko <[email protected]>
Signed-off-by Parav Pandit <[email protected]>

---
changelog:
v2->v3:
- addressed comments from Michael
- changed vqn to virtqueue number in the Note
- refer to vqn field instead of virtqueue number

---
  content.tex       |  2 +-
  transport-pci.tex | 14 ++++++++------
  2 files changed, 9 insertions(+), 7 deletions(-)
content.tex +0 -0
index 1ab7794..0f634ac 100644

content.tex \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues} · line 326

Quoted 7 lines
content.tex +1 -1
@@ -321,7 +321,7 @@ \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
  VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge
  might allow optimizations or simplify driver and/or device code.
 
-Each virtqueue is identified as vq number or also referred
+Each virtqueue is identified by a vq number or also referred
  to as a virtqueue number; vq number range is from 0 to 65535.

Please squash this to patch 1/8 were you introduced this line.

Quoted 6 lines
content.tex +0 -0
  Each virtqueue can consist of up to 3 parts:
transport-pci.tex +0 -0
index b07a822..044c085 100644

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.

why do you add new lines here and bellow ?

Quoted 29 lines
transport-pci.tex +4 -3
          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}=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 (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 +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,

transport-pci.tex \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option · line 1061

Quoted 8 lines
transport-pci.tex +1 -1
@@ -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}

In general, after fixing the above minor comments - looks good.

Reviewed-by Max Gurtovoy <[email protected]>

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/

author
#4 lore raw

RE: [virtio-comment] [PATCH v4 2/8] transport-pci: Refer to the vq by its number

Quoted 13 lines

From: Max Gurtovoy <[email protected]>
Sent: Monday, March 27, 2023 6:49 PM

content.tex \section{Virtqueues}\label{sec:Basic Facilities of a

Quoted 4 lines
content.tex +0 -0
@@ -321,7 +321,7 @@ \section{Virtqueues}\label{sec:Basic Facilities of a

Virtio Device / Virtqueues}

Quoted 3 lines
content.tex +0 -0
  VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge
  might allow optimizations or simplify driver and/or device code.
Quoted 7 lines

content.tex \section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues} · line 326

Quoted 4 lines
content.tex +1 -1
-Each virtqueue is identified as vq number or also referred
+Each virtqueue is identified by a vq number or also referred
  to as a virtqueue number; vq number range is from 0 to 65535.

Please squash this to patch 1/8 were you introduced this line.

Latest v7 doesnt have this wrong hunk here.

Quoted 13 lines
Quoted 10 lines
content.tex +0 -0
  Each virtqueue can consist of up to 3 parts:
transport-pci.tex index renamed from transport-pci.tex +0 -0

b07a822..044c085 100644

transport-pci.tex +0 -0
@@ -390,13 +390,15 @@ \subsubsection{Common configuration structure

layout}\label{sec:Virtio Transport

Quoted 2 lines

\item[\field{queue_notify_data}]
This field exists only if VIRTIO_F_NOTIF_CONFIG_DATA has been

negotiated.

Quoted 8 lines

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport · line 395

Quoted 5 lines
transport-pci.tex +3 -2
-        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.

why do you add new lines here and bellow ?

Will fix in v8.
Below line addition is due to existing limit of 64 or 65 chars per line.

Quoted 8 lines
Quoted 1 line

See section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-

specific Initialization And Device Operation / Available Buffer Notifications}.

Quoted 2 lines

\begin{note}
This field provides the device with flexibility to determine how

virtqueues

Quoted 2 lines

will be referred to in available buffer notifications.
- In a trivial case the device can set \field{queue_notify_data}=vqn. Some

devices

Quoted 14 lines

transport-pci.tex \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport

Quoted 3 lines
transport-pci.tex +2 -0
+        In a trivial case the device can set
+        \field{queue_notify_data}=vq number. Some devices
          may benefit from providing another value, for example an internal

virtqueue

transport-pci.tex \subsubsection{Device

Quoted 3 lines

identifier, or an internal offset related to the virtqueue number. \end{note}

transport-pci.tex +0 -0
@@ -1005,7 +1007,7 @@ \subsubsection{Device

Initialization}\label{sec:Virtio Transport Options / Virti

Quoted 6 lines
transport-pci.tex +1 -1
  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}.

I noticed mentioning of first queue here which is not related. Similar cleanup that Stefano suggested.
Fixing this in v8 too.

Quoted 24 lines

transport-pci.tex \subsubsection{Device · line 1012

Quoted 1 line
transport-pci.tex +0 -0
  \item Read the virtqueue size from \field{queue_size}. This controls how big

the virtqueue is

transport-pci.tex \subsubsection{Device · line 1013

Quoted 1 line
transport-pci.tex +0 -0
    (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.

Quoted 11 lines
transport-pci.tex +0 -0
@@ -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

Quoted 4 lines

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.

Quoted 2 lines

+\field{queue_notify_data} value instead of the virtqueue number.
\item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver

Quoted 7 lines

MUST set the

Quoted 2 lines

\field{vqn} field to the \field{queue_notify_data} value. \end{itemize}

In general, after fixing the above minor comments - looks good.

Reviewed-by Max Gurtovoy <[email protected]>

Thanks. Will add your RB in v8 for this patch.

author
#5 lore raw

PATCH v4 3/8 transport-mmio: Rename QueueNum register

In reply to 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.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
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 +28 -14
index f884a2c..3047633 100644
@@ -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/
author
#6 lore raw

PATCH v4 4/8 transport-mmio: Refer to the vq by its number

In reply to Parav Pandit

Currently specification uses virtqueue index and
number interchangeably to refer to the virtqueue.

Instead refer to it by its number.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Reviewed-by Jiri Pirko <[email protected]>
Signed-off-by Parav Pandit <[email protected]>
---
 transport-mmio.tex | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)
transport-mmio.tex +6 -8
index 3047633..f9b3a34 100644
@@ -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{QueueSizeMax},
     \field{QueueSize}, \field{QueueReady},

@@ -149,7 +149,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 +363,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 +391,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,7 +469,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{QueueSizeMax},
     \field{QueueSize}, \field{QueueAlign}

@@ -550,8 +549,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]
author
#7 lore raw

PATCH v4 5/8 transport-ccw: Rename queue depth/size to other transports

In reply to Parav Pandit

max_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'.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
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 +8 -6
index c492cb9..b4bc83b 100644
@@ -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 · 6 lines
2.26.2


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
author
#8 lore raw

PATCH v4 6/8 transport-ccw: Refer to the vq by its number

In reply to Parav Pandit

Currently specification uses virtqueue index and
number interchangeably to refer to the virtqueue.

Instead refer to it by its number.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Signed-off-by Parav Pandit <[email protected]>

---
changelog:
v3->v4:
- moved note to comment
v2->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
index b4bc83b..b405db1 100644
@@ -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 · 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/
author
#9 lore raw

PATCH v4 7/8 virtio-net: Avoid duplicate receive queue example

In reply to Parav Pandit

Receive 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.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Signed-off-by Parav Pandit <[email protected]>
---
 device-types/net/description.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
device-types/net/description.tex +2 -2
index d7c8b1b..435c1fc 100644
@@ -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]
author
#10 lore raw

PATCH v4 8/8 virtio-net: Describe RSS using receive queue handle

In reply to Parav Pandit

The 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.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Signed-off-by Parav Pandit <[email protected]>

---
changelog:
v3->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 | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)
device-types/net/description.tex +20 -7
index 435c1fc..8b560f3 100644
@@ -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,15 @@ \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
+id \field{rss_rq_id} described above.
 
-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
+queue ids described above in \field{rss_rq_id}.
 
 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 +1465,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
+the \field{rss_rq_id} corresponding to the enabled receive virtqueues.
 
 The number of entries in \field{indirection_table} (\field{indirection_table_mask} + 1) MUST be a power of two.
 

@@ -1468,7 +1479,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
+\field{rss_rq_id}.
 \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 · 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/
#11 lore raw

[virtio-comment] Re: [PATCH v4 8/8] virtio-net: Describe RSS using receive queue handle

Quoted 8 lines · Parav Pandit

The 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.

Quoted 7 lines

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.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163
Signed-off-by Parav Pandit <[email protected]>

getting there, I feel however there's still too much focus on rq_id. It's just a struct we use. What matters is the vqn. More comments below.

Quoted 38 lines

---
changelog:
v3->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 | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)
device-types/net/description.tex +7 -2
index 435c1fc..8b560f3 100644
@@ -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 1450

Quoted 6 lines
device-types/net/description.tex +1 -2
@@ -1442,10 +1447,15 @@ \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}

Looks like you keep removing the main thing which is *what is this field actually for*.

More comments:

id is actually abbreviation. Field is actually \field{unclassified_queue} - rss_rq_id is just a name of struct has no meaning by itself.
so either \field{struct rss_rq_id} or just don't mention this at all. Below example on how not to mention at all.

Here's one way to put it:

\field{unclassified_queue} identifies a receive virtqueue
to place unclassified packets in. Within \field{unclassified_queue}, \field{vqn_1_16}, consists of bits 1 to 16 of the receive virtqueue number
For example,
\field{vqn_1_16} value of 3 corresponds to virtqueue number 6 maps to receiveq4.

device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1458

Quoted 9 lines
device-types/net/description.tex +7 -1
+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
+id \field{rss_rq_id} described above.
 
-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
+queue ids described above in \field{rss_rq_id}.

Field \field{indirection_table} is an array of receive queue identifiers, using the same format as \field{unclassified_queue}.

device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1469

Quoted 10 lines
device-types/net/description.tex +2 -1
 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 +1465,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
+the \field{rss_rq_id} corresponding to the enabled receive virtqueues.

There's no field like this. Also not "the" virtqueues - we didn't discuss them previously. Generally if you want to tweak grammar it's best to do it separately...

example way to put it better:

\field{vqn_1_16} in each entry corresponding to enabled receive virtqueues.

device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1484

Quoted 11 lines
device-types/net/description.tex +3 -1
 The number of entries in \field{indirection_table} (\field{indirection_table_mask} + 1) MUST be a power of two.
 

@@ -1468,7 +1479,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
+\field{rss_rq_id}.

to get \field{vqn_1_16}

Quoted 5 lines
device-types/net/description.tex +0 -0
 \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 · 1 line
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/

author
#12 lore raw

[virtio-comment] RE: [PATCH v4 8/8] virtio-net: Describe RSS using receive queue handle

Quoted 4 lines

From: Michael S. Tsirkin <[email protected]>
Sent: Wednesday, March 22, 2023 7:04 PM

Quoted 8 lines
Quoted 2 lines

-Field \field{unclassified_queue} contains the 0-based index of -the receive virtqueue to place unclassified packets in. Index 0 corresponds to

receiveq1.

Quoted 1 line

+\field{rss_rq_id} is a receive virtqueue id. \field{vqn_1_16}

Looks like you keep removing the main thing which is *what is this field actually for*.

Ah my bad. Fixing it.

Quoted 7 lines

More comments:

id is actually abbreviation. Field is actually \field{unclassified_queue} - rss_rq_id is just a name of struct has no meaning by itself.
so either \field{struct rss_rq_id} or just don't mention this at all. Below example on how not to mention at all.

Structure defines the format of the vqn. I will keep the definition there of what vqn_1_16 means.

Quoted 9 lines

Here's one way to put it:

\field{unclassified_queue} identifies a receive virtqueue to place unclassified packets in.

Within \field{unclassified_queue}, \field{vqn_1_16}, consists of bits 1 to 16 of the receive virtqueue number For example, \field{vqn_1_16} value of 3 corresponds to virtqueue number 6 maps to receiveq4.

I will keep this example where rss_rq_is id structure is defined. More below.

Quoted 7 lines
Quoted 2 lines

+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.

Quoted 4 lines
(quoted diff) +3 -0
+
+Field \field{unclassified_queue} contains the receive virtqueue id
+\field{rss_rq_id} described above.
Quoted 8 lines
Quoted 1 line

-Field \field{indirection_table} contains an array of 0-based indices of receive

virtqueues. Index 0 corresponds to receiveq1.

Review

Quoted 2 lines
(quoted diff) +2 -0
+Field \field{indirection_table} is an array of receive queue ids
+described above in \field{rss_rq_id}.

Field \field{indirection_table} is an array of receive queue identifiers, using the same format as \field{unclassified_queue}.

Will refer to rss_rq_id and avoid with 2nd indirection in describing indirection table.

Quoted 5 lines
Quoted 3 lines

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}).

Quoted 1 line
Quoted 11 lines
Quoted 4 lines
(quoted diff) +0 -0
@@ -1455,7 +1465,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.

Quoted 2 lines

-A driver MUST fill the \field{indirection_table} array only with indices of

enabled queues. Index 0 corresponds to receiveq1.

Quoted 2 lines

+A driver MUST fill the \field{indirection_table} array only with the +\field{rss_rq_id} corresponding to the enabled receive virtqueues.

Will remove the reference to the field rss_rq_id here.

Quoted 3 lines

There's no field like this. Also not "the" virtqueues - we didn't discuss them previously. Generally if you want to tweak grammar it's best to do it separately...

Will remove "the".

Quoted 6 lines
Quoted 3 lines

+\item Apply \field{indirection_table_mask} to the calculated hash and +use the result as the index in the indirection table to get +\field{rss_rq_id}.

to get \field{vqn_1_16}

It is bit simpler with below rewrite without duplicating content of indirection table,

"use the result as the index in the indirection table to get receive queue entry."

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/

#13 lore raw
In reply to Parav Pandit
Quoted 7 lines · Parav Pandit

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.

Looks good, some comments on 8/8.

Quoted 52 lines

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:
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 (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 receive queue handle

Quoted 9 lines
 content.tex                      |  3 ++
 device-types/net/description.tex | 29 ++++++++++++-----
 transport-ccw.tex                | 27 ++++++++-------
 transport-mmio.tex               | 56 +++++++++++++++++++-------------
 transport-pci.tex                | 14 ++++----
 5 files changed, 81 insertions(+), 48 deletions(-)
Signature · 1 line
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/