doc/guides/nics/kni.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 KNI Poll Mode Driver
   5 ======================
   6
   7 KNI PMD is wrapper to the :ref:`librte_kni <kni>` library.
   8
   9 This PMD enables using KNI without having a KNI specific application,
  10 any forwarding application can use PMD interface for KNI.
  11
  12 Sending packets to any DPDK controlled interface or sending to the
  13 Linux networking stack will be transparent to the DPDK application.
  14
  15 To create a KNI device ``net_kni#`` device name should be used, and this
  16 will create ``kni#`` Linux virtual network interface.
  17
  18 There is no physical device backend for the virtual KNI device.
  19
  20 Packets sent to the KNI Linux interface will be received by the DPDK
  21 application, and DPDK application may forward packets to a physical NIC
  22 or to a virtual device (like another KNI interface or PCAP interface).
  23
  24 To forward any traffic from physical NIC to the Linux networking stack,
  25 an application should control a physical port and create one virtual KNI port,
  26 and forward between two.
  27
  28 Using this PMD requires KNI kernel module be inserted.
  29
  30
  31 Usage
  32 -----
  33
  34 EAL ``--vdev`` argument can be used to create KNI device instance, like::
  35
  36         testpmd --vdev=net_kni0 --vdev=net_kn1 -- -i
  37
  38 Above command will create ``kni0`` and ``kni1`` Linux network interfaces,
  39 those interfaces can be controlled by standard Linux tools.
  40
  41 When testpmd forwarding starts, any packets sent to ``kni0`` interface
  42 forwarded to the ``kni1`` interface and vice versa.
  43
  44 There is no hard limit on number of interfaces that can be created.
  45
  46
  47 Default interface configuration
  48 -------------------------------
  49
  50 ``librte_kni`` can create Linux network interfaces with different features,
  51 feature set controlled by a configuration struct, and KNI PMD uses a fixed
  52 configuration:
  53
  54     .. code-block:: console
  55
  56         Interface name: kni#
  57         force bind kernel thread to a core : NO
  58         mbuf size: (rte_pktmbuf_data_room_size(pktmbuf_pool) - RTE_PKTMBUF_HEADROOM)
  59         mtu: (conf.mbuf_size - RTE_ETHER_HDR_LEN)
  60
  61 KNI control path is not supported with the PMD, since there is no physical
  62 backend device by default.
  63
  64
  65 PMD arguments
  66 -------------
  67
  68 ``no_request_thread``, by default PMD creates a pthread for each KNI interface
  69 to handle Linux network interface control commands, like ``ifconfig kni0 up``
  70
  71 With ``no_request_thread`` option, pthread is not created and control commands
  72 not handled by PMD.
  73
  74 By default request thread is enabled. And this argument should not be used
  75 most of the time, unless this PMD used with customized DPDK application to handle
  76 requests itself.
  77
  78 Argument usage::
  79
  80         testpmd --vdev "net_kni0,no_request_thread=1" -- -i
  81
  82
  83 PMD log messages
  84 ----------------
  85
  86 If KNI kernel module (rte_kni.ko) not inserted, following error log printed::
  87
  88         "KNI: KNI subsystem has not been initialized. Invoke rte_kni_init() first"
  89
  90
  91 PMD testing
  92 -----------
  93
  94 It is possible to test PMD quickly using KNI kernel module loopback feature:
  95
  96 * Insert KNI kernel module with loopback support:
  97
  98     .. code-block:: console
  99
 100         insmod build/kmod/rte_kni.ko lo_mode=lo_mode_fifo_skb
 101
 102 * Start testpmd with no physical device but two KNI virtual devices:
 103
 104     .. code-block:: console
 105
 106         ./testpmd --vdev net_kni0 --vdev net_kni1 -- -i
 107
 108     .. code-block:: console
 109
 110         ...
 111         Configuring Port 0 (socket 0)
 112         KNI: pci: 00:00:00       c580:b8
 113         Port 0: 1A:4A:5B:7C:A2:8C
 114         Configuring Port 1 (socket 0)
 115         KNI: pci: 00:00:00       600:b9
 116         Port 1: AE:95:21:07:93:DD
 117         Checking link statuses...
 118         Port 0 Link Up - speed 10000 Mbps - full-duplex
 119         Port 1 Link Up - speed 10000 Mbps - full-duplex
 120         Done
 121         testpmd>
 122
 123 * Observe Linux interfaces
 124
 125     .. code-block:: console
 126
 127         $ ifconfig kni0 && ifconfig kni1
 128         kni0: flags=4098<BROADCAST,MULTICAST>  mtu 1500
 129                 ether ae:8e:79:8e:9b:c8  txqueuelen 1000  (Ethernet)
 130                 RX packets 0  bytes 0 (0.0 B)
 131                 RX errors 0  dropped 0  overruns 0  frame 0
 132                 TX packets 0  bytes 0 (0.0 B)
 133                 TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
 134
 135         kni1: flags=4098<BROADCAST,MULTICAST>  mtu 1500
 136                 ether 9e:76:43:53:3e:9b  txqueuelen 1000  (Ethernet)
 137                 RX packets 0  bytes 0 (0.0 B)
 138                 RX errors 0  dropped 0  overruns 0  frame 0
 139                 TX packets 0  bytes 0 (0.0 B)
 140                 TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
 141
 142
 143 * Start forwarding with tx_first:
 144
 145     .. code-block:: console
 146
 147         testpmd> start tx_first
 148
 149 * Quit and check forwarding stats:
 150
 151     .. code-block:: console
 152
 153         testpmd> quit
 154         Telling cores to stop...
 155         Waiting for lcores to finish...
 156
 157         ---------------------- Forward statistics for port 0  ----------------------
 158         RX-packets: 35637905       RX-dropped: 0             RX-total: 35637905
 159         TX-packets: 35637947       TX-dropped: 0             TX-total: 35637947
 160         ----------------------------------------------------------------------------
 161
 162         ---------------------- Forward statistics for port 1  ----------------------
 163         RX-packets: 35637915       RX-dropped: 0             RX-total: 35637915
 164         TX-packets: 35637937       TX-dropped: 0             TX-total: 35637937
 165         ----------------------------------------------------------------------------
 166
 167         +++++++++++++++ Accumulated forward statistics for all ports+++++++++++++++
 168         RX-packets: 71275820       RX-dropped: 0             RX-total: 71275820
 169         TX-packets: 71275884       TX-dropped: 0             TX-total: 71275884
 170         ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 171