virtio-net: Clarify virtio_net_hdr size and rx buffer size
v5 cover virtio-net: Clarify virtio_net_hdr size and rx buffer size
There are few small issues around size of receive buffer and size of the struct virtio_net_hdr as following.
1. VIRTIO_NET_F_HASH_REPORT is only applicable on the rx side processing. However it changes the size of the struct virtio_net_hdr for the tx side as well. This was not clarified when VIRTIO_NET_F_HASH_REPORT feature was introduced.
2. Receive buffer size calculation description and requirements did not reflect negotiation of VIRTIO_NET_F_HASH_REPORT.
3. Receive buffer size calculation was incorrect for ipv6 guest gso feature.
Above issue 2 was reported in [1].
Since issue 2 and 3 both touches the same set of requirements and description, they are updated under a new issue along with tx side fix as well touching the clarification needed for VIRTIO_NET_F_HASH_REPORT.
Hence above three issues are fixed under issue of [2].
Patch summary:
patch-1 fixes receive side description and requirement patch-2 adds transmit side clarification for VIRTIO_NET_F_HASH_REPORT patch-3 to fix virtio_net_hdr annotation
changelog:v4->v5:
- added vnet hdr structure annotation patchv3->v4:
- addressed comments from Cornelia
- rephrase for virtio_net_hdr size calculationv2->v3:
- addressed comments from Cornelia and Xuan
- added virtio_net_hdr inclusion description in buffer size calculation text
- rephrase tx to refer to the rx side virtio_net_hdr consideration
- addressed comments from Xuan
- replaced 'field' with 'structure'v1->v2:
- addressed comments from Cornelia
- rephrase buffer size wording without explicit length of virtio_net_hdr at 3 places.
- replaced otherwise to ', otherwise'
- rephrase non normative to write as driver normativev0->v1:
- addressed comments from Xuan to rewrite tx normative
Parav Pandit (3):
virtio-net: Fix receive buffer size calculation text
virtio-net: Clarify the size of the struct virtio_net_hdr for tx
virtio-net: Annotate virtio_net_hdr as field
device-types/net/description.tex | 37 ++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 11 deletions(-)
Signature · 1 line
2.34.1
PATCH v5 1/3 virtio-net: Fix receive buffer size calculation text
Receive buffer size calculation is based on the following negotiated features.
The text has wrong calculation for IPv6 and also it has missed VIRTIO_NET_F_HASH_REPORT.
The problem of igorance of VIRTIO_NET_F_HASH_REPORT is reported in [1], however fix for ipv6 payload length must also be considered.
Since for the both the fixes touching same requirements, a new issue is created as [2].
This patch brings following fixes.
1. Fix annotating struct virtio_net_hdr as field
2. Fix receive buffer calculation for guest GSO cases to consider ipv6 payload length
3. small grammar corrections for article
4. reword the requirement to consider the virtio_ndr_hdr which is depends on the negotiated feature, hence first clarify the struct virtio_net_hdr size
[1] https://github.com/oasis-tcs/virtio-spec/issues/170
[2] https://github.com/oasis-tcs/virtio-spec/issues/183
---
changelog:v3->v4:
- addressed comments from Cornelia
- rephrase for virtio_net_hdr size calculationv2->v3:
- addressed comments from Cornelia
- added virtio_net_hdr inclusion description in buffer size calculation text v1->v2:
- addressed comments from Cornelia
- rephrase buffer size wording without explicit length of virtio_net_hdr at 3 places.
- replaced otherwise to ', otherwise'
- rephrase non normative to write as driver normative
--- device-types/net/description.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-)
device-types/net/description.tex +19 -7
@@ -660,10 +660,15 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 features are used, the maximum incoming packet -will be to 65550 bytes long (the maximum size of a -TCP or UDP packet, plus the 14 byte ethernet header), otherwise -1514 bytes. The 12-byte struct virtio_net_hdr is prepended to this, -making for 65562 or 1526 bytes. +will be 65589 bytes long (14 bytes of Ethernet header, plus 40 bytes of +the IPv6 header, plus 65535 bytes of maximum IPv6 payload including any +extension header), otherwise 1514 bytes. +When VIRTIO_NET_F_HASH_REPORT is not negotiated, the required receive buffer +size is either 65601 or 1526 bytes accounting for 20 bytes of +\field{struct virtio_net_hdr} followed by receive packet. +When VIRTIO_NET_F_HASH_REPORT is negotiated, the required receive buffer +size is either 65609 or 1534 bytes accounting for 12 bytes of +\field{struct virtio_net_hdr} followed by receive packet. \drivernormative{\paragraph}{Setting Up Receive Buffers}{Device Types / Network Device / Device Operation / Setting Up Receive Buffers}
@@ -672,18 +677,25 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi \begin{itemize} \item If VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 are negotiated, the driver SHOULD populate - the receive queue(s) with buffers of at least 65562 bytes. + the receive queue(s) with buffers of at least 65609 bytes if + VIRTIO_NET_F_HASH_REPORT is negotiated, and of at least 65601 bytes if not. \item Otherwise, the driver SHOULD populate the receive queue(s) - with buffers of at least 1526 bytes. + with buffers of at least 1534 bytes if VIRTIO_NET_F_HASH_REPORT + is negotiated, and of at least 1526 bytes if not. \end{itemize} \item If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer MUST be at -least the size of the struct virtio_net_hdr. +least size of \field{struct virtio_net_hdr}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. \end{itemize} \begin{note} Obviously each buffer can be split across multiple descriptor elements. \end{note} +When calculating the size of \field{struct virtio_net_hdr}, the driver +must consider all the fields inclusive up to \field{padding_reserved}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. + If VIRTIO_NET_F_MQ is negotiated, each of receiveq1\ldots receiveqN that will be used SHOULD be populated with receive buffers.
Signature · 1 line
2.34.1
Re: [PATCH v5 1/3] virtio-net: Fix receive buffer size calculation text
Quoted 86 lines · Parav Pandit
Receive buffer size calculation is based on the following negotiated features.
The text has wrong calculation for IPv6 and also it has missed
VIRTIO_NET_F_HASH_REPORT.The problem of igorance of
VIRTIO_NET_F_HASH_REPORTis reported in [1], however fix for ipv6 payload length must also be considered.Since for the both the fixes touching same requirements, a new issue is created as [2].
This patch brings following fixes.
1. Fix annotating struct
virtio_net_hdras field
2. Fix receive buffer calculation for guest GSO cases to consider ipv6 payload length
3. small grammar corrections for article
4. reword the requirement to consider thevirtio_ndr_hdrwhich is depends on the negotiated feature, hence first clarify the structvirtio_net_hdrsize[1] https://github.com/oasis-tcs/virtio-spec/issues/170
[2] https://github.com/oasis-tcs/virtio-spec/issues/183Signed-off-by Parav Pandit <[email protected]>---
changelog:v3->v4:
- addressed comments from Cornelia
- rephrase forvirtio_net_hdrsize calculationv2->v3:
- addressed comments from Cornelia
- addedvirtio_net_hdrinclusion description in buffer size calculation textv1->v2:
- addressed comments from Cornelia
- rephrase buffer size wording without explicit length ofvirtio_net_hdrat 3 places.
- replaced otherwise to ', otherwise'
- rephrase non normative to write as driver normative--- device-types/net/description.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-)device-types/net/description.tex +13
-7@@ -660,10 +660,15 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 features are used, the maximum incoming packet -will be to 65550 bytes long (the maximum size of a -TCP or UDP packet, plus the 14 byte ethernet header), otherwise -1514 bytes. The 12-byte struct virtio_net_hdr is prepended to this, -making for 65562 or 1526 bytes. +will be 65589 bytes long (14 bytes of Ethernet header, plus 40 bytes of +the IPv6 header, plus 65535 bytes of maximum IPv6 payload including any +extension header), otherwise 1514 bytes. +When VIRTIO_NET_F_HASH_REPORT is not negotiated, the required receive buffer +size is either 65601 or 1526 bytes accounting for 20 bytes of +\field{struct virtio_net_hdr} followed by receive packet. +When VIRTIO_NET_F_HASH_REPORT is negotiated, the required receive buffer +size is either 65609 or 1534 bytes accounting for 12 bytes of +\field{struct virtio_net_hdr} followed by receive packet. \drivernormative{\paragraph}{Setting Up Receive Buffers}{Device Types / Network Device / Device Operation / Setting Up Receive Buffers}@@ -672,18 +677,25 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi \begin{itemize} \item If VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 are negotiated, the driver SHOULD populate - the receive queue(s) with buffers of at least 65562 bytes. + the receive queue(s) with buffers of at least 65609 bytes if + VIRTIO_NET_F_HASH_REPORT is negotiated, and of at least 65601 bytes if not. \item Otherwise, the driver SHOULD populate the receive queue(s) - with buffers of at least 1526 bytes. + with buffers of at least 1534 bytes if VIRTIO_NET_F_HASH_REPORT + is negotiated, and of at least 1526 bytes if not. \end{itemize} \item If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer MUST be at -least the size of the struct virtio_net_hdr.
device-types/net/description.tex \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi · line 696
Quoted 10 lines
device-types/net/description.tex +4
-0+least size of \field{struct virtio_net_hdr}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. \end{itemize} \begin{note} Obviously each buffer can be split across multiple descriptor elements. \end{note} +When calculating the size of \field{struct virtio_net_hdr}, the driver +must consider all the fields inclusive up to \field{padding_reserved},
MUST?
Beside this.
Quoted 8 lines
device-types/net/description.tex +2
-1+i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. + If VIRTIO_NET_F_MQ is negotiated, each of receiveq1\ldots receiveqN that will be used SHOULD be populated with receive buffers. --2.34.1
PATCH v5 2/3 virtio-net: Clarify the size of the struct virtio_net_hdr for tx
In reply to Parav PanditThe feature VIRTIO_NET_F_HASH_REPORT only applies to the receive side. However, when VIRTIO_NET_F_HASH_REPORT feature was introduced, it was not clarified that the size of the struct virtio_net_hdr on the packet transmission also uses higher size when VIRTIO_NET_F_HASH_REPORT is negotiated.
Explicitly clarify this.
---
changelog:v2->v3:
- rephrase tx to refer to the rx side virtio_net_hdr consideration
- addressed comments from Xuan
- replaced 'field' with 'structure'v0->v1:
- addressed comments from Xuan to rewrite tx normative
--- device-types/net/description.tex | 3 +++ 1 file changed, 3 insertions(+)
device-types/net/description.tex +3 -0
@@ -531,6 +531,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De \drivernormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission} +For the transmit packet buffer, the driver MUST use the size of the +structure \field{struct virtio_net_hdr} same as the receive packet buffer. + The driver MUST set \field{num_buffers} to zero. If VIRTIO_NET_F_CSUM is not negotiated, the driver MUST set
Signature · 1 line
2.34.1
Re: [PATCH v5 2/3] virtio-net: Clarify the size of the struct virtio_net_hdr for tx
Quoted 10 lines · Parav Pandit
The feature
VIRTIO_NET_F_HASH_REPORTonly applies to the receive side. However, whenVIRTIO_NET_F_HASH_REPORTfeature was introduced, it was not clarified that the size of the structvirtio_net_hdron the packet transmission also uses higher size whenVIRTIO_NET_F_HASH_REPORTis negotiated.Explicitly clarify this.
Quoted 30 lines
---
changelog:v2->v3:
- rephrase tx to refer to the rx sidevirtio_net_hdrconsideration
- addressed comments from Xuan
- replaced 'field' with 'structure'v0->v1:
- addressed comments from Xuan to rewrite tx normative--- device-types/net/description.tex | 3 +++ 1 file changed, 3 insertions(+)device-types/net/description.tex +3
-1@@ -531,6 +531,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De \drivernormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission} +For the transmit packet buffer, the driver MUST use the size of the +structure \field{struct virtio_net_hdr} same as the receive packet buffer. + The driver MUST set \field{num_buffers} to zero. If VIRTIO_NET_F_CSUM is not negotiated, the driver MUST set --2.34.1
PATCH v5 3/3 virtio-net: Annotate virtio_net_hdr as field
In reply to Parav PanditAt several places struct virtio_net_hdr missed out the field annotation. Add it.
--- device-types/net/description.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
device-types/net/description.tex +4 -4
@@ -437,11 +437,11 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O \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 -MUST format the fields in struct virtio_net_hdr +MUST format the fields in \field{struct virtio_net_hdr} according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. -The legacy driver only presented \field{num_buffers} in the struct virtio_net_hdr +The legacy driver only presented \field{num_buffers} in the \field{struct virtio_net_hdr} when VIRTIO_NET_F_MRG_RXBUF was negotiated; without that feature the structure was 2 bytes shorter.
@@ -735,7 +735,7 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network chains them together to form a single packet in a way similar to how it would store it in a single buffer spread over multiple descriptors. - The other buffers will not begin with a struct virtio_net_hdr. + The other buffers will not begin with a \field{struct virtio_net_hdr}. \item If \field{num_buffers} is one, then the entire packet will be
@@ -2416,7 +2416,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device When using legacy interfaces, transitional drivers which have not negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the -struct virtio_net_hdr on both transmit and receive, with the +\field{struct virtio_net_hdr} on both transmit and receive, with the network data in the following descriptors. Additionally, when using the control virtqueue (see \ref{sec:Device
Signature · 1 line
2.34.1
Re: [PATCH v5 3/3] virtio-net: Annotate virtio_net_hdr as field
Quoted 4 lines · Parav Pandit
At several places struct
virtio_net_hdrmissed out the field annotation. Add it.Signed-off-by Parav Pandit <[email protected]>
Quoted 43 lines
--- device-types/net/description.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)device-types/net/description.tex +4
-5@@ -437,11 +437,11 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O \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 -MUST format the fields in struct virtio_net_hdr +MUST format the fields in \field{struct virtio_net_hdr} according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. -The legacy driver only presented \field{num_buffers} in the struct virtio_net_hdr +The legacy driver only presented \field{num_buffers} in the \field{struct virtio_net_hdr} when VIRTIO_NET_F_MRG_RXBUF was negotiated; without that feature the structure was 2 bytes shorter.@@ -735,7 +735,7 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network chains them together to form a single packet in a way similar to how it would store it in a single buffer spread over multiple descriptors. - The other buffers will not begin with a struct virtio_net_hdr. + The other buffers will not begin with a \field{struct virtio_net_hdr}. \item If \field{num_buffers} is one, then the entire packet will be@@ -2416,7 +2416,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device When using legacy interfaces, transitional drivers which have not negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the -struct virtio_net_hdr on both transmit and receive, with the +\field{struct virtio_net_hdr} on both transmit and receive, with the network data in the following descriptors. Additionally, when using the control virtqueue (see \ref{sec:Device --2.34.1