virtio-net: receive-side scaling

Typo/grammar fixes as suggested by Cornelia (and a couple
noticed by myself).

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>

1 files changed, 50 insertions, 33 deletions

diff --git a/content.tex b/content.tex
index 8c8f3bb..e9d5148 100644
--- a/content.tex
+++ b/content.tex
@@ -2980,11 +2980,11 @@ struct virtio_net_config {
 Three following fields, \field{rss_max_key_size}, \field{rss_max_indirection_table_length}
 and \field{supported_hash_types} only exist if VIRTIO_NET_F_RSS is set.
 
-Field \field{rss_max_key_size} specifies maximal supported length of RSS key in bytes.
+Field \field{rss_max_key_size} specifies the maximal supported length of RSS key in bytes.
 
-Field \field{rss_max_indirection_table_length} specifies maximal number of 16-bit entries in RSS indirection table.
+Field \field{rss_max_indirection_table_length} specifies the maximal number of 16-bit entries in RSS indirection table.
 
-Field \field{supported_hash_types} contains bitmask of supported RSS hash types.
+Field \field{supported_hash_types} contains the bitmask of supported RSS hash types.
 
 Hash types applicable for IPv4 packets:
 \begin{lstlisting}
@@ -3004,7 +3004,7 @@ Hash types applicable for IPv6 packets with extension headers
 #define VIRTIO_NET_RSS_HASH_TYPE_TCP_EX            (1 << 7)
 #define VIRTIO_NET_RSS_HASH_TYPE_UDP_EX            (1 << 8)
 \end{lstlisting}
-For exact meaning of VIRTIO_NET_RSS_HASH_TYPE_ flags see \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types}.
+For the exact meaning of VIRTIO_NET_RSS_HASH_TYPE_ flags see \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types}.
 
 \devicenormative{\subsubsection}{Device configuration layout}{Device Types / Network Device / Device configuration layout}
 
@@ -3838,12 +3838,12 @@ before marking the buffer as used.
 
 \paragraph{Device operation in multiqueue mode}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device operation in multiqueue mode}
 
-This specification defines following modes that a device MAY implement for operation with multiple transmit/receive virtqueues:
+This specification defines the following modes that a device MAY implement for operation with multiple transmit/receive virtqueues:
 \begin{itemize}
 \item Automatic receive steering as defined in \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode}.
- If a device supports such mode, it offers VIRTIO_NET_F_MQ feature bit.
+ If a device supports this mode, it offers the VIRTIO_NET_F_MQ feature bit.
 \item Receive-side scaling as defined in \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS processing}.
- If a device supports such mode, it offers VIRTIO_NET_F_RSS feature bit.
+ If a device supports this mode, it offers the VIRTIO_NET_F_RSS feature bit.
 \end{itemize}
 
 A device MAY support one of these features or both. The driver MAY negotiate any set of these features that the device supports.
@@ -3857,7 +3857,7 @@ The driver enables multiqueue by sending a command using \field{class} VIRTIO_NE
  #define VIRTIO_NET_CTRL_MQ_RSS_CONFIG          1 (for configurable receive steering)
 \end{lstlisting}
 
-If more than one multiqueue mode negotiated, the resulting device configuration is defined by the last command sent by the driver.
+If more than one multiqueue mode is negotiated, the resulting device configuration is defined by the last command sent by the driver.
 
 \paragraph{Automatic receive steering in multiqueue mode}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode}
 
@@ -3908,7 +3908,7 @@ The driver MUST NOT queue packets on transmit queues greater than
 
 \devicenormative{\subparagraph}{Automatic receive steering in multiqueue mode}{Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode}
 
-The device after initialization of reset MUST queue packets only on receiveq1.
+After initialization of reset, the device MUST queue packets only on receiveq1.
 
 The device MUST NOT queue packets on receive queues greater than
 \field{virtqueue_pairs} once it has placed the
@@ -3921,13 +3921,13 @@ according to the native endian of the guest rather than
 (necessarily when not using the legacy interface) little-endian.
 
 \paragraph{Receive-side scaling (RSS)}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS)}
-A device offers feature VIRTIO_NET_F_RSS if it supports RSS receive steering with Toeplitz hash calculation and configurable parameters.
+A device offers the feature VIRTIO_NET_F_RSS if it supports RSS receive steering with Toeplitz hash calculation and configurable parameters.
 
 A driver queries RSS capabilities of the device by reading device configuration as defined in \ref{sec:Device Types / Network Device / Device configuration layout / RSS}
 
 \subparagraph{Setting RSS parameters}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / Setting RSS parameters}
 
