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
33Kernel NIC Interface
34====================
35
36The DPDK Kernel NIC Interface (KNI) allows userspace applications access to the Linux* control plane.
37
38The 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
47The 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
56The DPDK KNI Kernel Module
57--------------------------
58
59The 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
84KNI Creation and Deletion
85-------------------------
86
87The KNI interfaces are created by a DPDK application dynamically.
88The interface name and FIFO details are provided by the application through an ioctl call
89using 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
101Refer to rte_kni_common.h in the DPDK source code for more details.
102
103The physical addresses will be re-mapped into the kernel address space and stored in separate KNI contexts.
104
105The affinity of kernel RX thread (both single and multi-threaded modes) is controlled by force_bind and
106core_id config parameters.
107
108The KNI interfaces can be deleted by a DPDK application dynamically after being created.
109Furthermore, all those KNI interfaces not deleted will be deleted on the release operation
110of the miscellaneous device (when the DPDK application is closed).
111
112DPDK mbuf Flow
113--------------
114
115To minimize the amount of DPDK code running in kernel space, the mbuf mempool is managed in userspace only.
116The kernel module will be aware of mbufs,
117but 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
128Use Case: Ingress
129-----------------
130
131On the DPDK RX side, the mbuf is allocated by the PMD in the RX thread context.
132This thread will enqueue the mbuf in the rx_q FIFO.
133The KNI thread will poll all KNI active devices for the rx_q.
134If an mbuf is dequeued, it will be converted to a sk_buff and sent to the net stack via netif_rx().
135The dequeued mbuf must be freed, so the same pointer is sent back in the free_q FIFO.
136
137The RX thread, in the same main loop, polls this FIFO and frees the mbuf after dequeuing it.
138
139Use Case: Egress
140----------------
141
142For packet egress the DPDK application must first enqueue several mbufs to create an mbuf cache on the kernel side.
143
144The packet is received from the Linux net stack, by calling the kni_net_tx() callback.
145The mbuf is dequeued (without waiting due the cache) and filled with data from sk_buff.
146The sk_buff is then freed and the mbuf sent in the tx_q FIFO.
147
148The DPDK TX thread dequeues the mbuf and sends it to the PMD (via rte_eth_tx_burst()).
149It then puts the mbuf back in the cache.
150
151Ethtool
152-------
153
154Ethtool is a Linux-specific tool with corresponding support in the kernel
155where each net device must register its own callbacks for the supported operations.
156The current implementation uses the igb/ixgbe modified Linux drivers for ethtool support.
157Ethtool is not supported in i40e and VMs (VF or EM devices).
158
159Link state and MTU change
160-------------------------
161
162Link state and MTU change are network interface specific operations usually done via ifconfig.
163The request is initiated from the kernel side (in the context of the ifconfig process)
164and handled by the user space DPDK application.
165The application polls the request, calls the application handler and returns the response back into the kernel space.
166
167The application handlers can be registered upon interface creation or explicitly registered/unregistered in runtime.
168This provides flexibility in multiprocess scenarios
169(where the KNI is created in the primary process but the callbacks are handled in the secondary one).
170The constraint is that a single process can register and handle the requests.
171