Rename queue index to queue number

[1] https://lists.oasis-open.org/archives/virtio-dev/202302/msg00527.html

---
 transport-pci.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

transport-pci.tex +3 -3

index b07a822..dbd3adb 100644
@@ -1005,7 +1005,7 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
 The driver typically does this as follows, for each virtqueue a device has:
 
 \begin{enumerate}
-\item Write the virtqueue index (first queue is 0) to \field{queue_select}.
+\item Write the virtqueue number (first queue is 0) to \field{queue_select}.
 
 \item Read the virtqueue size from \field{queue_size}. This controls how big the virtqueue is
   (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues}). If this field is 0, the virtqueue does not exist.

@@ -1035,7 +1035,7 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
 
 When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
 the driver sends an available buffer notification to the device by writing
-the 16-bit virtqueue index
+the 16-bit virtqueue number
 of this virtqueue to the Queue Notify address.
 
 When VIRTIO_F_NOTIFICATION_DATA has been negotiated,

@@ -1053,7 +1053,7 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
 If VIRTIO_F_NOTIF_CONFIG_DATA has been negotiated:
 \begin{itemize}
 \item If VIRTIO_F_NOTIFICATION_DATA has not been negotiated, the driver MUST use the
-\field{queue_notify_data} value instead of the virtqueue index.
+\field{queue_notify_data} value instead of the virtqueue number.
 \item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver MUST set the
 \field{vqn} field to the \field{queue_notify_data} value.
 \end{itemize}

Signature · 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/

Michael S. Tsirkin

2023-03-21 09:01 UTC #2 lore raw

Re: [virtio-comment] [PATCH v2 1/7] transport-pci: 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.

This patch is on top of [1].

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163

---
 transport-pci.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

transport-pci.tex +2 -2

index b07a822..dbd3adb 100644
@@ -1005,7 +1005,7 @@ \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virti
 The driver typically does this as follows, for each virtqueue a device has:
 
 \begin{enumerate}
-\item Write the virtqueue index (first queue is 0) to \field{queue_select}.
+\item Write the virtqueue number (first queue is 0) to \field{queue_select}.
 
 \item Read the virtqueue size from \field{queue_size}. This controls how big the virtqueue is
   (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues}). If this field is 0, the virtqueue does not exist.

@@ -1035,7 +1035,7 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
 
 When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
 the driver sends an available buffer notification to the device by writing
-the 16-bit virtqueue index
+the 16-bit virtqueue number
 of this virtqueue to the Queue Notify address.
 
 When VIRTIO_F_NOTIFICATION_DATA has been negotiated,

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

Quoted 8 lines

transport-pci.tex +1 -1

@@ -1053,7 +1053,7 @@ \subsubsection{Available Buffer Notifications}\label{sec:Virtio Transport Option
 If VIRTIO_F_NOTIF_CONFIG_DATA has been negotiated:
 \begin{itemize}
 \item If VIRTIO_F_NOTIFICATION_DATA has not been negotiated, the driver MUST use the
-\field{queue_notify_data} value instead of the virtqueue index.
+\field{queue_notify_data} value instead of the virtqueue number.
 \item If VIRTIO_F_NOTIFICATION_DATA has been negotiated, the driver MUST set the
 \field{vqn} field to the \field{queue_notify_data} value.
 \end{itemize}

Hmm OK.

Now here's another a problem:

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

and I think it's actually \field{vqn} not 'virtqueue number':
\item [vqn] VQ number to be notified.

and it also says

In a trivial case the device can set \field{queue_notify_data}=vqn. Some devices may benefit from providing another value, for example an internal virtqueue identifier, or an internal offset related to the virtqueue number.

and that's backwards since vqn is always queue_notify_data. What is meant is "set queue_notify_data to the virtqueue number'.

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]

Parav Pandit

author

2023-03-21 20:43 UTC #3 lore raw

RE: [virtio-comment] [PATCH v2 1/7] transport-pci: Refer to the vq by its number

