Skip to contentSkip to conversation

virtio-net: Improve introductory description

PATCH In review Parav Pandit 3 participants 11 messages Feb 14, 2023 – Feb 20, 2023

lore
Share & tools
lore
#0 lore raw

PATCH v6 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.

---
changelog:
v5->v6:
- changed 'many' to 'various'
- rebased
v4->v5:
- fixed typo from virtuqueue to virtqueue
v3->v4:
- write buffer add/remove, instead of enqueue/dequeue, post
- changed 'many' to 'various'
v2->v3:
- further improve introduction
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 | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)
device-types/net/description.tex +13 -10
index 88a5770..a197e1a 100644
@@ -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 adds empty buffers to the receive virtqueue.
+The device receives incoming packets from the link; the device
+places these incoming packets in the receive virtqueue buffers.
+The driver adds outgoing packets to the transmit virtqueue. The device
+removes these packets from the transmit virtqueue and sends them to
+the link. The device may have a control virtqueue. 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 various 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 7 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.

Quoted 6 lines

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

Are you requesting a vote for this?

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 13 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

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

Quoted 8 lines
Quoted 6 lines

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

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better description, structure movement. Please advise if we need voting.

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

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

Quoted 10 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.

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better description, structure movement. Please advise if we need voting.

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

This is way beyond that. And generally when in doubt vote.

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

From: Michael S. Tsirkin <[email protected]>
Sent: Thursday, February 16, 2023 10:50 AM

Quoted 16 lines · Parav Pandit
Quoted 16 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

Quoted 10 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.

Quoted 7 lines
Quoted 5 lines
Quoted 3 lines

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better

description, structure movement.

Quoted 1 line

Please advise if we need voting.

Quoted 7 lines

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

This is way beyond that. And generally when in doubt vote.

Ok. Thanks for the direction.

Can you please create the voting ballot?
Git hub issue of interest is: Fixes: https://github.com/oasis-tcs/virtio-spec/issues/156

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/

#5 lore raw
Quoted 10 lines

From: Parav Pandit
Sent: Thursday, February 16, 2023 11:01 AM

Quoted 6 lines

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

Quoted 7 lines
Quoted 1 line

This is way beyond that. And generally when in doubt vote.

Ok. Thanks for the direction.

Can you please create the voting ballot?
Git hub issue of interest is: Fixes: https://github.com/oasis-tcs/virtio-
spec/issues/156

Just seeing now, you already created, thanks.

#6 lore raw
In reply to Michael S. Tsirkin
Quoted 27 lines · Michael S. Tsirkin
Quoted 16 lines · Parav Pandit
Quoted 16 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

Quoted 10 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.

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better description, structure movement. Please advise if we need voting.

Quoted 7 lines

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

This is way beyond that. And generally when in doubt vote.

Agreed.

(Btw: the github issue needs to be updated to point to the latest version of the patch, it still points to v1.)

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/

#7 lore raw
Quoted 40 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 11:03 AM

Quoted 17 lines · Michael S. Tsirkin
Quoted 16 lines · Parav Pandit
Quoted 16 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

Quoted 10 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.

Quoted 7 lines
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better

description, structure movement.

Quoted 9 lines
Quoted 1 line

Please advise if we need voting.

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

Quoted 6 lines
Quoted 1 line

This is way beyond that. And generally when in doubt vote.

Agreed.

(Btw: the github issue needs to be updated to point to the latest version of the patch, it still points to v1.)

Done.

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/

#8 lore raw
Quoted 39 lines · Parav Pandit
Quoted 39 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 11:03 AM

Quoted 17 lines · Michael S. Tsirkin
Quoted 16 lines · Parav Pandit
Quoted 16 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

Quoted 10 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.

Quoted 7 lines
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better

description, structure movement.

Quoted 9 lines
Quoted 1 line

Please advise if we need voting.

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

Quoted 8 lines
Quoted 6 lines
Quoted 1 line

This is way beyond that. And generally when in doubt vote.

Agreed.

(Btw: the github issue needs to be updated to point to the latest version of the patch, it still points to v1.)

Done.

Do you request to withdraw the ballot, so that we can start a new ballot with the proper URL?

(Sorry about being a stickler for process here.)

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

#9 lore raw
Quoted 53 lines

From: [email protected] <[email protected]> On Behalf Of Cornelia Huck

Quoted 47 lines · Parav Pandit
Quoted 46 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 11:03 AM

Quoted 17 lines · Michael S. Tsirkin
Quoted 16 lines · Parav Pandit
Quoted 16 lines

From: Cornelia Huck <[email protected]>
Sent: Thursday, February 16, 2023 9:10 AM

Quoted 10 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.

Quoted 8 lines
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

Are you requesting a vote for this?

I was not sure if its need voting as most are editorial cleanups, better

description, structure movement.

Quoted 10 lines
Quoted 1 line

Please advise if we need voting.

The bylaws are here:
https://github.com/oasis-tcs/virtio-spec/blob/master/README.md
Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.

This is way beyond that. And generally when in doubt vote.

Agreed.

(Btw: the github issue needs to be updated to point to the latest version of the patch, it still points to v1.)

Quoted 6 lines
Quoted 1 line

Done.

Do you request to withdraw the ballot, so that we can start a new ballot with the proper URL?

(Sorry about being a stickler for process here.)

Yes, can you please withdraw the ballot [1] as it contains stale reference to the patch?

[1] https://www.oasis-open.org/apps/org/workgroup/virtio/ballot.php?id=3758

Also please create new ballot as the github link is now updated for the issue [2].
[2] https://github.com/oasis-tcs/virtio-spec/issues/156

#10 lore raw
Quoted 6 lines · Parav Pandit

Yes, can you please withdraw the ballot [1] as it contains stale reference to the patch?

[1] https://www.oasis-open.org/apps/org/workgroup/virtio/ballot.php?id=3758

Also please create new ballot as the github link is now updated for the issue [2].
[2] https://github.com/oasis-tcs/virtio-spec/issues/156

Done.

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/