Skip to contentSkip to conversation

virtio-net: Define configuration field layout before its description

PATCH In review Parav Pandit 3 participants 8 messages Feb 3, 2023 – Feb 7, 2023

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 virtio-net: Define configuration field layout before its description

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

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

---
 device-types/net/description.tex | 39 +++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +21 -18
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network
 \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout}
 \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}
 
-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field
-always exists (though is only valid if VIRTIO_NET_F_MAC is set), and
-\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two
-read-only bits (for the driver) are currently defined for the status field:
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are read-only for a driver.
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;
+        u8 duplex;
+        u8 rss_max_key_size;
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types;
+};
+\end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid
+if VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver)
+are currently defined for the status field: VIRTIO_NET_S_LINK_UP
+and VIRTIO_NET_S_ANNOUNCE.
 
 \begin{lstlisting}
 #define VIRTIO_NET_S_LINK_UP     1
@@ -188,19 +204,6 @@ \subsection{Device configuration layout}\label{sec:Device Types / Network Device
 is expected to re-read these values after receiving a
 configuration change notification.
 
-\begin{lstlisting}
-struct virtio_net_config {
-        u8 mac[6];
-        le16 status;
-        le16 max_virtqueue_pairs;
-        le16 mtu;
-        le32 speed;
-        u8 duplex;
-        u8 rss_max_key_size;
-        le16 rss_max_indirection_table_length;
-        le32 supported_hash_types;
-};
-\end{lstlisting}
 The following field, \field{rss_max_key_size} only exists if VIRTIO_NET_F_RSS or VIRTIO_NET_F_HASH_REPORT is set.
 It specifies the maximum supported length of RSS key in bytes.
 
Signature · 1 line
2.26.2
#1 lore raw
Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Quoted 16 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

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

---
 device-types/net/description.tex | 39 +++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network · line 157

Quoted 9 lines
device-types/net/description.tex +1 -5
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network
 \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout}
 \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}
 
-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field
-always exists (though is only valid if VIRTIO_NET_F_MAC is set), and
-\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two
-read-only bits (for the driver) are currently defined for the status field:
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are read-only for a driver.

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

Quoted 10 lines
device-types/net/description.tex +10 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;
+        u8 duplex;
+        u8 rss_max_key_size;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network · line 177

Quoted 10 lines
device-types/net/description.tex +10 -0
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types;
+};
+\end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid
+if VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver)
+are currently defined for the status field: VIRTIO_NET_S_LINK_UP
+and VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are currently defined for the status field:
VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE."

Quoted 12 lines
device-types/net/description.tex +0 -5
 \begin{lstlisting}
 #define VIRTIO_NET_S_LINK_UP     1
@@ -188,19 +204,6 @@ \subsection{Device configuration layout}\label{sec:Device Types / Network Device
 is expected to re-read these values after receiving a
 configuration change notification.
 
-\begin{lstlisting}
-struct virtio_net_config {
-        u8 mac[6];
-        le16 status;
-        le16 max_virtqueue_pairs;

device-types/net/description.tex \subsection{Device configuration layout}\label{sec:Device Types / Network Device · line 208

Quoted 10 lines
device-types/net/description.tex +0 -8
-        le16 mtu;
-        le32 speed;
-        u8 duplex;
-        u8 rss_max_key_size;
-        le16 rss_max_indirection_table_length;
-        le32 supported_hash_types;
-};
-\end{lstlisting}
 The following field, \field{rss_max_key_size} only exists if VIRTIO_NET_F_RSS or VIRTIO_NET_F_HASH_REPORT is set.
 It specifies the maximum supported length of RSS key in bytes.

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

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

Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

Quoted 5 lines

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Yes. block can be improved too.
I will send separate patch for block side later.

Quoted 29 lines
Quoted 24 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

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

---
 device-types/net/description.tex | 39
+++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature

bits}\label{sec:Device Types / Network \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}

Quoted 4 lines

-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two -read-only bits (for the driver) are

currently defined for the status field:

Quoted 9 lines

device-types/net/description.tex

Quoted 2 lines
device-types/net/description.tex +1 -1
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are read-only for a

driver.

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

I want to avoid "uses" term. Because it is the device configuration layout built in the device. How about,
The network device has the following device configuration layout.

Quoted 23 lines
Quoted 10 lines
device-types/net/description.tex +10 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;
+        u8 duplex;
+        u8 rss_max_key_size;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network

Quoted 10 lines
device-types/net/description.tex +10 -0
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types;
+};
+\end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid if
+VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are
+currently defined for the status field: VIRTIO_NET_S_LINK_UP and
+VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

