-.. 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
========================================
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.
Virtio Implementation in DPDK
-----------------------------
-For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
+For details about the virtio spec, refer to the latest
+`VIRTIO (Virtual I/O) Device Specification
+<https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio>`_.
-As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
+As a PMD, virtio provides packet reception and transmission callbacks.
-In virtio_recv_pkts, index in range [vq->vq_used_cons_idx , vq->vq_ring.used->idx) in vring is available for virtio to burst out.
+In Rx, packets described by the used descriptors in vring are available
+for virtio to burst out.
-In virtio_xmit_pkts, same index range in vring is available for virtio to clean.
-Virtio will enqueue to be transmitted packets into vring, advance the vq->vq_ring.avail->idx,
-and then notify the host back end if necessary.
+In Tx, packets described by the used descriptors in vring are available
+for virtio to clean. Virtio will enqueue to be transmitted packets into
+vring, make them available to the device, and then notify the host back
+end if necessary.
Features and Limitations of virtio PMD
--------------------------------------
* 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
+ Rx queue size can be configurable 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 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.
+ command line. Note that, mac/vlan filter is best effort: unwanted packets could still arrive.
* "RTE_PKTMBUF_HEADROOM" should be defined
no less than "sizeof(struct virtio_net_hdr_mrg_rxbuf)", which is 12 bytes when mergeable or
Virtio PMD Rx/Tx Callbacks
--------------------------
-Virtio driver has 3 Rx callbacks and 2 Tx callbacks.
+Virtio driver has 6 Rx callbacks and 3 Tx callbacks.
Rx callbacks:
#. ``virtio_recv_pkts``:
- Regular version without mergeable Rx buffer support.
+ Regular version without mergeable Rx buffer support for split virtqueue.
#. ``virtio_recv_mergeable_pkts``:
- Regular version with mergeable Rx buffer support.
+ Regular version with mergeable Rx buffer support for split virtqueue.
#. ``virtio_recv_pkts_vec``:
Vector version without mergeable Rx buffer support, also fixes the available
- ring indexes and uses vector instructions to optimize performance.
+ ring indexes and uses vector instructions to optimize performance for split
+ virtqueue.
+
+#. ``virtio_recv_pkts_inorder``:
+ In-order version with mergeable and non-mergeable Rx buffer support
+ for split virtqueue.
+
+#. ``virtio_recv_pkts_packed``:
+ Regular and in-order version without mergeable Rx buffer support for
+ packed virtqueue.
+
+#. ``virtio_recv_mergeable_pkts_packed``:
+ Regular and in-order version with mergeable Rx buffer support for packed
+ virtqueue.
Tx callbacks:
#. ``virtio_xmit_pkts``:
- Regular version.
+ Regular version for split virtqueue.
-#. ``virtio_xmit_pkts_simple``:
- Vector version fixes the available ring indexes to optimize performance.
+#. ``virtio_xmit_pkts_inorder``:
+ In-order version for split virtqueue.
+#. ``virtio_xmit_pkts_packed``:
+ Regular and in-order version for packed virtqueue.
By default, the non-vector callbacks are used:
-* For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is
- used; otherwise ``virtio_recv_mergeable_pkts``.
+* For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts``
+ or ``virtio_recv_pkts_packed`` will be used, otherwise
+ ``virtio_recv_mergeable_pkts`` or ``virtio_recv_mergeable_pkts_packed``
+ will be used.
-* For Tx: ``virtio_xmit_pkts``.
+* For Tx: ``virtio_xmit_pkts`` or ``virtio_xmit_pkts_packed`` will be used.
Vector callbacks will be used when:
-* ``txq_flags`` is set to ``VIRTIO_SIMPLE_FLAGS`` (0xF01), which implies:
-
- * Single segment is specified.
-
- * No offload support is needed.
-
* Mergeable Rx buffers is disabled.
The corresponding callbacks are:
* For Rx: ``virtio_recv_pkts_vec``.
-* For Tx: ``virtio_xmit_pkts_simple``.
+There is no vector callbacks for packed virtqueue for now.
Example of using the vector version of the virtio poll mode driver in
``testpmd``::
- testpmd -l 0-2 -n 4 -- -i --txqflags=0xF01 --rxq=1 --txq=1 --nb-cores=1
+ testpmd -l 0-2 -n 4 -- -i --rxq=1 --txq=1 --nb-cores=1
+
+In-order callbacks only work on simulated virtio user vdev.
+
+For split virtqueue:
+
+* For Rx: If in-order is enabled then ``virtio_recv_pkts_inorder`` is used.
+* For Tx: If in-order is enabled then ``virtio_xmit_pkts_inorder`` is used.
+
+For packed virtqueue, the default callbacks already support the
+in-order feature.
Interrupt mode
--------------
$ l3fwd-power -l 0-1 -- -p 1 -P --config="(0,0,1)" \
--no-numa --parse-ptype
+
+
+Virtio PMD arguments
+--------------------
+
+Below devargs are supported by the PCI virtio driver:
+
+#. ``vdpa``:
+
+ A virtio device could also be driven by vDPA (vhost data path acceleration)
+ driver, and works as a HW vhost backend. This argument is used to specify
+ a virtio device needs to work in vDPA mode.
+ (Default: 0 (disabled))
+
+Below devargs are supported by the virtio-user vdev:
+
+#. ``path``:
+
+ It is used to specify a path to connect to vhost backend.
+
+#. ``mac``:
+
+ It is used to specify the MAC address.
+
+#. ``cq``:
+
+ It is used to enable the control queue. (Default: 0 (disabled))
+
+#. ``queue_size``:
+
+ It is used to specify the queue size. (Default: 256)
+
+#. ``queues``:
+
+ It is used to specify the queue number. (Default: 1)
+
+#. ``iface``:
+
+ It is used to specify the host interface name for vhost-kernel
+ backend.
+
+#. ``server``:
+
+ It is used to enable the server mode when using vhost-user backend.
+ (Default: 0 (disabled))
+
+#. ``mrg_rxbuf``:
+
+ It is used to enable virtio device mergeable Rx buffer feature.
+ (Default: 1 (enabled))
+
+#. ``in_order``:
+
+ It is used to enable virtio device in-order feature.
+ (Default: 1 (enabled))
+
+#. ``packed_vq``:
+
+ It is used to enable virtio device packed virtqueue feature.
+ (Default: 0 (disabled))
git.droids-corp.org / dpdk.git / blobdiff