-Driver sends VIRTIO_NET_CTRL_MQ_RSS_CONFIG command using following format for \field{command-specific-data}:
+Driver sends a VIRTIO_NET_CTRL_MQ_RSS_CONFIG command using the following format for \field{command-specific-data}:
 \begin{lstlisting}
 struct virtio_net_rss_config {
     le32 hash_types;
@@ -3942,34 +3942,41 @@ struct virtio_net_rss_config {
 Field \field{hash_types} contains a bitmask of allowed hash types as
 defined in \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types}.
 
-Field \field{indirection_table_mask} is a mask to be applied to calculated hash to produce index in \field{indirection_table array}.
+Field \field{indirection_table_mask} is a mask to be applied to
+the calculated hash to produce an index in the
+\field{indirection_table} array.
 Number of entries in \field{indirection_table} is (\field{indirection_table_mask} + 1).
 
-Field \field{unclassified_queue} contains 0-based index of receive virtqueue to place unclassified packets in. Index 0 corresponds to receiveq1.
+Field \field{unclassified_queue} contains the 0-based index of
+the receive virtqueue to place unclassified packets in. Index 0 corresponds to receiveq1.
 
-Field \field{indirection_table} contains array of 0-based indices of receive virtqueus. Index 0 corresponds to receiveq1.
+Field \field{indirection_table} contains an array of 0-based indices of receive virtqueus. Index 0 corresponds to receiveq1.
 
 A driver sets \field{max_tx_vq} to inform a device how many transmit virtqueues it may use (transmitq1\ldots transmitq \field{max_tx_vq}).
 
 \subparagraph{RSS hash types}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types}
 
-The device calculates hash on IPv4 packets according to the field \field{hash_types} of virtio_net_rss_config structure as follows:
+The device calculates the hash on IPv4 packets according to the
+field \field{hash_types} of the virtio_net_rss_config structure as follows:
 \begin{itemize}
-\item If VIRTIO_NET_RSS_HASH_TYPE_TCPv4 is set and the packet has TCP header, the hash is calculated over following fields:
+\item If VIRTIO_NET_RSS_HASH_TYPE_TCPv4 is set and the packet has
+a TCP header, the hash is calculated over the following fields:
 \begin{itemize}
 \item Source IP address
 \item Destination IP address
 \item Source TCP port
 \item Destination TCP port
 \end{itemize}
-\item Else if VIRTIO_NET_RSS_HASH_TYPE_UDPv4 is set and the packet has UDP header, the hash is calculated over following fields:
+\item Else if VIRTIO_NET_RSS_HASH_TYPE_UDPv4 is set and the
+packet has a UDP header, the hash is calculated over the following fields:
 \begin{itemize}
 \item Source IP address
 \item Destination IP address
 \item Source UDP port
 \item Destination UDP port
 \end{itemize}
-\item Else if VIRTIO_NET_RSS_HASH_TYPE_IPv4 is set, the hash is calculated over following fields:
+\item Else if VIRTIO_NET_RSS_HASH_TYPE_IPv4 is set, the hash is
+calculated over the following fields:
 \begin{itemize}
 \item Source IP address
 \item Destination IP address
