2 Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
15 * Neither the name of Intel Corporation nor the names of its
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 Poll Mode Driver for Emulated Virtio NIC
32 ========================================
34 Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
35 In the Data Plane Development Kit (DPDK),
36 we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
37 for fast guest VM to guest VM communication and guest VM to host communication.
39 Vhost is a kernel acceleration module for virtio qemu backend.
40 The DPDK extends kni to support vhost raw socket interface,
41 which enables vhost to directly read/ write packets from/to a physical port.
42 With this enhancement, virtio could achieve quite promising performance.
44 In future release, we will also make enhancement to vhost backend,
45 releasing peak performance of virtio PMD driver.
47 For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM,
48 please refer to Chapter "Driver for VM Emulated Devices".
50 In this chapter, we will demonstrate usage of virtio PMD driver with two backends,
51 standard qemu vhost back end and vhost kni back end.
53 Virtio Implementation in DPDK
54 -----------------------------
56 For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
58 As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
60 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.
62 In virtio_xmit_pkts, same index range in vring is available for virtio to clean.
63 Virtio will enqueue to be transmitted packets into vring, advance the vq->vq_ring.avail->idx,
64 and then notify the host back end if necessary.
66 Features and Limitations of virtio PMD
67 --------------------------------------
69 In this release, the virtio PMD driver provides the basic functionality of packet reception and transmission.
71 * It supports merge-able buffers per packet when receiving packets and scattered buffer per packet
72 when transmitting packets. The packet size supported is from 64 to 1518.
74 * It supports multicast packets and promiscuous mode.
76 * The descriptor number for the Rx/Tx queue is hard-coded to be 256 by qemu.
77 If given a different descriptor number by the upper application,
78 the virtio PMD generates a warning and fall back to the hard-coded value.
80 * Features of mac/vlan filter are supported, negotiation with vhost/backend are needed to support them.
81 When backend can't support vlan filter, virtio app on guest should disable vlan filter to make sure
82 the virtio port is configured correctly. E.g. specify '--disable-hw-vlan' in testpmd command line.
84 * RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct virtio_net_hdr), which is 10 bytes.
86 * Virtio does not support runtime configuration.
88 * Virtio supports Link State interrupt.
90 * Virtio supports Rx interrupt (so far, only support 1:1 mapping for queue/interrupt).
92 * Virtio supports software vlan stripping and inserting.
94 * Virtio supports using port IO to get PCI resource when uio/igb_uio module is not available.
99 The following prerequisites apply:
101 * In the BIOS, turn VT-x and VT-d on
103 * Linux kernel with KVM module; vhost module loaded and ioeventfd supported.
104 Qemu standard backend without vhost support isn't tested, and probably isn't supported.
106 Virtio with kni vhost Back End
107 ------------------------------
109 This section demonstrates kni vhost back end example setup for Phy-VM Communication.
111 .. _figure_host_vm_comms:
113 .. figure:: img/host_vm_comms.*
115 Host2VM Communication Example Using kni vhost Back End
118 Host2VM communication example
120 #. Load the kni kernel module:
122 .. code-block:: console
126 Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
127 Please refer to the *DPDK Getting Started Guide* for detailed instructions.
129 #. Launch the kni user application:
131 .. code-block:: console
133 examples/kni/build/app/kni -l 0-3 -n 4 -- -p 0x1 -P --config="(0,1,3)"
135 This command generates one network device vEth0 for physical port.
136 If specify more physical ports, the generated network device will be vEth1, vEth2, and so on.
138 For each physical port, kni creates two user threads.
139 One thread loops to fetch packets from the physical NIC port into the kni receive queue.
140 The other user thread loops to send packets in the kni transmit queue.
142 For each physical port, kni also creates a kernel thread that retrieves packets from the kni receive queue,
143 place them onto kni's raw socket's queue and wake up the vhost kernel thread to exchange packets with the virtio virt queue.
145 For more details about kni, please refer to :ref:`kni`.
147 #. Enable the kni raw socket functionality for the specified physical NIC port,
148 get the generated file descriptor and set it in the qemu command line parameter.
149 Always remember to set ioeventfd_on and vhost_on.
153 .. code-block:: console
155 echo 1 > /sys/class/net/vEth0/sock_en
156 fd=`cat /sys/class/net/vEth0/sock_fd`
157 exec qemu-system-x86_64 -enable-kvm -cpu host \
158 -m 2048 -smp 4 -name dpdk-test1-vm1 \
159 -drive file=/data/DPDKVMS/dpdk-vm.img \
160 -netdev tap, fd=$fd,id=mynet_kni, script=no,vhost=on \
161 -device virtio-net-pci,netdev=mynet_kni,bus=pci.0,addr=0x3,ioeventfd=on \
164 In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
165 which means received packets come from vEth0, and transmitted packets is sent to vEth0.
167 #. In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
168 When the virtio port in guest bursts Rx, it is getting packets from the
169 raw socket's receive queue.
170 When the virtio port bursts Tx, it is sending packet to the tx_q.
172 .. code-block:: console
175 echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
176 modprobe uio_pci_generic
177 python usertools/dpdk-devbind.py -b uio_pci_generic 00:03.0
179 We use testpmd as the forwarding application in this example.
181 .. figure:: img/console.*
185 #. Use IXIA packet generator to inject a packet stream into the KNI physical port.
187 The packet reception and transmission flow path is:
189 IXIA packet generator->82599 PF->KNI Rx queue->KNI raw socket queue->Guest
190 VM virtio port 0 Rx burst->Guest VM virtio port 0 Tx burst-> KNI Tx queue
191 ->82599 PF-> IXIA packet generator
193 Virtio with qemu virtio Back End
194 --------------------------------
196 .. _figure_host_vm_comms_qemu:
198 .. figure:: img/host_vm_comms_qemu.*
200 Host2VM Communication Example Using qemu vhost Back End
203 .. code-block:: console
205 qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 -mem-path /dev/
206 hugepages -mem-prealloc
207 -drive file=/data/DPDKVMS/dpdk-vm1
208 -netdev tap,id=vm1_p1,ifname=tap0,script=no,vhost=on
209 -device virtio-net-pci,netdev=vm1_p1,bus=pci.0,addr=0x3,ioeventfd=on
210 -device pci-assign,host=04:10.1 \
212 In this example, the packet reception flow path is:
214 IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest
215 VM virtio port 0 Rx burst-> Guest VM 82599 VF port1 Tx burst-> IXIA packet
218 The packet transmission flow is:
220 IXIA packet generator-> Guest VM 82599 VF port1 Rx burst-> Guest VM virtio
221 port 0 Tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
224 Virtio PMD Rx/Tx Callbacks
225 --------------------------
227 Virtio driver has 3 Rx callbacks and 2 Tx callbacks.
231 #. ``virtio_recv_pkts``:
232 Regular version without mergeable Rx buffer support.
234 #. ``virtio_recv_mergeable_pkts``:
235 Regular version with mergeable Rx buffer support.
237 #. ``virtio_recv_pkts_vec``:
238 Vector version without mergeable Rx buffer support, also fixes the available
239 ring indexes and uses vector instructions to optimize performance.
243 #. ``virtio_xmit_pkts``:
246 #. ``virtio_xmit_pkts_simple``:
247 Vector version fixes the available ring indexes to optimize performance.
250 By default, the non-vector callbacks are used:
252 * For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is
253 used; otherwise ``virtio_recv_mergeable_pkts``.
255 * For Tx: ``virtio_xmit_pkts``.
258 Vector callbacks will be used when:
260 * ``txq_flags`` is set to ``VIRTIO_SIMPLE_FLAGS`` (0xF01), which implies:
262 * Single segment is specified.
264 * No offload support is needed.
266 * Mergeable Rx buffers is disabled.
268 The corresponding callbacks are:
270 * For Rx: ``virtio_recv_pkts_vec``.
272 * For Tx: ``virtio_xmit_pkts_simple``.
275 Example of using the vector version of the virtio poll mode driver in
278 testpmd -l 0-2 -n 4 -- -i --txqflags=0xF01 --rxq=1 --txq=1 --nb-cores=1
284 .. _virtio_interrupt_mode:
286 There are three kinds of interrupts from a virtio device over PCI bus: config
287 interrupt, Rx interrupts, and Tx interrupts. Config interrupt is used for
288 notification of device configuration changes, especially link status (lsc).
289 Interrupt mode is translated into Rx interrupts in the context of DPDK.
291 Prerequisites for Rx interrupts
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294 To support Rx interrupts,
295 #. Check if guest kernel supports VFIO-NOIOMMU:
297 Linux started to support VFIO-NOIOMMU since 4.8.0. Make sure the guest
298 kernel is compiled with:
300 .. code-block:: console
302 CONFIG_VFIO_NOIOMMU=y
304 #. Properly set msix vectors when starting VM:
306 Enable multi-queue when starting VM, and specify msix vectors in qemu
307 cmdline. (N+1) is the minimum, and (2N+2) is mostly recommended.
309 .. code-block:: console
311 $(QEMU) ... -device virtio-net-pci,mq=on,vectors=2N+2 ...
313 #. In VM, insert vfio module in NOIOMMU mode:
315 .. code-block:: console
317 modprobe vfio enable_unsafe_noiommu_mode=1
320 #. In VM, bind the virtio device with vfio-pci:
322 .. code-block:: console
324 python tools/dpdk-devbind.py -b vfio-pci 00:03.0
329 Here we use l3fwd-power as an example to show how to get started.
333 .. code-block:: console
335 $ l3fwd-power -l 0-1 -- -p 1 -P --config="(0,0,1)" \
336 --no-numa --parse-ptype