Quoted 5 lines

From: Michael S. Tsirkin <[email protected]>
Sent: Tuesday, March 21, 2023 5:01 AM

Quoted 9 lines

\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.
and I think it's actually \field{vqn} not 'virtqueue number':
\item [vqn] VQ number to be notified.

Yes. will fix this in v3.

Quoted 10 lines

and it also says
In a trivial case the device can set \field{queue_notify_data}=vqn. Some
devices
may benefit from providing another value, for example an internal
virtqueue
identifier, or an internal offset related to the virtqueue number.
and that's backwards since vqn is always queue_notify_data. What is meant is "set queue_notify_data to the virtqueue number'.

Yes this change too in v3.

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/

Parav Pandit

author

2023-03-21 04:11 UTC #4 lore raw

PATCH v2 2/7 transport-mmio: Rename QueueNum register

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

---
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/

Parav Pandit

author

2023-03-21 04:11 UTC #5 lore raw

PATCH v2 3/7 transport-mmio: Refer to the vq by its number

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

Instead refer to it by its number.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163

---
 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]

Parav Pandit

author

2023-03-21 04:11 UTC #6 lore raw

PATCH v2 4/7 transport-ccw: Rename queue depth/size to other transports

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

---
 transport-ccw.tex | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

transport-ccw.tex +20 -6

index c492cb9..c2e60b6 100644
@@ -237,12 +237,16 @@ \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;
 };
 \end{lstlisting}
 
 The requested number of buffers for queue \field{index} is returned in
-\field{max_num}.
+\field{max_queue_size}.
+
+\begin{note}
+\field{max_queue_size} was previously named as max_num.
+\end{note}
 
 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 +257,7 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
         be64 desc;
         be32 res0;
         be16 index;
-        be16 num;
+        be16 size;
         be64 driver;
         be64 device;
 };

@@ -262,7 +266,12 @@ \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}.
+
+\begin{note}
+\field{size} was previously named as num.
+\end{note}
 
 \devicenormative{\paragraph}{Configuring a Virtqueue}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue}

@@ -278,13 +287,18 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
         be64 queue;
         be32 align;
         be16 index;
-        be16 num;
+        be16 size;
 };
 \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}.
 
+\begin{note}
+\field{size} was previously named as num.
+\end{note}
+
 \subsubsection{Communicating Status Information}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information}
 
 The driver changes the status of a device via the

Signature · 6 lines

2.26.2


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Parav Pandit

author

2023-03-21 04:11 UTC #7 lore raw

PATCH v2 5/7 transport-ccw: Refer to the vq by its number

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

Instead refer to it by its number.

Fixes https://github.com/oasis-tcs/virtio-spec/issues/163

---
changelog:
v0->v1:
- new patch

---
 transport-ccw.tex | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

transport-ccw.tex +8 -7

index c2e60b6..b8ba0b7 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;
         be16 max_queue_size;
 };
 \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}.
 
 \begin{note}

@@ -256,7 +256,7 @@ \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir
 struct vq_info_block {
         be64 desc;
         be32 res0;
-        be16 index;
+        be16 queue_select;
         be16 size;
         be64 driver;
         be64 device;

@@ -265,7 +265,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}.

@@ -286,12 +286,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;
         be16 size;
 };
 \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}.

@@ -583,7 +584,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]

Michael S. Tsirkin

2023-03-21 08:47 UTC #8 lore raw

[virtio-comment] Re: [PATCH v2 5/7] transport-ccw: Refer to the vq by its number

Quoted 7 lines · 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]>

OK, but I'd say it's worth referring to the old name here, too.

Quoted 28 lines

---
changelog:
v0->v1:
- new patch

---
 transport-ccw.tex | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

transport-ccw.tex +2 -2

index c2e60b6..b8ba0b7 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;
         be16 max_queue_size;
 };
 \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}.
 
 \begin{note}

transport-ccw.tex \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir · line 259

Quoted 5 lines

transport-ccw.tex +1 -1