Quoted 3 lines

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

I want to avoid such change in this patch.
This whole section about "exist" is very confusing. Because structure layout is not going to change when field don't "exist". But that is counter intuitive for the term "exist". And hence the "exist" wording is incorrect.
The size of the configuration layout is totally defined by the transport.
And validity of the field is driven by the feature bit and at some extent structure size can be shorter depending on feature.
So I want to park this "exist" cleanup at later point.

Quoted 27 lines

\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are currently defined for the status field:
VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE."

Quoted 11 lines

\begin{lstlisting}
#define VIRTIO_NET_S_LINK_UP 1

device-types/net/description.tex +0 -0
@@ -188,19 +204,6 @@ \subsection{Device configuration

layout}\label{sec:Device Types / Network Device is expected to re-read these values after receiving a configuration change notification.

-\begin{lstlisting}

device-types/net/description.tex +0 -3
-struct virtio_net_config {
-        u8 mac[6];
-        le16 status;

device-types/net/description.tex \subsection{Device configuration layout}\label{sec:Device Types / Network Device

Quoted 10 lines
device-types/net/description.tex +0 -9
-        le16 max_virtqueue_pairs;
-        le16 mtu;
-        le32 speed;
-        u8 duplex;
-        u8 rss_max_key_size;
-        le16 rss_max_indirection_table_length;
-        le32 supported_hash_types;
-};
-\end{lstlisting}
 The following field, \field{rss_max_key_size} only exists if VIRTIO_NET_F_RSS

or VIRTIO_NET_F_HASH_REPORT is set.

Quoted 1 line

It specifies the maximum supported length of RSS key in bytes.

#3 lore raw
Quoted 88 lines · Parav Pandit
Quoted 12 lines

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

Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

Quoted 5 lines

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Yes. block can be improved too.
I will send separate patch for block side later.

Quoted 29 lines
Quoted 24 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

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

---
 device-types/net/description.tex | 39
+++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature

bits}\label{sec:Device Types / Network \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}

Quoted 4 lines

-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two -read-only bits (for the driver) are

currently defined for the status field:

Quoted 9 lines

device-types/net/description.tex

Quoted 2 lines
device-types/net/description.tex +1 -1
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are read-only for a

driver.

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

I want to avoid "uses" term. Because it is the device configuration layout built in the device. How about,
The network device has the following device configuration layout.

Quoted 23 lines
Quoted 10 lines
device-types/net/description.tex +10 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;
+        u8 duplex;
+        u8 rss_max_key_size;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network

Quoted 10 lines
device-types/net/description.tex +10 -0
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types;
+};
+\end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid if
+VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are
+currently defined for the status field: VIRTIO_NET_S_LINK_UP and
+VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

Quoted 3 lines

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

Quoted 6 lines

I want to avoid such change in this patch.
This whole section about "exist" is very confusing. Because structure layout is not going to change when field don't "exist". But that is counter intuitive for the term "exist". And hence the "exist" wording is incorrect.
The size of the configuration layout is totally defined by the transport.
And validity of the field is driven by the feature bit and at some extent structure size can be shorter depending on feature.
So I want to park this "exist" cleanup at later point.

Yes it's a thorny issue generally. We also have confusion between "valid if feature negotiated" and "valid if feature offered". and generally it is vague what does "feature negotiated" mean before FEATURES_OK is set.
I had a patch for that at some point, but there are old drivers that violate almost all thinkable rule you can come up with so we need to at least put in a bunch of disclaimers and be as permissive as we can.

Quoted 27 lines
Quoted 27 lines

\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are currently defined for the status field:
VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE."

Quoted 11 lines

\begin{lstlisting}
#define VIRTIO_NET_S_LINK_UP 1

