doc/guides/prog_guide/kernel_nic_interface.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2015 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 .. _kni:
  32
  33 Kernel NIC Interface
  34 ====================
  35
  36 The DPDK Kernel NIC Interface (KNI) allows userspace applications access to the Linux* control plane.
  37
  38 The benefits of using the DPDK KNI are:
  39
  40 *   Faster than existing Linux TUN/TAP interfaces
  41     (by eliminating system calls and copy_to_user()/copy_from_user() operations.
  42
  43 *   Allows management of DPDK ports using standard Linux net tools such as ethtool, ifconfig and tcpdump.
  44
  45 *   Allows an interface with the kernel network stack.
  46
  47 The components of an application using the DPDK Kernel NIC Interface are shown in :numref:`figure_kernel_nic_intf`.
  48
  49 .. _figure_kernel_nic_intf:
  50
  51 .. figure:: img/kernel_nic_intf.*
  52
  53    Components of a DPDK KNI Application
  54
  55
  56 The DPDK KNI Kernel Module
  57 --------------------------
  58
  59 The KNI kernel loadable module provides support for two types of devices:
  60
  61 *   A Miscellaneous device (/dev/kni) that:
  62
  63     *   Creates net devices (via ioctl  calls).
  64
  65     *   Maintains a kernel thread context shared by all KNI instances
  66         (simulating the RX side of the net driver).
  67
  68     *   For single kernel thread mode, maintains a kernel thread context shared by all KNI instances
  69         (simulating the RX side of the net driver).
  70
  71     *   For multiple kernel thread mode, maintains a kernel thread context for each KNI instance
  72         (simulating the RX side of the new driver).
  73
  74 *   Net device:
  75
  76     *   Net functionality provided by implementing several operations such as netdev_ops,
  77         header_ops, ethtool_ops that are defined by struct net_device,
  78         including support for DPDK mbufs and FIFOs.
  79
  80     *   The interface name is provided from userspace.
  81
  82     *   The MAC address can be the real NIC MAC address or random.
  83
  84 KNI Creation and Deletion
  85 -------------------------
  86
  87 The KNI interfaces are created by a DPDK application dynamically.
  88 The interface name and FIFO details are provided by the application through an ioctl call
  89 using the rte_kni_device_info struct which contains:
  90
  91 *   The interface name.
  92
  93 *   Physical addresses of the corresponding memzones for the relevant FIFOs.
  94
  95 *   Mbuf mempool details, both physical and virtual (to calculate the offset for mbuf pointers).
  96
  97 *   PCI information.
  98
  99 *   Core affinity.
 100
 101 Refer to rte_kni_common.h in the DPDK source code for more details.
 102
 103 The physical addresses will be re-mapped into the kernel address space and stored in separate KNI contexts.
 104
 105 The affinity of kernel RX thread (both single and multi-threaded modes) is controlled by force_bind and
 106 core_id config parameters.
 107
 108 The KNI interfaces can be deleted by a DPDK application dynamically after being created.
 109 Furthermore, all those KNI interfaces not deleted will be deleted on the release operation
 110 of the miscellaneous device (when the DPDK application is closed).
 111
 112 DPDK mbuf Flow
 113 --------------
 114
 115 To minimize the amount of DPDK code running in kernel space, the mbuf mempool is managed in userspace only.
 116 The kernel module will be aware of mbufs,
 117 but all mbuf allocation and free operations will be handled by the DPDK application only.
 118
 119 :numref:`figure_pkt_flow_kni` shows a typical scenario with packets sent in both directions.
 120
 121 .. _figure_pkt_flow_kni:
 122
 123 .. figure:: img/pkt_flow_kni.*
 124
 125    Packet Flow via mbufs in the DPDK KNI
 126
 127
 128 Use Case: Ingress
 129 -----------------
 130
 131 On the DPDK RX side, the mbuf is allocated by the PMD in the RX thread context.
 132 This thread will enqueue the mbuf in the rx_q FIFO.
 133 The KNI thread will poll all KNI active devices for the rx_q.
 134 If an mbuf is dequeued, it will be converted to a sk_buff and sent to the net stack via netif_rx().
 135 The dequeued mbuf must be freed, so the same pointer is sent back in the free_q FIFO.
 136
 137 The RX thread, in the same main loop, polls this FIFO and frees the mbuf after dequeuing it.
 138
 139 Use Case: Egress
 140 ----------------
 141
 142 For packet egress the DPDK application must first enqueue several mbufs to create an mbuf cache on the kernel side.
 143
 144 The packet is received from the Linux net stack, by calling the kni_net_tx() callback.
 145 The mbuf is dequeued (without waiting due the cache) and filled with data from sk_buff.
 146 The sk_buff is then freed and the mbuf sent in the tx_q FIFO.
 147
 148 The DPDK TX thread dequeues the mbuf and sends it to the PMD (via rte_eth_tx_burst()).
 149 It then puts the mbuf back in the cache.
 150
 151 Ethtool
 152 -------
 153
 154 Ethtool is a Linux-specific tool with corresponding support in the kernel
 155 where each net device must register its own callbacks for the supported operations.
 156 The current implementation uses the igb/ixgbe modified Linux drivers for ethtool support.
 157 Ethtool is not supported in i40e and VMs (VF or EM devices).
 158
 159 Link state and MTU change
 160 -------------------------
 161
 162 Link state and MTU change are network interface specific operations usually done via ifconfig.
 163 The request is initiated from the kernel side (in the context of the ifconfig process)
 164 and handled by the user space DPDK application.
 165 The application polls the request, calls the application handler and returns the response back into the kernel space.
 166
 167 The application handlers can be registered upon interface creation or explicitly registered/unregistered in runtime.
 168 This provides flexibility in multiprocess scenarios
 169 (where the KNI is created in the primary process but the callbacks are handled in the secondary one).
 170 The constraint is that a single process can register and handle the requests.
 171
 172 KNI Working as a Kernel vHost Backend
 173 -------------------------------------
 174
 175 vHost is a kernel module usually working as the backend of virtio (a para- virtualization driver framework)
 176 to accelerate the traffic from the guest to the host.
 177 The DPDK Kernel NIC interface provides the ability to hookup vHost traffic into userspace DPDK application.
 178 Together with the DPDK PMD virtio, it significantly improves the throughput between guest and host.
 179 In the scenario where DPDK is running as fast path in the host, kni-vhost is an efficient path for the traffic.
 180
 181 Overview
 182 ~~~~~~~~
 183
 184 vHost-net has three kinds of real backend implementations. They are: 1) tap, 2) macvtap and 3) RAW socket.
 185 The main idea behind kni-vhost is making the KNI work as a RAW socket, attaching it as the backend instance of vHost-net.
 186 It is using the existing interface with vHost-net, so it does not require any kernel hacking,
 187 and is fully-compatible with the kernel vhost module.
 188 As vHost is still taking responsibility for communicating with the front-end virtio,
 189 it naturally supports both legacy virtio -net and the DPDK PMD virtio.
 190 There is a little penalty that comes from the non-polling mode of vhost.
 191 However, it scales throughput well when using KNI in multi-thread mode.
 192
 193 .. _figure_vhost_net_arch2:
 194
 195 .. figure:: img/vhost_net_arch.*
 196
 197    vHost-net Architecture Overview
 198
 199
 200 Packet Flow
 201 ~~~~~~~~~~~
 202
 203 There is only a minor difference from the original KNI traffic flows.
 204 On transmit side, vhost kthread calls the RAW socket's ops sendmsg and it puts the packets into the KNI transmit FIFO.
 205 On the receive side, the kni kthread gets packets from the KNI receive FIFO, puts them into the queue of the raw socket,
 206 and wakes up the task in vhost kthread to begin receiving.
 207 All the packet copying, irrespective of whether it is on the transmit or receive side,
 208 happens in the context of vhost kthread.
 209 Every vhost-net device is exposed to a front end virtio device in the guest.
 210
 211 .. _figure_kni_traffic_flow:
 212
 213 .. figure:: img/kni_traffic_flow.*
 214
 215    KNI Traffic Flow
 216
 217
 218 Sample Usage
 219 ~~~~~~~~~~~~
 220
 221 Before starting to use KNI as the backend of vhost, the CONFIG_RTE_KNI_VHOST configuration option must be turned on.
 222 Otherwise, by default, KNI will not enable its backend support capability.
 223
 224 Of course, as a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen before compiling the kernel.
 225
 226 #.  Compile the DPDK and insert uio_pci_generic/igb_uio kernel modules as normal.
 227
 228 #.  Insert the KNI kernel module:
 229
 230     .. code-block:: console
 231
 232         insmod ./rte_kni.ko
 233
 234     If using KNI in multi-thread mode, use the following command line:
 235
 236     .. code-block:: console
 237
 238         insmod ./rte_kni.ko kthread_mode=multiple
 239
 240 #.  Running the KNI sample application:
 241
 242     .. code-block:: console
 243
 244         examples/kni/build/app/kni -c -0xf0 -n 4 -- -p 0x3 -P --config="(0,4,6),(1,5,7)"
 245
 246     This command runs the kni sample application with two physical ports.
 247     Each port pins two forwarding cores (ingress/egress) in user space.
 248
 249 #.  Assign a raw socket to vhost-net during qemu-kvm startup.
 250     The DPDK does not provide a script to do this since it is easy for the user to customize.
 251     The following shows the key steps to launch qemu-kvm with kni-vhost:
 252
 253     .. code-block:: bash
 254
 255         #!/bin/bash
 256         echo 1 > /sys/class/net/vEth0/sock_en
 257         fd=`cat /sys/class/net/vEth0/sock_fd`
 258         qemu-kvm \
 259         -name vm1 -cpu host -m 2048 -smp 1 -hda /opt/vm-fc16.img \
 260         -netdev tap,fd=$fd,id=hostnet1,vhost=on \
 261         -device virti-net-pci,netdev=hostnet1,id=net1,bus=pci.0,addr=0x4
 262
 263 It is simple to enable raw socket using sysfs sock_en and get raw socket fd using sock_fd under the KNI device node.
 264
 265 Then, using the qemu-kvm command with the -netdev option to assign such raw socket fd as vhost's backend.
 266
 267 .. note::
 268
 269     The key word tap must exist as qemu-kvm now only supports vhost with a tap backend, so here we cheat qemu-kvm by an existing fd.
 270
 271 Compatibility Configure Option
 272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 273
 274 There is a CONFIG_RTE_KNI_VHOST_VNET_HDR_EN configuration option in DPDK configuration file.
 275 By default, it set to n, which means do not turn on the virtio net header,
 276 which is used to support additional features (such as, csum offload, vlan offload, generic-segmentation and so on),
 277 since the kni-vhost does not yet support those features.
 278
 279 Even if the option is turned on, kni-vhost will ignore the information that the header contains.
 280 When working with legacy virtio on the guest, it is better to turn off unsupported offload features using ethtool -K.
 281 Otherwise, there may be problems such as an incorrect L4 checksum error.