[dpdk-dev,v2] doc: virtio pmd versions

  This patch explains all the versions of current virtio pmd implementation,
what's the difference, and how to choose the right version.

--------------
Changes in v2:

   1. Changes on format and few descriptions.


Signed-off-by: Zhihong Wang <zhihong.wang@intel.com>
---
 doc/guides/nics/virtio.rst | 64 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 58 insertions(+), 6 deletions(-)
  

> -----Original Message-----
> From: Wang, Zhihong
> Sent: Wednesday, June 15, 2016 12:53 AM
> To: dev@dpdk.org
> Cc: Richardson, Bruce <bruce.richardson@intel.com>; Mcnamara, John
> <john.mcnamara@intel.com>; Wang, Zhihong <zhihong.wang@intel.com>
> Subject: [PATCH v2] doc: virtio pmd versions
> 
> This patch explains all the versions of current virtio pmd implementation,
> what's the difference, and how to choose the right version.
> 
> Signed-off-by: Zhihong Wang <zhihong.wang@intel.com>


Acked-by: John McNamara <john.mcnamara@intel.com>
  

On Tue, Jun 14, 2016 at 07:53:17PM -0400, Zhihong Wang wrote:
> This patch explains all the versions of current virtio pmd implementation,
> what's the difference, and how to choose the right version.
> 
> --------------
> Changes in v2:
> 
>    1. Changes on format and few descriptions.

Change log should go ...
> 
> 
> Signed-off-by: Zhihong Wang <zhihong.wang@intel.com>
> ---

here..

>  doc/guides/nics/virtio.rst | 64 +++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 58 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
> index 06ca433..a4fef89 100644
> --- a/doc/guides/nics/virtio.rst
> +++ b/doc/guides/nics/virtio.rst
> @@ -73,7 +73,7 @@ In this release, the virtio PMD driver provides the basic functionality of packe
>  
>  *   It supports multicast packets and promiscuous mode.
>  
> -*   The descriptor number for the RX/TX queue is hard-coded to be 256 by qemu.
> +*   The descriptor number for the Rx/Tx queue is hard-coded to be 256 by qemu.
>      If given a different descriptor number by the upper application,
>      the virtio PMD generates a warning and fall back to the hard-coded value.
>  
> @@ -163,8 +163,8 @@ Host2VM communication example
>      which means received packets come from vEth0, and transmitted packets is sent to vEth0.
>  
>  #.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
> -    When the virtio port in guest bursts rx, it is getting packets from the raw socket's receive queue.
> -    When the virtio port bursts tx, it is sending packet to the tx_q.
> +    When the virtio port in guest bursts Rx, it is getting packets from the raw socket's receive queue.
> +    When the virtio port bursts Tx, it is sending packet to the tx_q.
>  
>      .. code-block:: console
>  
> @@ -183,7 +183,7 @@ Host2VM communication example
>  
>      The packet reception and transmission flow path is:
>  
> -    IXIA packet generator->82599 PF->KNI rx queue->KNI raw socket queue->Guest VM virtio port 0 rx burst->Guest VM virtio port 0 tx burst-> KNI tx queue->82599 PF-> IXIA packet generator
> +    IXIA packet generator->82599 PF->KNI Rx queue->KNI raw socket queue->Guest VM virtio port 0 Rx burst->Guest VM virtio port 0 Tx burst-> KNI Tx queue->82599 PF-> IXIA packet generator
>  
>  Virtio with qemu virtio Back End
>  --------------------------------
> @@ -206,8 +206,60 @@ Virtio with qemu virtio Back End
>  
>  In this example, the packet reception flow path is:
>  
> -    IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest VM virtio port 0 rx burst-> Guest VM 82599 VF port1 tx burst-> IXIA packet generator
> +    IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest VM virtio port 0 Rx burst-> Guest VM 82599 VF port1 Tx burst-> IXIA packet generator
>  
>  The packet transmission flow is:
>  
> -    IXIA packet generator-> Guest VM 82599 VF port1 rx burst-> Guest VM virtio port 0 tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
> +    IXIA packet generator-> Guest VM 82599 VF port1 Rx burst-> Guest VM virtio port 0 Tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
> +
> +
> +Virtio PMD Versions
> +-------------------

Using "versions" here is a bit confusing to me, especially virtio PMD
supports spec version 0.95 and 1.0. Apparently, that's not what you
are talking about, virtio pmd Rx/Tx callbacks is.

So, something like "Virtio PMD Rx/Tx callbacks" is what I would suggest.

> +
> +Virtio driver has 3 versions of Rx functions and 2 versions of Tx functions.

And I will avoid using "versions".

> +
> +Rx functions:
> +
> +#. ``virtio_recv_pkts``:
> +   Regular version without mergeable Rx buffer support.
> +
> +#. ``virtio_recv_mergeable_pkts``:
> +   Regular version with mergeable Rx buffer support.
> +
> +#. ``virtio_recv_pkts_vec``:
> +   Simple version without mergeable Rx buffer support, also fixes the available ring indexes and uses vector instructions to optimize performance.

Just like coding and writing commit log, don't write long lines over 80
chars here.

Also I will use "vector" instead of "simple" here, as "vector" is more
easier to understand.

> +
> +Tx functions:
> +
> +#. ``virtio_xmit_pkts``:
> +   Regular version.
> +
> +#. ``virtio_xmit_pkts_simple``:
> +   Simple version fixes the available ring indexes to optimize performance.
> +
> +
> +By default, the non-vector versions are used:
> +
> +*   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is used; otherwise ``virtio_recv_mergeable_pkts``.
> +
> +*   For Tx: ``virtio_xmit_pkts``.
> +
> +
> +Setting ``txq_flags`` to ``VIRTIO_SIMPLE_FLAGS`` (0xF01) enables the simple version of the virtio poll mode driver:
> +
> +*   For Rx: ``virtio_recv_pkts_vec``.
> +
> +*   For Tx: ``virtio_xmit_pkts_simple``.
> +

This paragraph says that vector Rx/Tx will be enabled when 0xf01 txq
flags is set.
> +
> +The simple version will only be enabled when:
> +
> +*   Mergeable Rx buffers is disabled.
> +
> +*   Single segment is specified.
> +
> +*   No offload support is needed.

However, you are making another statement that vector Rx/Tx will be used
when ....

That's confusing.

I'd combine the two together, to something like below:

    Vector Rx/Tx callbacks will be used when:
    
    * ``txq_flags`` is set to 0xf01, which implies
    
      * No multiple segments
      * No offload support
    
    * Mergeable Rx buffers is disabled.


	--yliu
> +
> +Example of using the simple version of the virtio poll mode driver in ``testpmd``::
> +
> +   testpmd -c 0x7 -n 4 -- -i --txqflags=0xF01 --rxq=1 --txq=1 --nb-cores=1
> -- 
> 2.5.0