@@ -256,7 +256,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 known as index */

Quoted 13 lines

transport-ccw.tex +1 -1

         be16 size;
         be64 driver;
         be64 device;

@@ -265,7 +265,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}.

transport-ccw.tex \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Vir · line 289

Quoted 5 lines

transport-ccw.tex +1 -1

@@ -286,12 +286,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 known as index */

Quoted 21 lines

transport-ccw.tex +3 -2

         be16 size;
 };
 \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}.

@@ -583,7 +584,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 · 1 line

2.26.2

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]

Parav Pandit

author

2023-03-21 04:11 UTC #9 lore raw

PATCH v2 6/7 virtio-net: Avoid duplicate receive queue example

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

---
 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]

Parav Pandit

author

2023-03-21 04:11 UTC #10 lore raw

PATCH v2 7/7 virtio-net: Describe RSS using receive queue handle

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

---
changelog:
v0->v1:
- new patch suggested by Michael Tsirkin

---
 device-types/net/description.tex | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

device-types/net/description.tex +19 -5

index 435c1fc..fa9b4c7 100644
@@ -1442,20 +1442,32 @@ \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 \field{unclassified_queue} contains the receive queue
+handle \field{rq_handle} described below.
 
-Field \field{indirection_table} contains an array of 0-based indices of receive virtqueues. Index 0 corresponds to receiveq1.
+Field \field{indirection_table} contains an array of receive
+queue handles described below in \field{rq_handle}. For example at
+array index 0, a value of 3 maps to virtqueue number 6
+which corresponds to receiveq4.
 
 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}).
 
 Fields \field{hash_key_length} and \field{hash_key_data} define the key to be used in hash calculation.
 
+\begin{lstlisting}
+le16 rq_handle;
+\end{lstlisting}
+
+\field{rq_handle} is a receive virtqueue handle. It is calculated as
+virtqueue number divided by 2. For example a receive virtqueue handle
+value of 3 corresponds to virtqueue number 6 maps to receiveq4.
+
 \drivernormative{\subparagraph}{Setting RSS parameters}{Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) }
 
 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{rq_handle} 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 +1480,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{rq_handle}.
 \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]

Michael S. Tsirkin

2023-03-21 08:55 UTC #11 lore raw

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

Quoted 30 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.
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:
v0->v1:
- new patch suggested by Michael Tsirkin
---
 device-types/net/description.tex | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)
device-types/net/description.tex +0 -0
index 435c1fc..fa9b4c7 100644
@@ -1442,20 +1442,32 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
 \field{indirection_table} array.

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

Quoted 10 lines

device-types/net/description.tex +4 -3

 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 \field{unclassified_queue} contains the receive queue
+handle \field{rq_handle} described below.
 
-Field \field{indirection_table} contains an array of 0-based indices of receive virtqueues. Index 0 corresponds to receiveq1.
+Field \field{indirection_table} contains an array of receive
+queue handles described below in \field{rq_handle}.

This is only used once, here. I understand that we need a name for this but it need not be so generic, I feel it's just confusing. I propose "indirection table entry".

Thus:
Field \field{indirection_table} contains an array of
indirection table entries. Each indirection table entry consists of a vq number value divided by 2. Thus, an entry value of 3 maps to virtqueue number 6 which corresponds to receiveq4

Quoted 2 lines

For example at
+array index 0,

why mention array index here?

Quoted 2 lines

a value of 3 maps to virtqueue number 6
+which corresponds to receiveq4.

It's a good idea to first describe a concept then provide an example.

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

Quoted 12 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}).
Fields \field{hash_key_length} and \field{hash_key_data} define the key to be used in hash calculation.
+\begin{lstlisting}
device-types/net/description.tex +7 -0
+le16 rq_handle;
+\end{lstlisting}
+
+\field{rq_handle} is a receive virtqueue handle. It is calculated as
+virtqueue number divided by 2. For example a receive virtqueue handle
+value of 3 corresponds to virtqueue number 6 maps to receiveq4.
+

