Re: [virtio-dev] [PATCH] virtio-spec: fix the incorrect syntax

[Cornelia Huck <cornelia.huck@de.ibm.com>]

On Wed, 18 Dec 2013 10:24:11 +0800
Zhi Yong Wu <zwu.kernel@gmail.com> wrote:

> From: Zhi Yong Wu <wuzhy@linux.vnet.ibm.com>
> 
> Signed-off-by: Zhi Yong Wu <wuzhy@linux.vnet.ibm.com>
> ---
>  virtio-spec.lyx |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/virtio-spec.lyx b/virtio-spec.lyx
> index ebde0f5..a99e7e5 100644
> --- a/virtio-spec.lyx
> +++ b/virtio-spec.lyx
> @@ -5763,7 +5763,7 @@ Automatic receive steering in multiqueue mode
>  \change_inserted 1986246365 1354528882
>  If the driver negotiates the VIRTIO_NET_F_MQ feature bit (depends on VIRTIO_NET_
>  F_CTRL_VQ), it can transmit outgoing packets on one of the multiple transmitq0..tr
> -ansmitqN and ask the device to queue incoming packets into one the multiple
> +ansmitqN and ask the device to queue incoming packets into one of the multiple
>   receiveq0..receiveqN depending on the packet flow.
>  \change_unchanged
> 

Looks sane.

This has caused me to look at the wording for the multiqueue feature in
general, and I think the language should be tightened a bit. Here's
what I currently have; feedback from someone actually familiar with
multiqueue is welcome.

commit 982458d5287bb3483fdaaa211aae77b919e58187
Author: Cornelia Huck <cornelia.huck@de.ibm.com>
Date:   Wed Dec 18 16:46:17 2013 +0100

    net/multiqueue: tighten wording
    
    Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com>

diff --git a/content.tex b/content.tex
index 797ee3e..54195bf 100644
--- a/content.tex
+++ b/content.tex
@@ -2844,9 +2844,9 @@ Processing this notification involves:
 \paragraph{Automatic receive steering in multiqueue mode}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode}
 
 If the driver negotiates the VIRTIO_NET_F_MQ feature bit (depends
-on VIRTIO_NET_F_CTRL_VQ), it can transmit outgoing packets on one
+on VIRTIO_NET_F_CTRL_VQ), it MAY transmit outgoing packets on one
 of the multiple transmitq0..transmitqN and ask the device to
-queue incoming packets into one the multiple receiveq0..receiveqN
+queue incoming packets into one of the multiple receiveq0..receiveqN
 depending on the packet flow.
 
 \begin{lstlisting}
@@ -2860,28 +2860,28 @@ depending on the packet flow.
 	 #define VIRTIO_NET_CTRL_MQ_VQ_PAIRS_MAX        0x8000
 \end{lstlisting}
 
-Multiqueue is disabled by default. Driver enables multiqueue by
+Multiqueue is disabled by default. The driver enables multiqueue by
 executing the VIRTIO_NET_CTRL_MQ_VQ_PAIRS_SET command, specifying
-the number of the transmit and receive queues that will be used;
-thus transmitq0..transmitqn and receiveq0..receiveqn where
-n=virtqueue_pairs-1 will be used. All these virtqueues must have
+the number of the transmit and receive queues to be used; subsequently,
+transmitq0..transmitqn and receiveq0..receiveqn where
+n=virtqueue_pairs-1 MAY be used. All these virtqueues MUST have
 been pre-configured in advance. The range of legal values for the
 virtqueue_pairs field is between 1 and max_virtqueue_pairs.
 
-When multiqueue is enabled, device uses automatic receive steering
-based on packet flow.Programming of the receive steering
-classificator is implicit. Transmitting a packet of a specific
-flow on transmitqX will cause incoming packets for this flow to
+When multiqueue is enabled, the device MUST use automatic receive steering
+based on packet flow. Programming of the receive steering
+classificator is implicit. After the driver transmitted a packet of a specific
+flow on transmitqX, the device MUST cause incoming packets for this flow to
 be steered to receiveqX. For uni-directional protocols, or where
-no packets have been transmitted yet, device will steer a packet
+no packets have been transmitted yet, the device MAY steer a packet
 to a random queue out of the specified receiveq0..receiveqn.
 
 Multiqueue is disabled by setting virtqueue_pairs = 1 (this is
-the default). After the command is consumed by the device, the
-device will not steer new packets on virtqueues
-receveq1..receiveqN (i.e. other than receiveq0) nor read from
+the default). After the command has been consumed by the device, the
+device MUST NOT steer new packets to virtqueues
+receveq1..receiveqN (i.e. other than receiveq0) and MUST NOT read from
 transmitq1..transmitqN (i.e. other than transmitq0); accordingly,
-driver should not transmit new packets on virtqueues other than
+the driver MUST NOT transmit new packets on virtqueues other than
 transmitq0.
 
 \paragraph{Offloads State Configuration}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Offloads State Configuration}