[ceph.git] / ceph / src / spdk / dpdk / doc / guides / nics / kni.rst

..  SPDX-License-Identifier: BSD-3-Clause
    Copyright(c) 2017 Intel Corporation.

KNI Poll Mode Driver
======================

KNI PMD is wrapper to the :ref:`librte_kni <kni>` library.

This PMD enables using KNI without having a KNI specific application,
any forwarding application can use PMD interface for KNI.

Sending packets to any DPDK controlled interface or sending to the
Linux networking stack will be transparent to the DPDK application.

To create a KNI device ``net_kni#`` device name should be used, and this
will create ``kni#`` Linux virtual network interface.

There is no physical device backend for the virtual KNI device.

Packets sent to the KNI Linux interface will be received by the DPDK
application, and DPDK application may forward packets to a physical NIC
or to a virtual device (like another KNI interface or PCAP interface).

To forward any traffic from physical NIC to the Linux networking stack,
an application should control a physical port and create one virtual KNI port,
and forward between two.

Using this PMD requires KNI kernel module be inserted.


Usage
-----

EAL ``--vdev`` argument can be used to create KNI device instance, like::

        testpmd --vdev=net_kni0 --vdev=net_kn1 -- -i

Above command will create ``kni0`` and ``kni1`` Linux network interfaces,
those interfaces can be controlled by standard Linux tools.

When testpmd forwarding starts, any packets sent to ``kni0`` interface
forwarded to the ``kni1`` interface and vice versa.

There is no hard limit on number of interfaces that can be created.


Default interface configuration
-------------------------------

``librte_kni`` can create Linux network interfaces with different features,
feature set controlled by a configuration struct, and KNI PMD uses a fixed
configuration:

    .. code-block:: console

        Interface name: kni#
        force bind kernel thread to a core : NO
        mbuf size: (rte_pktmbuf_data_room_size(pktmbuf_pool) - RTE_PKTMBUF_HEADROOM)
        mtu: (conf.mbuf_size - RTE_ETHER_HDR_LEN)

KNI control path is not supported with the PMD, since there is no physical
backend device by default.


PMD arguments
-------------

``no_request_thread``, by default PMD creates a pthread for each KNI interface
to handle Linux network interface control commands, like ``ifconfig kni0 up``

With ``no_request_thread`` option, pthread is not created and control commands
not handled by PMD.

By default request thread is enabled. And this argument should not be used
most of the time, unless this PMD used with customized DPDK application to handle
requests itself.

Argument usage::

        testpmd --vdev "net_kni0,no_request_thread=1" -- -i


PMD log messages
----------------

If KNI kernel module (rte_kni.ko) not inserted, following error log printed::

        "KNI: KNI subsystem has not been initialized. Invoke rte_kni_init() first"


PMD testing
-----------

It is possible to test PMD quickly using KNI kernel module loopback feature:

* Insert KNI kernel module with loopback support:

    .. code-block:: console

        insmod build/kmod/rte_kni.ko lo_mode=lo_mode_fifo_skb

* Start testpmd with no physical device but two KNI virtual devices:

    .. code-block:: console

        ./testpmd --vdev net_kni0 --vdev net_kni1 -- -i

    .. code-block:: console

        ...
        Configuring Port 0 (socket 0)
        KNI: pci: 00:00:00       c580:b8
        Port 0: 1A:4A:5B:7C:A2:8C
        Configuring Port 1 (socket 0)
        KNI: pci: 00:00:00       600:b9
        Port 1: AE:95:21:07:93:DD
        Checking link statuses...
        Port 0 Link Up - speed 10000 Mbps - full-duplex
        Port 1 Link Up - speed 10000 Mbps - full-duplex
        Done
        testpmd>

* Observe Linux interfaces

    .. code-block:: console

        $ ifconfig kni0 && ifconfig kni1
        kni0: flags=4098<BROADCAST,MULTICAST>  mtu 1500
                ether ae:8e:79:8e:9b:c8  txqueuelen 1000  (Ethernet)
                RX packets 0  bytes 0 (0.0 B)
                RX errors 0  dropped 0  overruns 0  frame 0
                TX packets 0  bytes 0 (0.0 B)
                TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

        kni1: flags=4098<BROADCAST,MULTICAST>  mtu 1500
                ether 9e:76:43:53:3e:9b  txqueuelen 1000  (Ethernet)
                RX packets 0  bytes 0 (0.0 B)
                RX errors 0  dropped 0  overruns 0  frame 0
                TX packets 0  bytes 0 (0.0 B)
                TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0


* Start forwarding with tx_first:

    .. code-block:: console

        testpmd> start tx_first

* Quit and check forwarding stats:

    .. code-block:: console

        testpmd> quit
        Telling cores to stop...
        Waiting for lcores to finish...

        ---------------------- Forward statistics for port 0  ----------------------
        RX-packets: 35637905       RX-dropped: 0             RX-total: 35637905
        TX-packets: 35637947       TX-dropped: 0             TX-total: 35637947
        ----------------------------------------------------------------------------

        ---------------------- Forward statistics for port 1  ----------------------
        RX-packets: 35637915       RX-dropped: 0             RX-total: 35637915
        TX-packets: 35637937       TX-dropped: 0             TX-total: 35637937
        ----------------------------------------------------------------------------

        +++++++++++++++ Accumulated forward statistics for all ports+++++++++++++++
        RX-packets: 71275820       RX-dropped: 0             RX-total: 71275820
        TX-packets: 71275884       TX-dropped: 0             TX-total: 71275884
        ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Commit	Line	Data
11fdf7f2 TL	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
9f95a23c	58	mbuf size: (rte_pktmbuf_data_room_size(pktmbuf_pool) - RTE_PKTMBUF_HEADROOM)
f67539c2	59	mtu: (conf.mbuf_size - RTE_ETHER_HDR_LEN)
11fdf7f2 TL	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
9f95a23c	68	``no_request_thread``, by default PMD creates a pthread for each KNI interface
11fdf7f2 TL	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	++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++