[dpdk-dev] doc: virtio pmd versions
Commit Message
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>
---
doc/guides/nics/virtio.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 57 insertions(+)
Comments
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Zhihong Wang
> Sent: Thursday, April 21, 2016 4:55 AM
> To: dev@dpdk.org
> Cc: Wang, Zhihong <zhihong.wang@intel.com>
> Subject: [dpdk-dev] [PATCH] 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.
Hi,
Thanks for the clarification docs. That should hopefully answer a frequently
asked question.
Some minor comments below.
> +
> +Virtio PMD Versions
> +-------------------
> +
> +Virtio driver has 3 versions of rx functions and 2 versions of tx
> functions.
In some places RX/TX is used and in some rx/tx. I would suggest the
uppercase versions throughout.
> +
> +RX functions:
> +
> +* ``virtio_recv_pkts``:
> +
> + Regular version without mergeable rx buffers support
Since these could be a numbered list I would suggest using "#." (numbered
list) instead of "*" (bullet list). Also it would be better without a blank
line between the name and the definition so that they appear on the same
line in the generated docs.
> +
> + Simple version without mergeable rx buffers support, also fixes the
> + avail ring and uses vector instructions to optimize performance
s/avail/available in 2 places.
Also should that be "available ring size" or "number of available rings"
or something else?
> +Example to use the simple version of virtio poll mode driver in testpmd:
> +
> +.. code-block:: console
> +
> +./x86_64-native-linuxapp-gcc/app/testpmd -c 0x7 -n 4
> + -- -i --txqflags=0xf01 --rxq=1 --txq=1 --nb-cores=1
The code/commandline needs to be indented 3-4 spaces to be rendered
correctly. I'd also suggest omitting "./x86_64-native-linuxapp-gcc/app/" and
just using "testpmd" since that commandline is target dependent. The command
would also fit on one line like that.
Thanks,
John.
--
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Mcnamara, John
<snip>
>
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Zhihong Wang
<snip>
> > +
> > +Virtio PMD Versions
> > +-------------------
> > +
> > +Virtio driver has 3 versions of rx functions and 2 versions of tx
> > functions.
>
> In some places RX/TX is used and in some rx/tx. I would suggest the
> uppercase versions throughout.
>
In the commit logs, the only valid contractions allowed by the check-git-log.sh script are Rx and Tx
bad=$(echo "$headlines" | grep -E --color=always \
-e '\<(rx|tx|RX|TX)\>' \
....
I would therefore suggest we follow the same rules for the docs for consistency.
/Bruce
> -----Original Message-----
> From: Richardson, Bruce
> Sent: Thursday, June 9, 2016 1:53 PM
> To: Mcnamara, John <john.mcnamara@intel.com>; Wang, Zhihong
> <zhihong.wang@intel.com>; dev@dpdk.org
> Cc: Wang, Zhihong <zhihong.wang@intel.com>
> Subject: RE: [dpdk-dev] [PATCH] doc: virtio pmd versions
>
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Mcnamara, John
> <snip>
> >
> > > -----Original Message-----
> > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Zhihong Wang
> <snip>
> > > +
> > > +Virtio PMD Versions
> > > +-------------------
> > > +
> > > +Virtio driver has 3 versions of rx functions and 2 versions of tx
> > > functions.
> >
> > In some places RX/TX is used and in some rx/tx. I would suggest the
> > uppercase versions throughout.
> >
>
> In the commit logs, the only valid contractions allowed by the check-git-
> log.sh script are Rx and Tx
>
> bad=$(echo "$headlines" | grep -E --color=always \
> -e '\<(rx|tx|RX|TX)\>' \
> ....
>
> I would therefore suggest we follow the same rules for the docs for
> consistency.
Hi,
I don't mind what it is once we have consistency, so Rx/Tx is fine. Zhihong,
please note.
John
> -----Original Message-----
> From: Mcnamara, John
> Sent: Thursday, June 9, 2016 8:56 PM
> To: Richardson, Bruce <bruce.richardson@intel.com>; Wang, Zhihong
> <zhihong.wang@intel.com>; dev@dpdk.org
> Cc: Wang, Zhihong <zhihong.wang@intel.com>
> Subject: RE: [dpdk-dev] [PATCH] doc: virtio pmd versions
>
> > -----Original Message-----
> > From: Richardson, Bruce
> > Sent: Thursday, June 9, 2016 1:53 PM
> > To: Mcnamara, John <john.mcnamara@intel.com>; Wang, Zhihong
> > <zhihong.wang@intel.com>; dev@dpdk.org
> > Cc: Wang, Zhihong <zhihong.wang@intel.com>
> > Subject: RE: [dpdk-dev] [PATCH] doc: virtio pmd versions
> >
> > > -----Original Message-----
> > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Mcnamara, John
> > <snip>
> > >
> > > > -----Original Message-----
> > > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Zhihong Wang
> > <snip>
> > > > +
> > > > +Virtio PMD Versions
> > > > +-------------------
> > > > +
> > > > +Virtio driver has 3 versions of rx functions and 2 versions of tx
> > > > functions.
> > >
> > > In some places RX/TX is used and in some rx/tx. I would suggest the
> > > uppercase versions throughout.
> > >
> >
> > In the commit logs, the only valid contractions allowed by the check-git-
> > log.sh script are Rx and Tx
> >
> > bad=$(echo "$headlines" | grep -E --color=always \
> > -e '\<(rx|tx|RX|TX)\>' \
> > ....
> >
> > I would therefore suggest we follow the same rules for the docs for
> > consistency.
>
> Hi,
>
> I don't mind what it is once we have consistency, so Rx/Tx is fine. Zhihong,
> please note.
Thank you John and Bruce!
V2 has been sent, please take a look.
>
> John
>
>
@@ -211,3 +211,60 @@ In this example, the packet reception flow path is:
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
+
+Virtio PMD Versions
+-------------------
+
+Virtio driver has 3 versions of rx functions and 2 versions of tx functions.
+
+RX functions:
+
+* ``virtio_recv_pkts``:
+
+ Regular version without mergeable rx buffers support
+
+* ``virtio_recv_mergeable_pkts``:
+
+ Regular version with mergeable rx buffers support
+
+* ``virtio_recv_pkts_vec``:
+
+ Simple version without mergeable rx buffers support, also fixes the avail ring and uses vector instructions to optimize performance
+
+TX functions:
+
+* ``virtio_xmit_pkts``:
+
+ Regular version
+
+* ``virtio_xmit_pkts_simple``:
+
+ Simple version fixes the avail ring 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 virtio poll mode driver:
+
+* For rx: ``virtio_recv_pkts_vec``
+
+* For tx: ``virtio_xmit_pkts_simple``
+
+The simple version will only be enabled when:
+
+* Mergeable rx buffers is disabled
+
+* Single segment is specified
+
+* No offload support is needed
+
+Example to use the simple version of virtio poll mode driver in testpmd:
+
+.. code-block:: console
+
+./x86_64-native-linuxapp-gcc/app/testpmd -c 0x7 -n 4
+ -- -i --txqflags=0xf01 --rxq=1 --txq=1 --nb-cores=1
+