[PATCH] doc: update virtio doc

[PATCH] doc: update virtio doc

[Zhiyong Yang]

Add more explanations about vring size changes and virtio_header
size.

Signed-off-by: Zhiyong Yang <zhiyong.yang@intel.com>
---
 doc/guides/nics/virtio.rst | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
index 91bedea..36ddd08 100644
--- a/doc/guides/nics/virtio.rst
+++ b/doc/guides/nics/virtio.rst
@@ -41,8 +41,8 @@ The DPDK extends kni to support vhost raw socket interface,
 which enables vhost to directly read/ write packets from/to a physical port.
 With this enhancement, virtio could achieve quite promising performance.
 
-In future release, we will also make enhancement to vhost backend,
-releasing peak performance of virtio PMD driver.
+In future release, we will also make enhancement to vhost backend.
+Peak performance of virtio PMD driver will be released with every release version since DPDK 17.02 release.
 
 For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM,
 please refer to Chapter "Driver for VM Emulated Devices".
@@ -73,15 +73,20 @@ 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 2.7 and below.
     If given a different descriptor number by the upper application,
     the virtio PMD generates a warning and fall back to the hard-coded value.
+    Rx queue size can be configureable and up to 1024 since qemu 2.8 and above. Rx queue size is 256
+    by default. Tx queue size is still hard-coded to be 256.
 
 *   Features of mac/vlan filter are supported, negotiation with vhost/backend are needed to support them.
     When backend can't support vlan filter, virtio app on guest should disable vlan filter to make sure
     the virtio port is configured correctly. E.g. specify '--disable-hw-vlan' in testpmd command line.
 
-*   RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct virtio_net_hdr), which is 10 bytes.
+*   RTE_PKTMBUF_HEADROOM should be defined
+    larger than sizeof(struct virtio_net_hdr), which is 10 bytes, when using non-mergeable.
+    larger than sizeof(struct virtio_net_hdr_mrg_rxbuf), which is 12 bytes when mergeable or F_VERSION_1
+    is set.
 
 *   Virtio does not support runtime configuration.
 
-- 
2.7.4

Re: [PATCH] doc: update virtio doc

[Mcnamara, John]

> -----Original Message-----
> From: Yang, Zhiyong
> Sent: Wednesday, May 10, 2017 7:18 AM
> To: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>
> Cc: yuanhan.liu@linux.intel.com; maxime.coquelin@redhat.com; Yang, Zhiyong
> <zhiyong.yang@intel.com>
> Subject: [PATCH] doc: update virtio doc
> 
> Add more explanations about vring size changes and virtio_header size.
> 
> Signed-off-by: Zhiyong Yang <zhiyong.yang@intel.com>
> ---
>  doc/guides/nics/virtio.rst | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst index
> 91bedea..36ddd08 100644
> --- a/doc/guides/nics/virtio.rst
> +++ b/doc/guides/nics/virtio.rst
> @@ -41,8 +41,8 @@ The DPDK extends kni to support vhost raw socket
> interface,  which enables vhost to directly read/ write packets from/to a
> physical port.
>  With this enhancement, virtio could achieve quite promising performance.
> 
> -In future release, we will also make enhancement to vhost backend, -
> releasing peak performance of virtio PMD driver.
> +In future release, we will also make enhancement to vhost backend.
> +Peak performance of virtio PMD driver will be released with every release
> version since DPDK 17.02 release.

Hi,

There have been great performance improvements in Virtio in the last few
releases. However, we can't really promise that is will improve in every
release. I'd suggest removing these two lines and the previous line
starting with "With this enhancement, virtio could ...".


> 
>  ...
> 
> -*   RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct
> virtio_net_hdr), which is 10 bytes.
> +*   RTE_PKTMBUF_HEADROOM should be defined
> +    larger than sizeof(struct virtio_net_hdr), which is 10 bytes, when
> using non-mergeable.
> +    larger than sizeof(struct virtio_net_hdr_mrg_rxbuf), which is 12
> bytes when mergeable or F_VERSION_1
> +    is set.
> 