device-types/net/description.tex +0 -0
@@ -188,19 +204,6 @@ \subsection{Device configuration

layout}\label{sec:Device Types / Network Device is expected to re-read these values after receiving a configuration change notification.

-\begin{lstlisting}

device-types/net/description.tex +0 -3
-struct virtio_net_config {
-        u8 mac[6];
-        le16 status;

device-types/net/description.tex \subsection{Device configuration layout}\label{sec:Device Types / Network Device

Quoted 10 lines
device-types/net/description.tex +0 -9
-        le16 max_virtqueue_pairs;
-        le16 mtu;
-        le32 speed;
-        u8 duplex;
-        u8 rss_max_key_size;
-        le16 rss_max_indirection_table_length;
-        le32 supported_hash_types;
-};
-\end{lstlisting}
 The following field, \field{rss_max_key_size} only exists if VIRTIO_NET_F_RSS

or VIRTIO_NET_F_HASH_REPORT is set.

Quoted 1 line

It specifies the maximum supported length of RSS key in bytes.

#4 lore raw
In reply to Parav Pandit
Quoted 11 lines · Parav Pandit
Quoted 11 lines

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

Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

Quoted 7 lines
Quoted 5 lines

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Yes. block can be improved too.
I will send separate patch for block side later.

I think there were one or two others; but I consider none of this urgent :)

Quoted 34 lines
Quoted 34 lines
Quoted 25 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

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

---
 device-types/net/description.tex | 39
+++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature

bits}\label{sec:Device Types / Network \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}

Quoted 4 lines

-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two -read-only bits (for the driver) are

currently defined for the status field:

device-types/net/description.tex

Quoted 2 lines
device-types/net/description.tex +1 -1
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are read-only for a

driver.

Quoted 8 lines
Quoted 5 lines

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

I want to avoid "uses" term. Because it is the device configuration layout built in the device. How about,
The network device has the following device configuration layout.

Works for me.

Quoted 24 lines
Quoted 24 lines
Quoted 11 lines
device-types/net/description.tex +10 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;
+        u8 duplex;
+        u8 rss_max_key_size;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network

Quoted 10 lines
device-types/net/description.tex +10 -0
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types;
+};
+\end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid if
+VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are
+currently defined for the status field: VIRTIO_NET_S_LINK_UP and
+VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

Quoted 4 lines
Quoted 3 lines

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

I want to avoid such change in this patch.

This is only splitting up the sentence and tweaking the grammar, which I consider a rather minor change.

Quoted 2 lines

This whole section about "exist" is very confusing. Because structure layout is not going to change when field don't "exist". But that is counter intuitive for the term "exist". And hence the "exist" wording is incorrect.

I think we have been through that discussion before... would need to look through the archives.

Quoted 1 line

The size of the configuration layout is totally defined by the transport.

No, the transport only defines how the config is accessed?

Quoted 2 lines

And validity of the field is driven by the feature bit and at some extent structure size can be shorter depending on feature. So I want to park this "exist" cleanup at later point.

Certainly, this patch should only do a simple cleanup.

Quoted 3 lines
Quoted 3 lines

\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are currently defined for the status field:
VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE."

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

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

Quoted 16 lines · Parav Pandit
Quoted 16 lines

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

Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Quoted 6 lines
Quoted 2 lines

Yes. block can be improved too.
I will send separate patch for block side later.

I think there were one or two others; but I consider none of this urgent :)

o.k.
Will look into it.

Quoted 42 lines
Quoted 42 lines
Quoted 42 lines
Quoted 26 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

[1]
https://lists.oasis-open.org/archives/virtio-dev/202302/msg00004.ht
ml

---
 device-types/net/description.tex | 39
+++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature

bits}\label{sec:Device Types / Network \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}

Quoted 5 lines

-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two -read-only bits (for the driver) are

currently defined for the status field:

device-types/net/description.tex

Quoted 3 lines
device-types/net/description.tex +2 -1
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are
+read-only for a

driver.

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

Quoted 7 lines
Quoted 1 line

I want to avoid "uses" term. Because it is the device configuration layout built

in the device.

Quoted 2 lines

How about,
The network device has the following device configuration layout.

Works for me.

Ok.

Quoted 33 lines
Quoted 22 lines
Quoted 22 lines
Quoted 9 lines
device-types/net/description.tex +8 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network · line 177

