1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2010-2015 Intel Corporation.
3
4.. _kni:
5
6Kernel NIC Interface
7====================
8
9The DPDK Kernel NIC Interface (KNI) allows userspace applications access to the Linux* control plane.
10
11The 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
20The 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
29The DPDK KNI Kernel Module
30--------------------------
31
32The 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
57KNI Creation and Deletion
58-------------------------
59
60The KNI interfaces are created by a DPDK application dynamically.
61The interface name and FIFO details are provided by the application through an ioctl call
62using 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
74Refer to rte_kni_common.h in the DPDK source code for more details.
75
76The physical addresses will be re-mapped into the kernel address space and stored in separate KNI contexts.
77
78The affinity of kernel RX thread (both single and multi-threaded modes) is controlled by force_bind and
79core_id config parameters.
80
81The KNI interfaces can be deleted by a DPDK application dynamically after being created.
82Furthermore, all those KNI interfaces not deleted will be deleted on the release operation
83of the miscellaneous device (when the DPDK application is closed).
84
85DPDK mbuf Flow
86--------------
87
88To minimize the amount of DPDK code running in kernel space, the mbuf mempool is managed in userspace only.
89The kernel module will be aware of mbufs,
90but 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
101Use Case: Ingress
102-----------------
103
104On the DPDK RX side, the mbuf is allocated by the PMD in the RX thread context.
105This thread will enqueue the mbuf in the rx_q FIFO.
106The KNI thread will poll all KNI active devices for the rx_q.
107If an mbuf is dequeued, it will be converted to a sk_buff and sent to the net stack via netif_rx().
108The dequeued mbuf must be freed, so the same pointer is sent back in the free_q FIFO.
109
110The RX thread, in the same main loop, polls this FIFO and frees the mbuf after dequeuing it.
111
112Use Case: Egress
113----------------
114
115For packet egress the DPDK application must first enqueue several mbufs to create an mbuf cache on the kernel side.
116
117The packet is received from the Linux net stack, by calling the kni_net_tx() callback.
118The mbuf is dequeued (without waiting due the cache) and filled with data from sk_buff.
119The sk_buff is then freed and the mbuf sent in the tx_q FIFO.
120
121The DPDK TX thread dequeues the mbuf and sends it to the PMD (via rte_eth_tx_burst()).
122It then puts the mbuf back in the cache.
123
124Ethtool
125-------
126
127Ethtool is a Linux-specific tool with corresponding support in the kernel
128where each net device must register its own callbacks for the supported operations.
129The current implementation uses the igb/ixgbe modified Linux drivers for ethtool support.
130Ethtool is not supported in i40e and VMs (VF or EM devices).
131
132Link state and MTU change
133-------------------------
134
135Link state and MTU change are network interface specific operations usually done via ifconfig.
136The request is initiated from the kernel side (in the context of the ifconfig process)
137and handled by the user space DPDK application.
138The application polls the request, calls the application handler and returns the response back into the kernel space.
139
140The application handlers can be registered upon interface creation or explicitly registered/unregistered in runtime.
141This provides flexibility in multiprocess scenarios
142(where the KNI is created in the primary process but the callbacks are handled in the secondary one).
143The constraint is that a single process can register and handle the requests.
144