doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   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
  14     distribution.
  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.
  18
  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.
  30
  31 Poll Mode Driver for Emulated Virtio NIC
  32 ========================================
  33
  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.
  38
  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.
  43
  44 In future release, we will also make enhancement to vhost backend,
  45 releasing peak performance of virtio PMD driver.
  46
  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".
  49
  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.
  52
  53 Virtio Implementation in DPDK
  54 -----------------------------
  55
  56 For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
  57
  58 As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
  59
  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.
  61
  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.
  65
  66 Features and Limitations of virtio PMD
  67 --------------------------------------
  68
  69 In this release, the virtio PMD driver provides the basic functionality of packet reception and transmission.
  70
  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.
  73
  74 *   It supports multicast packets and promiscuous mode.
  75
  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.
  79
  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.
  83
  84 *   RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct virtio_net_hdr), which is 10 bytes.
  85
  86 *   Virtio does not support runtime configuration.
  87
  88 *   Virtio supports Link State interrupt.
  89
  90 *   Virtio supports software vlan stripping and inserting.
  91
  92 *   Virtio supports using port IO to get PCI resource when uio/igb_uio module is not available.
  93
  94 Prerequisites
  95 -------------
  96
  97 The following prerequisites apply:
  98
  99 *   In the BIOS, turn VT-x and VT-d on
 100
 101 *   Linux kernel with KVM module; vhost module loaded and ioeventfd supported.
 102     Qemu standard backend without vhost support isn't tested, and probably isn't supported.
 103
 104 Virtio with kni vhost Back End
 105 ------------------------------
 106
 107 This section demonstrates kni vhost back end example setup for Phy-VM Communication.
 108
 109 .. _pg_figure_14:
 110
 111 **Figure 14. Host2VM Communication Example Using kni vhost Back End**
 112
 113 .. image29_png has been renamed
 114
 115 |host_vm_comms|
 116
 117 Host2VM communication example
 118
 119 #.  Load the kni kernel module:
 120
 121     .. code-block:: console
 122
 123         insmod rte_kni.ko
 124
 125     Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
 126     Please refer to the *DPDK Getting Started Guide* for detailed instructions.
 127
 128 #.  Launch the kni user application:
 129
 130     .. code-block:: console
 131
 132         examples/kni/build/app/kni -c 0xf -n 4 -- -p 0x1 -i 0x1 -o 0x2
 133
 134     This command generates one network device vEth0 for physical port.
 135     If specify more physical ports, the generated network device will be vEth1, vEth2, and so on.
 136
 137     For each physical port, kni creates two user threads.
 138     One thread loops to fetch packets from the physical NIC port into the kni receive queue.
 139     The other user thread loops to send packets in the kni transmit queue.
 140
 141     For each physical port, kni also creates a kernel thread that retrieves packets from the kni receive queue,
 142     place them onto kni's raw socket's queue and wake up the vhost kernel thread to exchange packets with the virtio virt queue.
 143
 144     For more details about kni, please refer to Chapter 24 "Kernel NIC Interface".
 145
 146 #.  Enable the kni raw socket functionality for the specified physical NIC port,
 147     get the generated file descriptor and set it in the qemu command line parameter.
 148     Always remember to set ioeventfd_on and vhost_on.
 149
 150     Example:
 151
 152     .. code-block:: console
 153
 154         echo 1 > /sys/class/net/vEth0/sock_en
 155         fd=`cat /sys/class/net/vEth0/sock_fd`
 156         exec qemu-system-x86_64 -enable-kvm -cpu host \
 157         -m 2048 -smp 4 -name dpdk-test1-vm1 \
 158         -drive file=/data/DPDKVMS/dpdk-vm.img \
 159         -netdev tap, fd=$fd,id=mynet_kni, script=no,vhost=on \
 160         -device virtio-net-pci,netdev=mynet_kni,bus=pci.0,addr=0x3,ioeventfd=on \
 161         -vnc:1 -daemonize
 162
 163     In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
 164     which means received packets come from vEth0, and transmitted packets is sent to vEth0.
 165
 166 #.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
 167     When the virtio port in guest bursts rx, it is getting packets from the raw socket's receive queue.
 168     When the virtio port bursts tx, it is sending packet to the tx_q.
 169
 170     .. code-block:: console
 171
 172         modprobe uio
 173         echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
 174         modprobe uio_pci_generic
 175         python tools/dpdk_nic_bind.py -b uio_pci_generic 00:03.0
 176
 177     We use testpmd as the forwarding application in this example.
 178
 179     .. image30_png has been renamed
 180
 181     |console|
 182
 183 #.  Use IXIA packet generator to inject a packet stream into the KNI physical port.
 184
 185     The packet reception and transmission flow path is:
 186
 187     IXIA packet generator->82599 PF->KNI rx queue->KNI raw socket queue->Guest VM virtio port 0 rx burst->Guest VM virtio port 0 tx burst-> KNI tx queue->82599 PF-> IXIA packet generator
 188
 189 Virtio with qemu virtio Back End
 190 --------------------------------
 191
 192 .. _pg_figure_15:
 193
 194 **Figure 15. Host2VM Communication Example Using qemu vhost Back End**
 195
 196    .. image31_png has been renamed
 197
 198    |host_vm_comms_qemu|
 199
 200 .. code-block:: console
 201
 202     qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 -mem-path /dev/
 203     hugepages -mem-prealloc
 204     -drive file=/data/DPDKVMS/dpdk-vm1
 205     -netdev tap,id=vm1_p1,ifname=tap0,script=no,vhost=on
 206     -device virtio-net-pci,netdev=vm1_p1,bus=pci.0,addr=0x3,ioeventfd=on
 207     -device pci-assign,host=04:10.1 \
 208
 209 In this example, the packet reception flow path is:
 210
 211     IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest VM virtio port 0 rx burst-> Guest VM 82599 VF port1 tx burst-> IXIA packet generator
 212
 213 The packet transmission flow is:
 214
 215     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
 216
 217 .. |host_vm_comms| image:: img/host_vm_comms.*
 218
 219 .. |console| image:: img/console.*
 220
 221 .. |host_vm_comms_qemu| image:: img/host_vm_comms_qemu.*