New upstream version 18.02

[deb_dpdk.git] / doc / guides / nics / virtio.rst

diff --git a/doc/guides/nics/virtio.rst b/doc/guides/nics/virtio.rst
index 91bedea..ca09cd2 100644 (file)
--- a/doc/guides/nics/virtio.rst
+++ b/doc/guides/nics/virtio.rst
@@ -1,32 +1,5 @@
-..  BSD LICENSE
-    Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-    * Neither the name of Intel Corporation nor the names of its
-    contributors may be used to endorse or promote products derived
-    from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2015 Intel Corporation.
 
 Poll Mode Driver for Emulated Virtio NIC
 ========================================
@@ -34,6 +7,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 +15,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 +44,21 @@ 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.
+    When backend can't support vlan filter, virtio app on guest should not enable vlan filter in order
+    to make sure the virtio port is configured correctly. E.g. do not specify '--enable-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.
 
@@ -288,6 +265,13 @@ interrupt, Rx interrupts, and Tx interrupts. Config interrupt is used for
 notification of device configuration changes, especially link status (lsc).
 Interrupt mode is translated into Rx interrupts in the context of DPDK.
 
+.. Note::
+
+   Virtio PMD already has support for receiving lsc from qemu when the link
+   status changes, especially when vhost user disconnects. However, it fails
+   to do that if the VM is created by qemu 2.6.2 or below, since the
+   capability to detect vhost user disconnection is introduced in qemu 2.7.0.
+
 Prerequisites for Rx interrupts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~