1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Driver for VM Emulated Devices 5============================== 6 7The DPDK EM poll mode driver supports the following emulated devices: 8 9* qemu-kvm emulated Intel® 82540EM Gigabit Ethernet Controller (qemu e1000 device) 10 11* VMware emulated Intel® 82545EM Gigabit Ethernet Controller 12 13* VMware emulated Intel® 82574L Gigabit Ethernet Controller. 14 15Validated Hypervisors 16--------------------- 17 18The validated hypervisors are: 19 20* KVM (Kernel Virtual Machine) with Qemu, version 0.14.0 21 22* KVM (Kernel Virtual Machine) with Qemu, version 0.15.1 23 24* VMware ESXi 5.0, Update 1 25 26Recommended Guest Operating System in Virtual Machine 27----------------------------------------------------- 28 29The recommended guest operating system in a virtualized environment is: 30 31* Fedora* 18 (64-bit) 32 33For supported kernel versions, refer to the *DPDK Release Notes*. 34 35Setting Up a KVM Virtual Machine 36-------------------------------- 37 38The following describes a target environment: 39 40* Host Operating System: Fedora 14 41 42* Hypervisor: KVM (Kernel Virtual Machine) with Qemu version, 0.14.0 43 44* Guest Operating System: Fedora 14 45 46* Linux Kernel Version: Refer to the DPDK Getting Started Guide 47 48* Target Applications: testpmd 49 50The setup procedure is as follows: 51 52#. Download qemu-kvm-0.14.0 from 53 `http://sourceforge.net/projects/kvm/files/qemu-kvm/ <http://sourceforge.net/projects/kvm/files/qemu-kvm/>`_ 54 and install it in the Host OS using the following steps: 55 56 When using a recent kernel (2.6.25+) with kvm modules included: 57 58 .. code-block:: console 59 60 tar xzf qemu-kvm-release.tar.gz cd qemu-kvm-release 61 ./configure --prefix=/usr/local/kvm 62 make 63 sudo make install 64 sudo /sbin/modprobe kvm-intel 65 66 When using an older kernel or a kernel from a distribution without the kvm modules, 67 you must download (from the same link), compile and install the modules yourself: 68 69 .. code-block:: console 70 71 tar xjf kvm-kmod-release.tar.bz2 72 cd kvm-kmod-release 73 ./configure 74 make 75 sudo make install 76 sudo /sbin/modprobe kvm-intel 77 78 Note that qemu-kvm installs in the /usr/local/bin directory. 79 80 For more details about KVM configuration and usage, please refer to: 81 `http://www.linux-kvm.org/page/HOWTO1 <http://www.linux-kvm.org/page/HOWTO1>`_. 82 83#. Create a Virtual Machine and install Fedora 14 on the Virtual Machine. 84 This is referred to as the Guest Operating System (Guest OS). 85 86#. Start the Virtual Machine with at least one emulated e1000 device. 87 88 .. note:: 89 90 The Qemu provides several choices for the emulated network device backend. 91 Most commonly used is a TAP networking backend that uses a TAP networking device in the host. 92 For more information about Qemu supported networking backends and different options for configuring networking at Qemu, 93 please refer to: 94 95 — `http://www.linux-kvm.org/page/Networking <http://www.linux-kvm.org/page/Networking>`_ 96 97 — `http://wiki.qemu.org/Documentation/Networking <http://wiki.qemu.org/Documentation/Networking>`_ 98 99 — `http://qemu.weilnetz.de/qemu-doc.html <http://qemu.weilnetz.de/qemu-doc.html>`_ 100 101 For example, to start a VM with two emulated e1000 devices, issue the following command: 102 103 .. code-block:: console 104 105 /usr/local/kvm/bin/qemu-system-x86_64 -cpu host -smp 4 -hda qemu1.raw -m 1024 106 -net nic,model=e1000,vlan=1,macaddr=DE:AD:1E:00:00:01 107 -net tap,vlan=1,ifname=tapvm01,script=no,downscript=no 108 -net nic,model=e1000,vlan=2,macaddr=DE:AD:1E:00:00:02 109 -net tap,vlan=2,ifname=tapvm02,script=no,downscript=no 110 111 where: 112 113 — -m = memory to assign 114 115 — -smp = number of smp cores 116 117 — -hda = virtual disk image 118 119 This command starts a new virtual machine with two emulated 82540EM devices, 120 backed up with two TAP networking host interfaces, tapvm01 and tapvm02. 121 122 .. code-block:: console 123 124 # ip tuntap show 125 tapvm01: tap 126 tapvm02: tap 127 128#. Configure your TAP networking interfaces using ip/ifconfig tools. 129 130#. Log in to the guest OS and check that the expected emulated devices exist: 131 132 .. code-block:: console 133 134 # lspci -d 8086:100e 135 00:04.0 Ethernet controller: Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03) 136 00:05.0 Ethernet controller: Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03) 137 138#. Install the DPDK and run testpmd. 139 140Known Limitations of Emulated Devices 141------------------------------------- 142 143The following are known limitations: 144 145#. The Qemu e1000 RX path does not support multiple descriptors/buffers per packet. 146 Therefore, rte_mbuf should be big enough to hold the whole packet. 147 For example, to allow testpmd to receive jumbo frames, use the following: 148 149 dpdk-testpmd [options] -- --mbuf-size=<your-max-packet-size> 150 151#. Qemu e1000 does not validate the checksum of incoming packets. 152 153#. Qemu e1000 only supports one interrupt source, so link and Rx interrupt should be exclusive. 154 155#. Qemu e1000 does not support interrupt auto-clear, application should disable interrupt immediately when woken up. 156