@@ -3977,23 +3984,28 @@ The device calculates hash on IPv4 packets according to the field \field{hash_ty
 \item Else the device does not calculate the hash
 \end{itemize}
 
-The device calculates hash on IPv6 packets without extension headers according to the field \field{hash_types} of virtio_net_rss_config structure as follows:
+\label{itm:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types/hash on IPv6 packets without extension headers}
+The device calculates the hash on IPv6 packets without extension
+headers according to the field \field{hash_types} of the virtio_net_rss_config structure as follows:
 \begin{itemize}
-\item If VIRTIO_NET_RSS_HASH_TYPE_TCPv6 is set and the packet has TCPv6 header, the hash is calculated over following fields:
+\item If VIRTIO_NET_RSS_HASH_TYPE_TCPv6 is set and the packet has
+a TCPv6 header, the hash is calculated over the following fields:
 \begin{itemize}
 \item Source IPv6 address
 \item Destination IPv6 address
 \item Source TCP port
 \item Destination TCP port
 \end{itemize}
-\item Else if VIRTIO_NET_RSS_HASH_TYPE_UDPv6 is set and the packet has UDPv6 header, the hash is calculated over following fields:
+\item Else if VIRTIO_NET_RSS_HASH_TYPE_UDPv6 is set and the
+packet has a UDPv6 header, the hash is calculated over the following fields:
 \begin{itemize}
 \item Source IPv6 address
 \item Destination IPv6 address
 \item Source UDP port
 \item Destination UDP port
 \end{itemize}
-\item Else if VIRTIO_NET_RSS_HASH_TYPE_IPv6 is set, the hash is calculated over following fields:
+\item Else if VIRTIO_NET_RSS_HASH_TYPE_IPv6 is set, the hash is
+calculated over the following fields:
 \begin{itemize}
 \item Source IPv6 address
 \item Destination IPv6 address
@@ -4001,47 +4013,52 @@ The device calculates hash on IPv6 packets without extension headers according t
 \item Else the device does not calculate the hash
 \end{itemize}
 
-The device calculates hash on IPv6 packets with extension headers according to the field \field{hash_types} of virtio_net_rss_config structure as follows:
+The device calculates the hash on IPv6 packets with extension
+headers according to the field \field{hash_types} of the virtio_net_rss_config structure as follows:
 \begin{itemize}
-\item If VIRTIO_NET_RSS_HASH_TYPE_TCP_EX is set and the packet has TCPv6 header, the hash is calculated over following fields:
+\item If VIRTIO_NET_RSS_HASH_TYPE_TCP_EX is set and the packet
+has a TCPv6 header, the hash is calculated over the following fields:
 \begin{itemize}
 \item Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 address.
 \item IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 address.
 \item Source TCP port
 \item Destination TCP port
 \end{itemize}
-\item Else if VIRTIO_NET_RSS_HASH_TYPE_UDP_EX is set and the packet has UDPv6 header, the hash is calculated over following fields:
+\item Else if VIRTIO_NET_RSS_HASH_TYPE_UDP_EX is set and the
+packet has a UDPv6 header, the hash is calculated over the following fields:
 \begin{itemize}
 \item Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 address.
 \item IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 address.
 \item Source UDP port
 \item Destination UDP port
 \end{itemize}
-\item Else if VIRTIO_NET_RSS_HASH_TYPE_IP_EX is set, the hash is calculated over following fields:
+\item Else if VIRTIO_NET_RSS_HASH_TYPE_IP_EX is set, the hash is
+calculated over the following fields:
 \begin{itemize}
 \item Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 address.
 \item IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 address.
 \end{itemize}
-\item Else skip IPv6 extension headers and calculate the hash as defined above for IPv6 packet without extension headers
+\item Else skip IPv6 extension headers and calculate the hash as
+defined for an IPv6 packet without extension headers (see \ref{itm:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types/hash on IPv6 packets without extension headers}).
 \end{itemize}
 
 \drivernormative{\subparagraph}{Setting RSS parameters}{Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) }
 
-A driver MUST NOT send VIRTIO_NET_CTRL_MQ_RSS_CONFIG command if the feature VIRTIO_NET_F_RSS has not been negotiated.
+A driver MUST NOT send the VIRTIO_NET_CTRL_MQ_RSS_CONFIG command if the feature VIRTIO_NET_F_RSS has not been negotiated.
 
-A driver MUST fill \field{indirection_table} array only with indices of enabled queues. Index 0 corresponds to receiveq1.
+A driver MUST fill the \field{indirection_table} array only with indices of enabled queues. Index 0 corresponds to receiveq1.
 
-Number of entries in \field{indirection_table} (\field{indirection_table_mask} + 1) MUST be a power of two.
+The number of entries in \field{indirection_table} (\field{indirection_table_mask} + 1) MUST be a power of two.
 
 A driver MUST use \field{indirection_table_mask} values that are less than \field{rss_max_indirection_table_length} reported by a device.
 
 A driver MUST NOT set any VIRTIO_NET_RSS_HASH_TYPE_ flags that are not supported by a device.
 
 \devicenormative{\subparagraph}{RSS processing}{Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS processing}
-The device MUST determine destination queue for network packet as follows:
+The device MUST determine the destination queue for a network packet as follows:
 \begin{itemize}
-\item Calculate hash of the packet as defined in \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types}
-\item If the device did not calculate the hash for specific packet, the device directs the packet to the receiveq specified by \field{unclassified_queue} of virtio_net_rss_config structure (value of 0 corresponds to receiveq1).
+\item Calculate the hash of the packet as defined in \ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS hash types}
+\item If the device did not calculate the hash for the specific packet, the device directs the packet to the receiveq specified by \field{unclassified_queue} of virtio_net_rss_config structure (value of 0 corresponds to receiveq1).
 \item Apply \field{indirection_table_mask} to the calculated hash and use the result as the index in the indirection table to get 0-based number of destination receiveq (value of 0 corresponds to receiveq1).
 \end{itemize}