Quoted 10 lines
device-types/net/description.tex +10 -0
+        u8 duplex;
+        u8 rss_max_key_size;
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types; }; \end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid
+if VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver)
+are currently defined for the status field: VIRTIO_NET_S_LINK_UP
+and VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

Quoted 4 lines
Quoted 3 lines

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

I want to avoid such change in this patch.

This is only splitting up the sentence and tweaking the grammar, which I consider a rather minor change.

Quoted 1 line

This whole section about "exist" is very confusing. Because structure layout is

not going to change when field don't "exist". But that is counter intuitive for the term "exist".

Quoted 9 lines
Quoted 1 line

And hence the "exist" wording is incorrect.

I think we have been through that discussion before... would need to look through the archives.

Quoted 1 line

The size of the configuration layout is totally defined by the transport.

No, the transport only defines how the config is accessed?

VIRTIO_PCI_CAP_DEVICE_CFG for PCI and length field in virtio_pci_cap tells how big the config layout. Rest of the "existence" complexity I explained above.

Quoted 6 lines
Quoted 1 line

And validity of the field is driven by the feature bit and at some extent

structure size can be shorter depending on feature.

Quoted 1 line

So I want to park this "exist" cleanup at later point.

Certainly, this patch should only do a simple cleanup.

Ok. Will send v2.

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are currently defined for the status field:
VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE."

#6 lore raw
Quoted 118 lines · Parav Pandit
Quoted 23 lines

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

Quoted 16 lines · Parav Pandit
Quoted 16 lines

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

Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Quoted 6 lines
Quoted 2 lines

Yes. block can be improved too.
I will send separate patch for block side later.

I think there were one or two others; but I consider none of this urgent :)

o.k.
Will look into it.

Quoted 42 lines
Quoted 42 lines
Quoted 42 lines
Quoted 26 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

[1]
https://lists.oasis-open.org/archives/virtio-dev/202302/msg00004.ht
ml

---
 device-types/net/description.tex | 39
+++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature

bits}\label{sec:Device Types / Network \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}

Quoted 5 lines

-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two -read-only bits (for the driver) are

currently defined for the status field:

device-types/net/description.tex

Quoted 3 lines
device-types/net/description.tex +2 -1
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are
+read-only for a

driver.

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

Quoted 7 lines
Quoted 1 line

I want to avoid "uses" term. Because it is the device configuration layout built

in the device.

Quoted 2 lines

How about,
The network device has the following device configuration layout.

Works for me.

Ok.

Quoted 35 lines
Quoted 22 lines
Quoted 22 lines
Quoted 9 lines
device-types/net/description.tex +8 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network · line 177

Quoted 10 lines
device-types/net/description.tex +10 -0
+        u8 duplex;
+        u8 rss_max_key_size;
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types; }; \end{lstlisting}
+
+The \field{mac} address field always exists (though is only valid
+if VIRTIO_NET_F_MAC is set), and \field{status} only exists if
+VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver)
+are currently defined for the status field: VIRTIO_NET_S_LINK_UP
+and VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

Quoted 4 lines
Quoted 3 lines

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

I want to avoid such change in this patch.

This is only splitting up the sentence and tweaking the grammar, which I consider a rather minor change.

Quoted 1 line

This whole section about "exist" is very confusing. Because structure layout is

not going to change when field don't "exist". But that is counter intuitive for the term "exist".

Quoted 1 line

And hence the "exist" wording is incorrect.

Quoted 8 lines
Quoted 7 lines

I think we have been through that discussion before... would need to look through the archives.

Quoted 1 line

The size of the configuration layout is totally defined by the transport.

No, the transport only defines how the config is accessed?

VIRTIO_PCI_CAP_DEVICE_CFG for PCI and length field in virtio_pci_cap tells how big the config layout.

There's explicit text in the spec saying this can be larger than necessary. So length there does not indicate field existence at all.

Quoted 13 lines

Rest of the "existence" complexity I explained above.

Quoted 6 lines
Quoted 1 line

And validity of the field is driven by the feature bit and at some extent

structure size can be shorter depending on feature.

Quoted 1 line

So I want to park this "exist" cleanup at later point.

