* [virtio-dev] [PATCH 0/2] Minor improvements
@ 2023-04-20 12:46 David Edmondson
2023-04-20 12:46 ` [virtio-dev] [PATCH 1/2] virtio-net: Minor wording improvement David Edmondson
` (2 more replies)
0 siblings, 3 replies; 5+ messages in thread
From: David Edmondson @ 2023-04-20 12:46 UTC (permalink / raw)
To: virtio-comment, virtio-dev
A couple of minor improvements:
- add "and" between two "MUST",
- avoid using abbreviated flag names, making it easier to search the
specification for the actual flag names.
David Edmondson (2):
virtio-net: Minor wording improvement
virtio-net: Avoid abbreviating flag names
device-types/net/description.tex | 89 ++++++++++++++++++--------------
1 file changed, 50 insertions(+), 39 deletions(-)
--
2.39.2 (Apple Git-143)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 5+ messages in thread
* [virtio-dev] [PATCH 1/2] virtio-net: Minor wording improvement
2023-04-20 12:46 [virtio-dev] [PATCH 0/2] Minor improvements David Edmondson
@ 2023-04-20 12:46 ` David Edmondson
2023-04-20 18:08 ` [virtio-dev] Re: [virtio-comment] " Parav Pandit
2023-04-20 12:46 ` [virtio-dev] [PATCH 2/2] virtio-net: Avoid abbreviating flag names David Edmondson
2023-04-20 20:32 ` [virtio-dev] Re: [virtio-comment] [PATCH 0/2] Minor improvements Michael S. Tsirkin
2 siblings, 1 reply; 5+ messages in thread
From: David Edmondson @ 2023-04-20 12:46 UTC (permalink / raw)
To: virtio-comment, virtio-dev
Signed-off-by: David Edmondson <david.edmondson@oracle.com>
---
device-types/net/description.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index 875c4e6..8aa7953 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -815,7 +815,7 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
If \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE, then
the device MUST also set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in
-\field{flags} MUST set \field{gso_size} to indicate the desired MSS.
+\field{flags} and MUST set \field{gso_size} to indicate the desired MSS.
If VIRTIO_NET_F_RSC_EXT was negotiated, the device MUST also
set VIRTIO_NET_HDR_F_RSC_INFO bit in \field{flags},
set \field{csum_start} to number of coalesced TCP segments and
--
2.39.2 (Apple Git-143)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [virtio-dev] [PATCH 2/2] virtio-net: Avoid abbreviating flag names
2023-04-20 12:46 [virtio-dev] [PATCH 0/2] Minor improvements David Edmondson
2023-04-20 12:46 ` [virtio-dev] [PATCH 1/2] virtio-net: Minor wording improvement David Edmondson
@ 2023-04-20 12:46 ` David Edmondson
2023-04-20 20:32 ` [virtio-dev] Re: [virtio-comment] [PATCH 0/2] Minor improvements Michael S. Tsirkin
2 siblings, 0 replies; 5+ messages in thread
From: David Edmondson @ 2023-04-20 12:46 UTC (permalink / raw)
To: virtio-comment, virtio-dev
Use the full name for various flags when referencing them in the body
of the text.
Signed-off-by: David Edmondson <david.edmondson@oracle.com>
---
device-types/net/description.tex | 87 ++++++++++++++++++--------------
1 file changed, 49 insertions(+), 38 deletions(-)
diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index 8aa7953..106a1c7 100644
--- a/device-types/net/description.tex
+++ b/device-types/net/description.tex
@@ -472,14 +472,16 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
checksum includes the header), and \field{csum_offset} will be 16.
\end{note}
-\item If the driver negotiated
- VIRTIO_NET_F_HOST_TSO4, TSO6, USO or UFO, and the packet requires
- TCP segmentation, UDP segmentation or fragmentation, then \field{gso_type}
- is set to VIRTIO_NET_HDR_GSO_TCPV4, TCPV6, UDP_L4 or UDP.
- (Otherwise, it is set to VIRTIO_NET_HDR_GSO_NONE). In this
- case, packets larger than 1514 bytes can be transmitted: the
- metadata indicates how to replicate the packet header to cut it
- into smaller packets. The other gso fields are set:
+\item If the driver negotiated VIRTIO_NET_F_HOST_TSO4,
+ VIRTIO_NET_F_HOST_TSO6, VIRTIO_NET_F_HOST_USO or
+ VIRTIO_NET_F_HOST_UFO, and the packet requires TCP segmentation, UDP
+ segmentation or fragmentation, then \field{gso_type} is set to
+ VIRTIO_NET_HDR_GSO_TCPV4, VIRTIO_NET_HDR_GSO_TCPV6,
+ VIRTIO_NET_HDR_GSO_UDP_L4 or VIRTIO_NET_HDR_GSO_UDP. (Otherwise, it
+ is set to VIRTIO_NET_HDR_GSO_NONE). In this case, packets larger
+ than 1514 bytes can be transmitted: the metadata indicates how to
+ replicate the packet header to cut it into smaller packets. The
+ other gso fields are set:
\begin{itemize}
\item If the VIRTIO_NET_F_GUEST_HDRLEN feature has been negotiated,
@@ -564,8 +566,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
packet;
\end{enumerate}
-If none of the VIRTIO_NET_F_HOST_TSO4, TSO6, USO or UFO options have
-been negotiated, the driver MUST set \field{gso_type} to
+If none of the VIRTIO_NET_F_HOST_TSO4, VIRTIO_NET_F_HOST_TSO6,
+VIRTIO_NET_F_HOST_USO or VIRTIO_NET_F_HOST_UFO options have been
+negotiated, the driver MUST set \field{gso_type} to
VIRTIO_NET_HDR_GSO_NONE.
If \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE, then
@@ -573,8 +576,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
\field{flags} and MUST set \field{gso_size} to indicate the
desired MSS.
-If one of the VIRTIO_NET_F_HOST_TSO4, TSO6, USO or UFO options have
-been negotiated:
+If one of the VIRTIO_NET_F_HOST_TSO4, VIRTIO_NET_F_HOST_TSO6,
+VIRTIO_NET_F_HOST_USO or VIRTIO_NET_F_HOST_UFO options have been
+negotiated:
\begin{itemize}
\item If the VIRTIO_NET_F_GUEST_HDRLEN feature has been negotiated,
and \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE,
@@ -600,8 +604,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
If VIRTIO_NET_HDR_F_NEEDS_CSUM bit in \field{flags} is not set, the
device MUST NOT use the \field{csum_start} and \field{csum_offset}.
-If one of the VIRTIO_NET_F_HOST_TSO4, TSO6, USO or UFO options have
-been negotiated:
+If one of the VIRTIO_NET_F_HOST_TSO4, VIRTIO_NET_F_HOST_TSO6,
+VIRTIO_NET_F_HOST_USO or VIRTIO_NET_F_HOST_UFO options have been
+negotiated:
\begin{itemize}
\item If the VIRTIO_NET_F_GUEST_HDRLEN feature has been negotiated,
and \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE,
@@ -717,23 +722,26 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
has been validated.
\end{enumerate}
-Additionally, VIRTIO_NET_F_GUEST_CSUM, TSO4, TSO6, UDP and ECN
-features enable receive checksum, large receive offload and ECN
-support which are the input equivalents of the transmit checksum,
-transmit segmentation offloading and ECN features, as described
-in \ref{sec:Device Types / Network Device / Device Operation /
-Packet Transmission}:
+Additionally, VIRTIO_NET_F_GUEST_CSUM, VIRTIO_NET_F_GUEST_TSO4,
+VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UDP and
+VIRTIO_NET_F_GUEST_ECN features enable receive checksum, large receive
+offload and ECN support which are the input equivalents of the
+transmit checksum, transmit segmentation offloading and ECN features,
+as described in \ref{sec:Device Types / Network Device / Device
+ Operation / Packet Transmission}:
\begin{enumerate}
-\item If the VIRTIO_NET_F_GUEST_TSO4, TSO6, UFO, USO4 or USO6 options were
- negotiated, then \field{gso_type} MAY be something other than
+\item 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 options were negotiated, then
+ \field{gso_type} MAY be something other than
VIRTIO_NET_HDR_GSO_NONE, and \field{gso_size} field indicates the
desired MSS (see Packet Transmission point 2).
-\item If the VIRTIO_NET_F_RSC_EXT option was negotiated (this
- implies one of VIRTIO_NET_F_GUEST_TSO4, TSO6), the
- device processes also duplicated ACK segments, reports
- number of coalesced TCP segments in \field{csum_start} field and
- number of duplicated ACK segments in \field{csum_offset} field
- and sets bit VIRTIO_NET_HDR_F_RSC_INFO in \field{flags}.
+\item If the VIRTIO_NET_F_RSC_EXT option was negotiated (this implies
+ one of VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6), the device
+ processes also duplicated ACK segments, reports number of coalesced
+ TCP segments in \field{csum_start} field and number of duplicated
+ ACK segments in \field{csum_offset} field and sets bit
+ VIRTIO_NET_HDR_F_RSC_INFO in \field{flags}.
\item If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the
VIRTIO_NET_HDR_F_NEEDS_CSUM bit in \field{flags} can be
set: if so, the packet checksum at offset \field{csum_offset}
@@ -809,9 +817,10 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
fully checksummed packet;
\end{enumerate}
-If none of the VIRTIO_NET_F_GUEST_TSO4, TSO6, UFO, USO4 or USO6 options have
-been negotiated, the device MUST set \field{gso_type} to
-VIRTIO_NET_HDR_GSO_NONE.
+If none of 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 options have been negotiated, the device MUST
+set \field{gso_type} to VIRTIO_NET_HDR_GSO_NONE.
If \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE, then
the device MUST also set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in
@@ -824,10 +833,11 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
If VIRTIO_NET_F_RSC_EXT was not negotiated, the device MUST
not set VIRTIO_NET_HDR_F_RSC_INFO bit in \field{flags}.
-If one of the VIRTIO_NET_F_GUEST_TSO4, TSO6, UFO, USO4 or USO6 options have
-been negotiated, the device SHOULD set \field{hdr_len} to a value
-not less than the length of the headers, including the transport
-header.
+If one of 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 options have been negotiated, the device
+SHOULD set \field{hdr_len} to a value not less than the length of the
+headers, including the transport header.
If the VIRTIO_NET_F_GUEST_CSUM feature has been negotiated, the
device MAY set the VIRTIO_NET_HDR_F_DATA_VALID bit in
@@ -845,9 +855,10 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
if VIRTIO_NET_HDR_F_RSC_INFO bit \field{flags} is set, the
driver MUST NOT use the \field{csum_start} and \field{csum_offset}.
-If one of the VIRTIO_NET_F_GUEST_TSO4, TSO6, UFO, USO4 or USO6 options have
-been negotiated, the driver MAY use \field{hdr_len} only as a hint about the
-transport header size.
+If one of 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 options have been negotiated, the driver MAY
+use \field{hdr_len} only as a hint about the transport header size.
The driver MUST NOT rely on \field{hdr_len} to be correct.
\begin{note}
This is due to various bugs in implementations.
--
2.39.2 (Apple Git-143)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [virtio-dev] Re: [virtio-comment] [PATCH 1/2] virtio-net: Minor wording improvement
2023-04-20 12:46 ` [virtio-dev] [PATCH 1/2] virtio-net: Minor wording improvement David Edmondson
@ 2023-04-20 18:08 ` Parav Pandit
0 siblings, 0 replies; 5+ messages in thread
From: Parav Pandit @ 2023-04-20 18:08 UTC (permalink / raw)
To: David Edmondson, virtio-comment, virtio-dev
On 4/20/2023 8:46 AM, David Edmondson wrote:
> Signed-off-by: David Edmondson <david.edmondson@oracle.com>
> ---
> device-types/net/description.tex | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/device-types/net/description.tex b/device-types/net/description.tex
> index 875c4e6..8aa7953 100644
> --- a/device-types/net/description.tex
> +++ b/device-types/net/description.tex
> @@ -815,7 +815,7 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
>
> If \field{gso_type} differs from VIRTIO_NET_HDR_GSO_NONE, then
> the device MUST also set the VIRTIO_NET_HDR_F_NEEDS_CSUM bit in
> -\field{flags} MUST set \field{gso_size} to indicate the desired MSS.
> +\field{flags} and MUST set \field{gso_size} to indicate the desired MSS.
> If VIRTIO_NET_F_RSC_EXT was negotiated, the device MUST also
> set VIRTIO_NET_HDR_F_RSC_INFO bit in \field{flags},
> set \field{csum_start} to number of coalesced TCP segments and
Reviewed-by: Parav Pandit <parav@nvidia.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 5+ messages in thread
* [virtio-dev] Re: [virtio-comment] [PATCH 0/2] Minor improvements
2023-04-20 12:46 [virtio-dev] [PATCH 0/2] Minor improvements David Edmondson
2023-04-20 12:46 ` [virtio-dev] [PATCH 1/2] virtio-net: Minor wording improvement David Edmondson
2023-04-20 12:46 ` [virtio-dev] [PATCH 2/2] virtio-net: Avoid abbreviating flag names David Edmondson
@ 2023-04-20 20:32 ` Michael S. Tsirkin
2 siblings, 0 replies; 5+ messages in thread
From: Michael S. Tsirkin @ 2023-04-20 20:32 UTC (permalink / raw)
To: David Edmondson; +Cc: virtio-comment, virtio-dev
On Thu, Apr 20, 2023 at 01:46:45PM +0100, David Edmondson wrote:
> A couple of minor improvements:
> - add "and" between two "MUST",
> - avoid using abbreviated flag names, making it easier to search the
> specification for the actual flag names.
>
> David Edmondson (2):
> virtio-net: Minor wording improvement
> virtio-net: Avoid abbreviating flag names
>
> device-types/net/description.tex | 89 ++++++++++++++++++--------------
> 1 file changed, 50 insertions(+), 39 deletions(-)
Acked-by: Michael S. Tsirkin <mst@redhat.com>
seems like an editorial change. Cornelia, want to commit?
> --
> 2.39.2 (Apple Git-143)
>
>
> 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: virtio-comment-subscribe@lists.oasis-open.org
> Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
> List help: virtio-comment-help@lists.oasis-open.org
> 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/
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-04-20 20:32 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-04-20 12:46 [virtio-dev] [PATCH 0/2] Minor improvements David Edmondson
2023-04-20 12:46 ` [virtio-dev] [PATCH 1/2] virtio-net: Minor wording improvement David Edmondson
2023-04-20 18:08 ` [virtio-dev] Re: [virtio-comment] " Parav Pandit
2023-04-20 12:46 ` [virtio-dev] [PATCH 2/2] virtio-net: Avoid abbreviating flag names David Edmondson
2023-04-20 20:32 ` [virtio-dev] Re: [virtio-comment] [PATCH 0/2] Minor improvements Michael S. Tsirkin
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).