doc/guides/prog_guide/kernel_nic_interface.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2015 Intel Corporation.
   3
   4 .. _kni:
   5
   6 Kernel NIC Interface
   7 ====================
   8
   9 The DPDK Kernel NIC Interface (KNI) allows userspace applications access to the Linux* control plane.
  10
  11 The benefits of using the DPDK KNI are:
  12
  13 *   Faster than existing Linux TUN/TAP interfaces
  14     (by eliminating system calls and copy_to_user()/copy_from_user() operations.
  15
  16 *   Allows management of DPDK ports using standard Linux net tools such as ethtool, ifconfig and tcpdump.
  17
  18 *   Allows an interface with the kernel network stack.
  19
  20 The components of an application using the DPDK Kernel NIC Interface are shown in :numref:`figure_kernel_nic_intf`.
  21
  22 .. _figure_kernel_nic_intf:
  23
  24 .. figure:: img/kernel_nic_intf.*
  25
  26    Components of a DPDK KNI Application
  27
  28
  29 The DPDK KNI Kernel Module
  30 --------------------------
  31
  32 The KNI kernel loadable module provides support for two types of devices:
  33
  34 *   A Miscellaneous device (/dev/kni) that:
  35
  36     *   Creates net devices (via ioctl  calls).
  37
  38     *   Maintains a kernel thread context shared by all KNI instances
  39         (simulating the RX side of the net driver).
  40
  41     *   For single kernel thread mode, maintains a kernel thread context shared by all KNI instances
  42         (simulating the RX side of the net driver).
  43
  44     *   For multiple kernel thread mode, maintains a kernel thread context for each KNI instance
  45         (simulating the RX side of the net driver).
  46
  47 *   Net device:
  48
  49     *   Net functionality provided by implementing several operations such as netdev_ops,
  50         header_ops, ethtool_ops that are defined by struct net_device,
  51         including support for DPDK mbufs and FIFOs.
  52
  53     *   The interface name is provided from userspace.
  54
  55     *   The MAC address can be the real NIC MAC address or random.
  56
  57 KNI Creation and Deletion
  58 -------------------------
  59
  60 The KNI interfaces are created by a DPDK application dynamically.
  61 The interface name and FIFO details are provided by the application through an ioctl call
  62 using the rte_kni_device_info struct which contains:
  63
  64 *   The interface name.
  65
  66 *   Physical addresses of the corresponding memzones for the relevant FIFOs.
  67
  68 *   Mbuf mempool details, both physical and virtual (to calculate the offset for mbuf pointers).
  69
  70 *   PCI information.
  71
  72 *   Core affinity.
  73
  74 Refer to rte_kni_common.h in the DPDK source code for more details.
  75
  76 The physical addresses will be re-mapped into the kernel address space and stored in separate KNI contexts.
  77
  78 The affinity of kernel RX thread (both single and multi-threaded modes) is controlled by force_bind and
  79 core_id config parameters.
  80
  81 The KNI interfaces can be deleted by a DPDK application dynamically after being created.
  82 Furthermore, all those KNI interfaces not deleted will be deleted on the release operation
  83 of the miscellaneous device (when the DPDK application is closed).
  84
  85 DPDK mbuf Flow
  86 --------------
  87
  88 To minimize the amount of DPDK code running in kernel space, the mbuf mempool is managed in userspace only.
  89 The kernel module will be aware of mbufs,
  90 but all mbuf allocation and free operations will be handled by the DPDK application only.
  91
  92 :numref:`figure_pkt_flow_kni` shows a typical scenario with packets sent in both directions.
  93
  94 .. _figure_pkt_flow_kni:
  95
  96 .. figure:: img/pkt_flow_kni.*
  97
  98    Packet Flow via mbufs in the DPDK KNI
  99
 100
 101 Use Case: Ingress
 102 -----------------
 103
 104 On the DPDK RX side, the mbuf is allocated by the PMD in the RX thread context.
 105 This thread will enqueue the mbuf in the rx_q FIFO.
 106 The KNI thread will poll all KNI active devices for the rx_q.
 107 If an mbuf is dequeued, it will be converted to a sk_buff and sent to the net stack via netif_rx().
 108 The dequeued mbuf must be freed, so the same pointer is sent back in the free_q FIFO.
 109
 110 The RX thread, in the same main loop, polls this FIFO and frees the mbuf after dequeuing it.
 111
 112 Use Case: Egress
 113 ----------------
 114
 115 For packet egress the DPDK application must first enqueue several mbufs to create an mbuf cache on the kernel side.
 116
 117 The packet is received from the Linux net stack, by calling the kni_net_tx() callback.
 118 The mbuf is dequeued (without waiting due the cache) and filled with data from sk_buff.
 119 The sk_buff is then freed and the mbuf sent in the tx_q FIFO.
 120
 121 The DPDK TX thread dequeues the mbuf and sends it to the PMD (via rte_eth_tx_burst()).
 122 It then puts the mbuf back in the cache.
 123
 124 Ethtool
 125 -------
 126
 127 Ethtool is a Linux-specific tool with corresponding support in the kernel
 128 where each net device must register its own callbacks for the supported operations.
 129 The current implementation uses the igb/ixgbe modified Linux drivers for ethtool support.
 130 Ethtool is not supported in i40e and VMs (VF or EM devices).
 131
 132 Link state and MTU change
 133 -------------------------
 134
 135 Link state and MTU change are network interface specific operations usually done via ifconfig.
 136 The request is initiated from the kernel side (in the context of the ifconfig process)
 137 and handled by the user space DPDK application.
 138 The application polls the request, calls the application handler and returns the response back into the kernel space.
 139
 140 The application handlers can be registered upon interface creation or explicitly registered/unregistered in runtime.
 141 This provides flexibility in multiprocess scenarios
 142 (where the KNI is created in the primary process but the callbacks are handled in the secondary one).
 143 The constraint is that a single process can register and handle the requests.