virtio-net: Improve introductory description
PATCH v3 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:v2->v3:
- further improve introductionv1->v2:
- corrected/added article before transmit and receive virtqueue
- replaced listed with described
- updated set to negotiated for CTRL_VQ
- improved introduction wordingsv0->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 | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-)
device-types/net/description.tex +13 -10
@@ -2,13 +2,15 @@ \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 device has transmit and receive +queues. 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. The device may have a control virtuqueue. The driver +uses the control virtqueue to dynamically manipulate various +features of the initialized device. \subsection{Device ID}\label{sec:Device Types / Network Device / Device ID}
@@ -28,7 +30,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 +392,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
Quoted 56 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.
Signed-off-by Parav Pandit <[email protected]>---
This patch is on top of [1].[1] https://lists.oasis-open.org/archives/virtio-dev/202301/msg00280.html
---
changelog:v2->v3:
- further improve introductionv1->v2:
- corrected/added article before transmit and receive virtqueue
- replaced listed with described
- updated set to negotiated forCTRL_VQ
- improved introduction wordingsv0->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 | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-)device-types/net/description.tex +0
-4@@ -2,13 +2,15 @@ \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 device has transmit and receive +queues. 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. The device may have a control virtuqueue. The driver
typo: s/virtuqueue/virtqueue/
device-types/net/description.tex \section{Network Device}\label{sec:Device Types / Network Device} · line 15
Quoted 4 lines
device-types/net/description.tex +2
-0+uses the control virtqueue to dynamically manipulate various +features of the initialized device. \subsection{Device ID}\label{sec:Device Types / Network Device / Device ID}
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 5 lines
From: Cornelia Huck <[email protected]>
Sent: Thursday, February 9, 2023 6:38 AM
Quoted 10 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+to the Ethernet network. The device has transmit and receive queues. +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. The device may have a control virtuqueue. The +drivertypo: s/virtuqueue/virtqueue/
Fix fix. Thanks.
Quoted 55 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.
Signed-off-by Parav Pandit <[email protected]>---
This patch is on top of [1].[1] https://lists.oasis-open.org/archives/virtio-dev/202301/msg00280.html
---
changelog:v2->v3:
- further improve introductionv1->v2:
- corrected/added article before transmit and receive virtqueue
- replaced listed with described
- updated set to negotiated forCTRL_VQ
- improved introduction wordingsv0->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 | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-)device-types/net/description.tex +0
-3@@ -2,13 +2,15 @@ \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-types/net/description.tex \section{Network Device}\label{sec:Device Types / Network Device} · line 10
Quoted 10 lines
device-types/net/description.tex +5
-4-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 device has transmit and receive +queues. 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
We "post" receive buffers, yet "enqueue" transmit buffers. These actions seem the same.
Maybe "submits" in both cases?
Quoted 28 lines
device-types/net/description.tex +8
-3+dequeues these packets from the transmit virtqueue and sends them to +the link. The device may have a control virtuqueue. The driver +uses the control virtqueue to dynamically manipulate various +features of the initialized device. \subsection{Device ID}\label{sec:Device Types / Network Device / Device ID}@@ -28,7 +30,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 +392,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 · 17 lines
Sorry I'm not home right now, I'm walking into spiderwebs. This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: [email protected] Unsubscribe: [email protected] List help: [email protected] List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/
Quoted 4 lines
From: David Edmondson <[email protected]>
Sent: Thursday, February 9, 2023 7:03 AM
[..]
Quoted 10 lines
Review
Quoted 6 lines
(quoted diff) +5
-0+to the Ethernet network. The device has transmit and receive queues. +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 deviceWe "post" receive buffers, yet "enqueue" transmit buffers. These actions seem the same.
Quoted 2 lines
Maybe "submits" in both cases?
At virtqueue level it is same.
In context of virtio net device, transmit operation is queued that awaits processing (to send) by device. While receive side, its unsolicited operation done by driver that doesn't await processing by device. Whenever/if in future when a packet arrives, the posted buffer is consumed.
So enqueue and post were capturing this contextual detail.
But maybe I am trying to be too precise here but above wording were more natural to me at net level. :) Let me know..
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 18 lines · Parav Pandit
Quoted 4 lines
From: David Edmondson <[email protected]>
Sent: Thursday, February 9, 2023 7:03 AM[..]
Quoted 10 lines
Review
Quoted 6 lines
(quoted diff) +5
-0+to the Ethernet network. The device has transmit and receive queues. +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 deviceWe "post" receive buffers, yet "enqueue" transmit buffers. These actions seem the same.
Quoted 2 lines
Maybe "submits" in both cases?
Quoted 8 lines
At virtqueue level it is same.
In context of virtio net device, transmit operation is queued that awaits processing (to send) by device. While receive side, its unsolicited operation done by driver that doesn't await processing by device. Whenever/if in future when a packet arrives, the posted buffer is consumed.So enqueue and post were capturing this contextual detail.
But maybe I am trying to be too precise here but above wording were more natural to me at net level. :) Let me know..
Just "add" - this is what happens at vq level:
Driver makes requests available to device by adding an available buffer to the queue, i.e., adding a buffer
Signature · 1 line
MST
Quoted 17 lines · Parav Pandit
Quoted 3 lines
From: David Edmondson <[email protected]>
Sent: Thursday, February 9, 2023 7:03 AM[..]
Quoted 10 lines
Review
Quoted 6 lines
(quoted diff) +5
-0+to the Ethernet network. The device has transmit and receive queues. +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 deviceWe "post" receive buffers, yet "enqueue" transmit buffers. These actions seem the same.
Quoted 2 lines
Maybe "submits" in both cases?
Quoted 8 lines
At virtqueue level it is same.
In context of virtio net device, transmit operation is queued that awaits processing (to send) by device. While receive side, its unsolicited operation done by driver that doesn't await processing by device. Whenever/if in future when a packet arrives, the posted buffer is consumed.So enqueue and post were capturing this contextual detail.
But maybe I am trying to be too precise here but above wording were more natural to me at net level. :) Let me know..
I'm not too bothered. The operations are functionally the same, so using different words seemed odd.
Signature · 17 lines
Please don't stand so close to me. This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: [email protected] Unsubscribe: [email protected] List help: [email protected] List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/
Quoted 52 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.
Signed-off-by Parav Pandit <[email protected]>---
This patch is on top of [1].[1] https://lists.oasis-open.org/archives/virtio-dev/202301/msg00280.html
---
changelog:v2->v3:
- further improve introductionv1->v2:
- corrected/added article before transmit and receive virtqueue
- replaced listed with described
- updated set to negotiated forCTRL_VQ
- improved introduction wordingsv0->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 | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-)device-types/net/description.tex +0
-0@@ -2,13 +2,15 @@ \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
device-types/net/description.tex \section{Network Device}\label{sec:Device Types / Network Device} · line 7
Quoted 10 lines
device-types/net/description.tex +3
-7-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 device has transmit and receive +queues. The driver posts empty buffers in the receive virtqueue. +The device receives the incoming packets
s/the// - 1st time we mention packets
Quoted 21 lines
from the link; the device
device-types/net/description.tex +8
-1+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. The device may have a control virtuqueue. The driver +uses the control virtqueue to dynamically manipulate various +features of the initialized device. \subsection{Device ID}\label{sec:Device Types / Network Device / Device ID}@@ -28,7 +30,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}
device-types/net/description.tex \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O · line 395
Quoted 6 lines
device-types/net/description.tex +1
-2@@ -389,8 +392,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
many seems subjective.
s/many/some of the/ ?
Quoted 6 lines
device-types/net/description.tex +1
-0+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 driversSignature · 1 line
2.26.2
Quoted 5 lines · Michael S. Tsirkin
Quoted 4 lines · Parav Pandit
device-types/net/description.tex +0
-0@@ -389,8 +392,8 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O }; \end{lstlisting}
Quoted 7 lines
device-types/net/description.tex \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O · line 395
Quoted 3 lines
device-types/net/description.tex +1
-2-The controlq is used to control device features such as -filtering. +The controlq is used to control many device features described further inmany seems subjective.
s/many/some of the/ ?
s/many/various/ instead? That section should cover all of the device features controled via the control vq.
Quoted 2 lines
device-types/net/description.tex \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O · line 396
Quoted 2 lines
device-types/net/description.tex +1
-0+section \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue}.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 13 lines · Cornelia Huck
Quoted 11 lines · Michael S. Tsirkin
device-types/net/description.tex \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O · line 395
Quoted 7 lines · Parav Pandit
device-types/net/description.tex +1
-2@@ -389,8 +392,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 inmany seems subjective.
Quoted 4 lines
Quoted 1 line
s/many/some of the/ ?
s/many/various/ instead? That section should cover all of the device features controled via the control vq.
I like that.
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
device-types/net/description.tex +1
-0+section \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue}.
Quoted 18 lines
From: Michael S. Tsirkin <[email protected]>
Sent: Thursday, February 9, 2023 7:31 AMQuoted 13 lines · Cornelia Huck
Quoted 11 lines · Michael S. Tsirkin
device-types/net/description.tex \subsection{Device Operation}\label{sec:Device · line 395
Quoted 7 lines · Parav Pandit
device-types/net/description.tex +2
-2@@ -389,8 +392,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 inmany seems subjective.
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
s/many/some of the/ ?
s/many/various/ instead? That section should cover all of the device features controled via the control vq.
I like that.
Looks good. Will send v4.
Quoted 3 lines
Quoted 2 lines
Quoted 2 lines
Review \subsection{Device Operation}\label{sec:Device · line 396
Quoted 2 lines
(quoted diff) +1
-0+section \ref{sec:Device Types / Network Device / Device Operation /Control Virtqueue}.