it's a bit disconnected from the rest of the description. why not adjacent to it?

Quoted 23 lines

\drivernormative{\subparagraph}{Setting RSS parameters}{Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) }

A driver MUST NOT send the VIRTIO_NET_CTRL_MQ_RSS_CONFIG command if the feature VIRTIO_NET_F_RSS has not been negotiated.

device-types/net/description.tex +5 -2

-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{rq_handle} 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 +1480,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{rq_handle}.
 \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

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]

Parav Pandit

author

2023-03-21 20:54 UTC #12 lore raw

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

Quoted 4 lines

From: Michael S. Tsirkin <[email protected]>
Sent: Tuesday, March 21, 2023 4:56 AM

[..]

Quoted 12 lines

\field{indirection_table} array.
Quoted 1 line
Number of entries in \field{indirection_table} is
(\field{indirection_table_mask} + 1).
Quoted 3 lines
-Field \field{unclassified_queue} contains the 0-based index of -the receive virtqueue to place unclassified packets in. Index 0 corresponds to
receiveq1.
Review
Quoted 4 lines
(quoted diff) +2 -1
+Field \field{unclassified_queue} contains the receive queue handle
+\field{rq_handle} described below.
 
-Field \field{indirection_table} contains an array of 0-based indices of receive
virtqueues. Index 0 corresponds to receiveq1.

Quoted 8 lines

Review
Quoted 2 lines
(quoted diff) +2 -0
+Field \field{indirection_table} contains an array of receive queue
+handles described below in \field{rq_handle}.
This is only used once, here. I understand that we need a name for this but it need not be so generic, I feel it's just confusing.
I propose "indirection table entry".

Unclassified_queue field also refers to it.
Need to duplicate the below description there too. So using rq_handle simplified it.
May be it can be duplicated as
Unclassified_queue consists of vq number value divided by two.

And avoid rq_handle definition.

Quoted 9 lines

Thus:
Field \field{indirection_table} contains an array of indirection table entries. Each indirection table entry consists of a vq number value divided by 2. Thus, an entry value of 3 maps to
virtqueue number 6
which corresponds to receiveq4

Quoted 5 lines

Quoted 2 lines
For example at
+array index 0,
why mention array index here?

Since we are mentioning an indirection table array, referring to an array entry without referring to the array index was little odd. After reading your above example, it doesn't look that odd.

Quoted 5 lines

Quoted 2 lines
a value of 3 maps to virtqueue number 6
+which corresponds to receiveq4.
It's a good idea to first describe a concept then provide an example.

True, but it was not too far with pointer to describe below.

Quoted 7 lines

Quoted 2 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 2 lines
Fields \field{hash_key_length} and \field{hash_key_data} define the key to be
used in hash calculation.
Quoted 1 line

Quoted 11 lines

device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1464
Quoted 8 lines
+\begin{lstlisting}
device-types/net/description.tex +7 -0
+le16 rq_handle;
+\end{lstlisting}
+
+\field{rq_handle} is a receive virtqueue handle. It is calculated as
+virtqueue number divided by 2. For example a receive virtqueue handle
+value of 3 corresponds to virtqueue number 6 maps to receiveq4.
+
it's a bit disconnected from the rest of the description. why not adjacent to it?

Sure it can move up before max_tx_vq or before introducing unclassified_queue.

But I guess we can describe by duplicating the text and avoiding rq_handle as you suggest. Will simplify this in v3.

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.

Parav Pandit

author

2023-03-21 21:15 UTC #13 lore raw

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

Quoted 8 lines

From: [email protected] <[email protected] open.org> On Behalf Of Parav Pandit
But I guess we can describe by duplicating the text and avoiding rq_handle as you suggest.
Will simplify this in v3.

Looking further, we refer to rq_handle in more than 2 places, at indirection_table_mask field too. So I am keeping it, moving it ahead so that all 3 places can refer it.

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.

Michael S. Tsirkin

2023-03-21 09:05 UTC #14 lore raw