All constants and struct names should be ```` quoted. Like this:


*   ``RTE_PKTMBUF_HEADROOM`` should be defined  larger than
    ``sizeof(struct virtio_net_hdr)``, which is 10 bytes, when using
    non-mergeable or larger than ``sizeof(struct virtio_net_hdr_mrg_rxbuf)``,
    which is 12 bytes when mergeable or ``F_VERSION_1`` is set.

John

Re: [PATCH] doc: update virtio doc

[Yang, Zhiyong]

Hi, John:

> -----Original Message-----
> From: Mcnamara, John
> Sent: Wednesday, May 10, 2017 5:58 PM
> To: Yang, Zhiyong <zhiyong.yang@intel.com>; dev@dpdk.org
> Cc: yuanhan.liu@linux.intel.com; maxime.coquelin@redhat.com
> Subject: RE: [PATCH] doc: update virtio doc
> 
> 
> 
> > -----Original Message-----
> > From: Yang, Zhiyong
> > Sent: Wednesday, May 10, 2017 7:18 AM
> > To: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>
> > Cc: yuanhan.liu@linux.intel.com; maxime.coquelin@redhat.com; Yang,
> > Zhiyong <zhiyong.yang@intel.com>
> > Subject: [PATCH] doc: update virtio doc
> >
> > Add more explanations about vring size changes and virtio_header size.
> >
> > Signed-off-by: Zhiyong Yang <zhiyong.yang@intel.com>
> > ---
> >  doc/guides/nics/virtio.rst | 13 +++++++++----
> >  1 file changed, 9 insertions(+), 4 deletions(-)
> >
> > diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
> > index
> > 91bedea..36ddd08 100644
> > --- a/doc/guides/nics/virtio.rst
> > +++ b/doc/guides/nics/virtio.rst
> > @@ -41,8 +41,8 @@ The DPDK extends kni to support vhost raw socket
> > interface,  which enables vhost to directly read/ write packets
> > from/to a physical port.
> >  With this enhancement, virtio could achieve quite promising performance.
> >
> > -In future release, we will also make enhancement to vhost backend, -
> > releasing peak performance of virtio PMD driver.
> > +In future release, we will also make enhancement to vhost backend.
> > +Peak performance of virtio PMD driver will be released with every
> > +release
> > version since DPDK 17.02 release.
> 
> Hi,
> 
> There have been great performance improvements in Virtio in the last few
> releases. However, we can't really promise that is will improve in every release.
> I'd suggest removing these two lines and the previous line starting with "With
> this enhancement, virtio could ...".
> 

Ok. 

> 
> >
> >  ...
> >
> > -*   RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct
> > virtio_net_hdr), which is 10 bytes.
> > +*   RTE_PKTMBUF_HEADROOM should be defined
> > +    larger than sizeof(struct virtio_net_hdr), which is 10 bytes,
> > +when
> > using non-mergeable.
> > +    larger than sizeof(struct virtio_net_hdr_mrg_rxbuf), which is 12
> > bytes when mergeable or F_VERSION_1
> > +    is set.
> >
> 
> All constants and struct names should be ```` quoted. Like this:
> 
> 
> *   ``RTE_PKTMBUF_HEADROOM`` should be defined  larger than
>     ``sizeof(struct virtio_net_hdr)``, which is 10 bytes, when using
>     non-mergeable or larger than ``sizeof(struct virtio_net_hdr_mrg_rxbuf)``,
>     which is 12 bytes when mergeable or ``F_VERSION_1`` is set.
> 

Good suggestion.

Zhiyong Yang

> John
> 

[PATCH v2] doc: update virtio vring size and virtio_header size

[Zhiyong Yang]

Add more explanations about vring size changes and different virtio_header
size.

