Skip to contentSkip to conversation

virtio-net: Improve introductory description

PATCH Superseded Parav Pandit 3 participants 5 messages Feb 2, 2023 – Feb 9, 2023

v2 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 virtio-net: Improve introductory description

The control VQ of the virtio network device is used beyond advance steering control. The control VQ dynamically changes multiple features of the initialized device.

Hence, update this area of control VQ introductory description at few places and also place the link to its description.

Also update the introduction section to better describe receive and transmit virtqueues.

---
This patch is on top of [1].

[1] https://lists.oasis-open.org/archives/virtio-dev/202301/msg00280.html
---
changelog:
v1->v2:
- corrected/added article before transmit and receive virtqueue
- replaced listed with described
- updated set to negotiated for CTRL_VQ
- improved introduction wordings
v0->v1:
- replaced command queue to control virtqueue to reflect current state
- added link of control vq to its detailed section
- removed reference of cvq from more places that limits it to steering
- Addressed Cornelia's review comments:
- updated introduction section to better describe rq, sq, cvq.
- explicitly wrote that cvq is optional along with its feature bit related description
- dropped few items from Cornelia's review as they do not exactly fit with latest 1.2 specification as below.
- avoided listing number of queues in introduction as its linked to q reset which can disable all queues
- avoid mentioning cvq as optional as there is better section for it
- avoid talking about queue pairs as spec and use cases allows not operate in pairs mode

---
 device-types/net/description.tex | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
device-types/net/description.tex +11 -10
index 88a5770..dedd6b1 100644
@@ -2,13 +2,13 @@ \section{Network Device}\label{sec:Device Types / Network Device}
 
 The virtio network device is a virtual network interface controller.
 It consists of a virtual Ethernet link which connects the device
-to the Ethernet network. It is the most complex of the devices
-supported so far by virtio. It has enhanced rapidly and demonstrates
-clearly how support for new features are added to an existing
-device. Empty buffers are placed in one virtqueue for receiving
-packets, and outgoing packets are enqueued into another for
-transmission in that order. A third command queue is used to
-control advanced filtering features.
+to the Ethernet network. The driver posts empty buffers in the
+receive virtqueue. The device receives the incoming packets from the link;
+the device places these incoming packets in the receive virtqueue buffers.
+The driver enqueues outgoing packets to the transmit virtqueue. The device
+dequeues these packets from the transmit virtqueue and sends them to
+the link. A control virtqueue is used to dynamically manipulate various
+features of the initialized device.
 
 \subsection{Device ID}\label{sec:Device Types / Network Device / Device ID}
 
@@ -28,7 +28,8 @@ \subsection{Virtqueues}\label{sec:Device Types / Network Device / Virtqueues}
  N=1 if neither VIRTIO_NET_F_MQ nor VIRTIO_NET_F_RSS are negotiated, otherwise N is set by
  \field{max_virtqueue_pairs}.
 
- controlq only exists if VIRTIO_NET_F_CTRL_VQ set.
+controlq is optional; it only exists if VIRTIO_NET_F_CTRL_VQ is
+negotiated.
 
 \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits}
 
@@ -389,8 +390,8 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O
 };
 \end{lstlisting}
 
-The controlq is used to control device features such as
-filtering.
+The controlq is used to control many device features described further in
+section \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue}.
 
 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Network Device / Device Operation / Legacy Interface: Device Operation}
 When using the legacy interface, transitional devices and drivers
Signature · 1 line
2.26.2
#1 lore raw
Quoted 28 lines · Parav Pandit

The control VQ of the virtio network device is used beyond advance steering control. The control VQ dynamically changes multiple features of the initialized device.

Hence, update this area of control VQ introductory description at few places and also place the link to its description.

Also update the introduction section to better describe receive and transmit virtqueues.

---
 device-types/net/description.tex | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
device-types/net/description.tex +0 -4
index 88a5770..dedd6b1 100644
@@ -2,13 +2,13 @@ \section{Network Device}\label{sec:Device Types / Network Device}
 
 The virtio network device is a virtual network interface controller.
 It consists of a virtual Ethernet link which connects the device
-to the Ethernet network. It is the most complex of the devices
-supported so far by virtio. It has enhanced rapidly and demonstrates
-clearly how support for new features are added to an existing
-device. Empty buffers are placed in one virtqueue for receiving

device-types/net/description.tex \section{Network Device}\label{sec:Device Types / Network Device} · line 11

Quoted 10 lines
device-types/net/description.tex +7 -3
-packets, and outgoing packets are enqueued into another for
-transmission in that order. A third command queue is used to
-control advanced filtering features.
+to the Ethernet network. The driver posts empty buffers in the
+receive virtqueue. The device receives the incoming packets from the link;
+the device places these incoming packets in the receive virtqueue buffers.
+The driver enqueues outgoing packets to the transmit virtqueue. The device
+dequeues these packets from the transmit virtqueue and sends them to
+the link. A control virtqueue is used to dynamically manipulate various
+features of the initialized device.

General question: Is it better to talk about "the receive virtqueue" (to keep it simple), or "a receive virtqueue" (as there may be several)?

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/

#2 lore raw
Quoted 44 lines

From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 5:07 AM

Quoted 33 lines · Parav Pandit

