ceph/src/seastar/dpdk/doc/guides/nics/e1000em.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 Driver for VM Emulated Devices
   5 ==============================
   6
   7 The 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® 8274L Gigabit Ethernet Controller.
  14
  15 Validated Hypervisors
  16 ---------------------
  17
  18 The 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
  26 Recommended Guest Operating System in Virtual Machine
  27 -----------------------------------------------------
  28
  29 The recommended guest operating system in a virtualized environment is:
  30
  31 *   Fedora* 18 (64-bit)
  32
  33 For supported kernel versions, refer to the *DPDK Release Notes*.
  34
  35 Setting Up a KVM Virtual Machine
  36 --------------------------------
  37
  38 The 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
  50 The 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
 140 Known Limitations of Emulated Devices
 141 -------------------------------------
 142
 143 The 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     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.