virtio-net: Define configuration field layout before its description
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
@@ -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
Quoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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
Signed-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0
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/
Quoted 12 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 8:49 AMQuoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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.htmlSigned-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Featurebits}\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_MACis set), and -\field{status} only exists ifVIRTIO_NET_F_STATUSis set. Two -read-only bits (for the driver) arecurrently 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 adriver.
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_MACis 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_STATUSis set. Two read-only bits (for the driver) are currently defined for the status field:VIRTIO_NET_S_LINK_UPandVIRTIO_NET_S_ANNOUNCE."Quoted 11 lines
\begin{lstlisting}
#defineVIRTIO_NET_S_LINK_UP1device-types/net/description.tex +0
-0@@ -188,19 +204,6 @@ \subsection{Device configurationlayout}\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_RSSor
VIRTIO_NET_F_HASH_REPORTis set.Quoted 1 line
It specifies the maximum supported length of RSS key in bytes.
Quoted 88 lines · Parav Pandit
Quoted 12 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 8:49 AMQuoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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.htmlSigned-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Featurebits}\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_MACis set), and -\field{status} only exists ifVIRTIO_NET_F_STATUSis set. Two -read-only bits (for the driver) arecurrently 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 adriver.
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_MACis 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_STATUSis set. Two read-only bits (for the driver) are currently defined for the status field:VIRTIO_NET_S_LINK_UPandVIRTIO_NET_S_ANNOUNCE."Quoted 11 lines
\begin{lstlisting}
#defineVIRTIO_NET_S_LINK_UP1device-types/net/description.tex +0
-0@@ -188,19 +204,6 @@ \subsection{Device configurationlayout}\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_RSSor
VIRTIO_NET_F_HASH_REPORTis set.Quoted 1 line
It specifies the maximum supported length of RSS key in bytes.
Quoted 11 lines · Parav Pandit
Quoted 11 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 8:49 AMQuoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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.htmlSigned-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Featurebits}\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_MACis set), and -\field{status} only exists ifVIRTIO_NET_F_STATUSis set. Two -read-only bits (for the driver) arecurrently 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 adriver.
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_MACis 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_STATUSis set. Two read-only bits (for the driver) are currently defined for the status field:VIRTIO_NET_S_LINK_UPandVIRTIO_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/
Quoted 23 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 10:50 AMQuoted 16 lines · Parav Pandit
Quoted 16 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 8:49 AMQuoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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
mlSigned-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Featurebits}\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_MACis set), and -\field{status} only exists ifVIRTIO_NET_F_STATUSis set. Two -read-only bits (for the driver) arecurrently 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 adriver.
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_MACis 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_STATUSis set. Two read-only bits (for the driver) are currently defined for the status field:VIRTIO_NET_S_LINK_UPandVIRTIO_NET_S_ANNOUNCE."
Quoted 118 lines · Parav Pandit
Quoted 23 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 10:50 AMQuoted 16 lines · Parav Pandit
Quoted 16 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 8:49 AMQuoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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
mlSigned-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Featurebits}\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_MACis set), and -\field{status} only exists ifVIRTIO_NET_F_STATUSis set. Two -read-only bits (for the driver) arecurrently 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 adriver.
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_MACis 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_CFGfor PCI and length field invirtio_pci_captells 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_STATUSis set. Two read-only bits (for the driver) are currently defined for the status field:VIRTIO_NET_S_LINK_UPandVIRTIO_NET_S_ANNOUNCE."
Quoted 133 lines
From: Michael S. Tsirkin <[email protected]>
Sent: Tuesday, February 7, 2023 4:58 PMQuoted 128 lines · Parav Pandit
Quoted 23 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 10:50 AMQuoted 16 lines · Parav Pandit
Quoted 16 lines
From: Cornelia Huck <[email protected]>
Sent: Tuesday, February 7, 2023 8:49 AMQuoted 5 lines · Parav Pandit
Currently some fields of the
virtio_net_configstructure are defined before introducing the structure and some are defined after introducingvirtio_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
mlSigned-off-by Parav Pandit <[email protected]>--- device-types/net/description.tex | 39 +++++++++++++++++--------------- 1 file changed, 21 insertions(+), 18 deletions(-)device-types/net/description.tex +0
-0@@ -154,11 +154,27 @@ \subsubsection{Legacy Interface: Featurebits}\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_MACis set), and -\field{status} only exists ifVIRTIO_NET_F_STATUSis set. Two -read-only bits (for the
driver) arecurrently 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 adriver.
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_MACis 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_CFGfor PCI and length field invirtio_pci_captellshow 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.