The control VQ of the virtio network device is used beyond advance steering control. The control VQ dynamically changes multiple features of the initialized device.

Hence, update this area of control VQ introductory description at few places and also place the link to its description.

Also update the introduction section to better describe receive and transmit virtqueues.

---
 device-types/net/description.tex | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
device-types/net/description.tex +0 -0
index 88a5770..dedd6b1 100644
@@ -2,13 +2,13 @@ \section{Network Device}\label{sec:Device Types /
 Network Device}
 
 The virtio network device is a virtual network interface controller.
 It consists of a virtual Ethernet link which connects the device -to

the Ethernet network. It is the most complex of the devices -supported so far by virtio. It has enhanced rapidly and demonstrates -clearly how support for new features are added to an existing -device. Empty buffers are placed in one virtqueue for receiving -packets, and outgoing packets are enqueued into another for -transmission in that order. A third command queue is used to -control advanced filtering features.

device-types/net/description.tex

Quoted 3 lines
device-types/net/description.tex +3 -0
+to the Ethernet network. The driver posts empty buffers in the
+receive virtqueue. The device receives the incoming packets from the
+link; the device places these incoming packets in the receive virtqueue

buffers.

Quoted 7 lines

device-types/net/description.tex

Quoted 4 lines
device-types/net/description.tex +4 -0
+The driver enqueues outgoing packets to the transmit virtqueue. The
+device dequeues these packets from the transmit virtqueue and sends
+them to the link. A control virtqueue is used to dynamically
+manipulate various features of the initialized device.

General question: Is it better to talk about "the receive virtqueue" (to keep it simple), or "a receive virtqueue" (as there may be several)?

For sure Michael can better answer this than me. :)
The receive virtqueue aligns to me with "the device", the driver etc.
It also aligns with existing sections in device and driver requirements that refers to "the receiveq". Since there are many queues, better to refer as "the".
A receive queue may imply that there is only one.

#3 lore raw
Quoted 44 lines · Parav Pandit
Quoted 44 lines

From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 5:07 AM

Quoted 33 lines · Parav Pandit

The control VQ of the virtio network device is used beyond advance steering control. The control VQ dynamically changes multiple features of the initialized device.

Hence, update this area of control VQ introductory description at few places and also place the link to its description.

Also update the introduction section to better describe receive and transmit virtqueues.

---
 device-types/net/description.tex | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
device-types/net/description.tex +0 -0
index 88a5770..dedd6b1 100644
@@ -2,13 +2,13 @@ \section{Network Device}\label{sec:Device Types /
 Network Device}
 
 The virtio network device is a virtual network interface controller.
 It consists of a virtual Ethernet link which connects the device -to

the Ethernet network. It is the most complex of the devices -supported so far by virtio. It has enhanced rapidly and demonstrates -clearly how support for new features are added to an existing -device. Empty buffers are placed in one virtqueue for receiving -packets, and outgoing packets are enqueued into another for -transmission in that order. A third command queue is used to -control advanced filtering features.

device-types/net/description.tex

Quoted 3 lines
device-types/net/description.tex +3 -0
+to the Ethernet network. The driver posts empty buffers in the
+receive virtqueue. The device receives the incoming packets from the
+link; the device places these incoming packets in the receive virtqueue

buffers.

Quoted 4 lines
Quoted 4 lines

device-types/net/description.tex

Quoted 4 lines
device-types/net/description.tex +4 -0
+The driver enqueues outgoing packets to the transmit virtqueue. The
+device dequeues these packets from the transmit virtqueue and sends
+them to the link. A control virtqueue is used to dynamically
+manipulate various features of the initialized device.

What happened here? Parav it looks like your client mangled Cornelia's response. Pls take a look at your client config.

Quoted 8 lines
Quoted 2 lines

General question: Is it better to talk about "the receive virtqueue" (to keep it simple), or "a receive virtqueue" (as there may be several)?

For sure Michael can better answer this than me. :)
The receive virtqueue aligns to me with "the device", the driver etc.
It also aligns with existing sections in device and driver requirements that refers to "the receiveq". Since there are many queues, better to refer as "the".
A receive queue may imply that there is only one.

My take is that it should be "a queue" the first time we talk about it. Then if it's the same queue we say "the queue". I also feel an intro sentence saying something along the lines of "the device has receive and transmit queues". Then rest of uses can be "the".

Signature · 1 line
MST
#4 lore raw
Quoted 4 lines

From: Michael S. Tsirkin <[email protected]>
Sent: Wednesday, February 8, 2023 4:46 AM

[..]

Quoted 6 lines
Quoted 6 lines
Quoted 2 lines

General question: Is it better to talk about "the receive virtqueue" (to keep it simple), or "a receive virtqueue" (as there may be several)?

For sure Michael can better answer this than me. :) The receive virtqueue aligns to me with "the device", the driver etc.
It also aligns with existing sections in device and driver requirements that

Quoted 8 lines

refers to "the receiveq".

Quoted 2 lines

Since there are many queues, better to refer as "the". A receive queue may imply that there is only one.

My take is that it should be "a queue" the first time we talk about it. Then if it's the same queue we say "the queue".
I also feel an intro sentence saying something along the lines of "the device has receive and transmit queues". Then rest of uses can be "the".

Will update this in v3.