Signed-off-by: Zhiyong Yang <zhiyong.yang@intel.com>
---

Changes in v2:
1. Remove two lines and add "" to constants and struct names.
2. Modify the title.
 
 doc/guides/nics/virtio.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
index 91bedea..4d6a837 100644
--- a/doc/guides/nics/virtio.rst
+++ b/doc/guides/nics/virtio.rst
@@ -34,6 +34,7 @@ Poll Mode Driver for Emulated Virtio NIC
 Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
 In the Data Plane Development Kit (DPDK),
 we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
+
 for fast guest VM to guest VM communication and guest VM to host communication.
 
 Vhost is a kernel acceleration module for virtio qemu backend.
@@ -41,9 +42,6 @@ The DPDK extends kni to support vhost raw socket interface,
 which enables vhost to directly read/ write packets from/to a physical port.
 With this enhancement, virtio could achieve quite promising performance.
 
-In future release, we will also make enhancement to vhost backend,
-releasing peak performance of virtio PMD driver.
-
 For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM,
 please refer to Chapter "Driver for VM Emulated Devices".
 
@@ -73,15 +71,20 @@ 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 2.7 and below.
     If given a different descriptor number by the upper application,
     the virtio PMD generates a warning and fall back to the hard-coded value.
+    Rx queue size can be configureable and up to 1024 since qemu 2.8 and above. Rx queue size is 256
+    by default. Tx queue size is still hard-coded to be 256.
 
 *   Features of mac/vlan filter are supported, negotiation with vhost/backend are needed to support them.
     When backend can't support vlan filter, virtio app on guest should disable vlan filter to make sure
     the virtio port is configured correctly. E.g. specify '--disable-hw-vlan' in testpmd command line.
 
-*   RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct virtio_net_hdr), which is 10 bytes.
+*   "RTE_PKTMBUF_HEADROOM" should be defined
+    no less than "sizeof(struct virtio_net_hdr_mrg_rxbuf)", which is 12 bytes when mergeable or
+    "VIRTIO_F_VERSION_1" is set.
+    no less than "sizeof(struct virtio_net_hdr)", which is 10 bytes, when using non-mergeable.
 
 *   Virtio does not support runtime configuration.
 
-- 
2.7.4

Re: [PATCH v2] doc: update virtio vring size and virtio_header size

[Mcnamara, John]

> -----Original Message-----
> From: Yang, Zhiyong
> Sent: Thursday, May 11, 2017 3:17 AM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnamara@intel.com>; yuanhan.liu@linux.intel.com;
> maxime.coquelin@redhat.com; Yang, Zhiyong <zhiyong.yang@intel.com>
> Subject: [PATCH v2] doc: update virtio vring size and virtio_header size
> 
> Add more explanations about vring size changes and different virtio_header
> size.
> 
> Signed-off-by: Zhiyong Yang <zhiyong.yang@intel.com>

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

Re: [PATCH v2] doc: update virtio vring size and virtio_header size

[Yuanhan Liu]

On Fri, Jun 30, 2017 at 02:43:47PM +0000, Mcnamara, John wrote:
> 
> 
> > -----Original Message-----
> > From: Yang, Zhiyong
> > Sent: Thursday, May 11, 2017 3:17 AM
> > To: dev@dpdk.org
> > Cc: Mcnamara, John <john.mcnamara@intel.com>; yuanhan.liu@linux.intel.com;
> > maxime.coquelin@redhat.com; Yang, Zhiyong <zhiyong.yang@intel.com>
> > Subject: [PATCH v2] doc: update virtio vring size and virtio_header size
> > 
> > Add more explanations about vring size changes and different virtio_header
> > size.
> > 
> > Signed-off-by: Zhiyong Yang <zhiyong.yang@intel.com>
> 
> Acked-by: John McNamara <john.mcnamara@intel.com>

Applied to dpdk-next-virtio.

Thanks.

	--yliu