doc/guides/nics/kni.rst

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