Certainly, this patch should only do a simple cleanup.

Ok. Will send v2.

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for the driver) are currently defined for the status field:
VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE."

#7 lore raw
Quoted 133 lines

From: Michael S. Tsirkin <[email protected]>
Sent: Tuesday, February 7, 2023 4:58 PM

Quoted 128 lines · Parav Pandit
Quoted 23 lines

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

Quoted 16 lines · Parav Pandit
Quoted 16 lines

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

Quoted 5 lines · Parav Pandit

Currently some fields of the virtio_net_config structure are defined before introducing the structure and some are defined after introducing virtio_net_config.
Better to define the configuration layout first followed by description of all the fields.

I see that some other devices (e.g. block) list the config layout _after_ all of the descriptions, although I think listing first and then describing is the better approach. However, in-between is the worst order, and just cleaning up this one right now makes sense.

Quoted 7 lines
Quoted 2 lines

Yes. block can be improved too.
I will send separate patch for block side later.

I think there were one or two others; but I consider none of this urgent
:)

o.k.
Will look into it.

Quoted 44 lines
Quoted 44 lines
Quoted 44 lines
Quoted 27 lines

Device configuration fields are described in the section. Change wording from 'listed' to 'described' as suggested in patch [1].

[1]
https://lists.oasis-open.org/archives/virtio-dev/202302/msg0000
4.ht
ml

---
 device-types/net/description.tex | 39
+++++++++++++++++---------------
 1 file changed, 21 insertions(+), 18 deletions(-)
device-types/net/description.tex +0 -0
index dedd6b1..d4f598b 100644
@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Feature

bits}\label{sec:Device Types / Network \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}

Quoted 6 lines

-Device configuration fields are listed below, they are read-only for a driver. The \field{mac} address field -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two -read-only bits (for the
driver) are

currently defined for the status field:

device-types/net/description.tex

Quoted 3 lines
device-types/net/description.tex +2 -1
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
+Device configuration fields are described below, they are
+read-only for a

driver.

Maybe replace that with:

"The network device uses the following device configuration layout. The fields are read-only for the driver."

Quoted 8 lines
Quoted 2 lines

I want to avoid "uses" term. Because it is the device configuration layout built

in the device.

Quoted 2 lines

How about,
The network device has the following device configuration layout.

Works for me.

Ok.

Quoted 41 lines
Quoted 22 lines
Quoted 22 lines
Quoted 9 lines
device-types/net/description.tex +8 -0
+
+\begin{lstlisting}
+struct virtio_net_config {
+        u8 mac[6];
+        le16 status;
+        le16 max_virtqueue_pairs;
+        le16 mtu;
+        le32 speed;

device-types/net/description.tex \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network

Quoted 10 lines
device-types/net/description.tex +10 -0
+        u8 duplex;
+        u8 rss_max_key_size;
+        le16 rss_max_indirection_table_length;
+        le32 supported_hash_types; }; \end{lstlisting}
+
+The \field{mac} address field always exists (though is only
+valid if VIRTIO_NET_F_MAC is set), and \field{status} only
+exists if VIRTIO_NET_F_STATUS is set. Two read-only bits (for
+the driver) are currently defined for the status field:
+VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.

As you are touching this anyway, maybe break it up?

Quoted 4 lines
Quoted 3 lines

"The \field{mac} address field always exists (although it is only valid if VIRTIO_NET_F_MAC is set).

I want to avoid such change in this patch.

This is only splitting up the sentence and tweaking the grammar, which I consider a rather minor change.

Quoted 2 lines

This whole section about "exist" is very confusing. Because structure layout is

not going to change when field don't "exist". But that is counter intuitive for the term "exist".

Quoted 1 line

And hence the "exist" wording is incorrect.

I think we have been through that discussion before... would need to look through the archives.

Quoted 1 line

The size of the configuration layout is totally defined by the transport.

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

No, the transport only defines how the config is accessed?

VIRTIO_PCI_CAP_DEVICE_CFG for PCI and length field in virtio_pci_cap tells

how big the config layout.

There's explicit text in the spec saying this can be larger than necessary. So length there does not indicate field existence at all.

It can be larger but has to be minimum upto the length that accommodate the published features bits.