-.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation.
Kernel NIC Interface Sample Application
=======================================
Kernel NIC Application Packet Flow
-
Compiling the Application
-------------------------
-Compile the application as follows:
-
-#. Go to the example directory:
-
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk cd
- ${RTE_SDK}/examples/kni
+To compile the sample application see :doc:`compiling`.
-#. Set the target (a default target is used if not specified)
+The application is located in the ``kni`` sub-directory.
- .. note::
+.. note::
This application is intended as a linuxapp only.
- .. code-block:: console
-
- export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-#. Build the application:
-
- .. code-block:: console
-
- make
-
Loading the Kernel Module
-------------------------
Refer to *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options.
-The -c coremask parameter of the EAL options should include the lcores indicated by the lcore_rx and lcore_tx,
+The -c coremask or -l corelist parameter of the EAL options should include the lcores indicated by the lcore_rx and lcore_tx,
but does not need to include lcores indicated by lcore_kthread as they are used to pin the kernel thread on.
The -p PORTMASK parameter should include the ports indicated by the port in --config, neither more nor less.
.. code-block:: console
- ./build/kni -c 0xf0 -n 4 -- -P -p 0x3 -config="(0,4,6,8),(1,5,7,9)"
+ ./build/kni -l 4-7 -n 4 -- -P -p 0x3 --config="(0,4,6,8),(1,5,7,9)"
KNI Operations
--------------
#tcpdump -i vEth0_0
+Change the MAC address:
+
+.. code-block:: console
+
+ #ifconfig vEth0_0 hw ether 0C:01:02:03:04:08
+
When the DPDK userspace application is closed, all the KNI devices are deleted from Linux*.
Explanation
Initialization
~~~~~~~~~~~~~~
-Setup of mbuf pool, driver and queues is similar to the setup done in the L2 Forwarding sample application
-(see Chapter 9 "L2 Forwarding Sample Application (in Real and Virtualized Environments" for details).
+Setup of mbuf pool, driver and queues is similar to the setup done in the :doc:`l2_forward_real_virtual`..
In addition, one or more kernel NIC interfaces are allocated for each
of the configured ports according to the command line parameters.
.. code-block:: c
static int
- kni_alloc(uint8_t port_id)
+ kni_alloc(uint16_t port_id)
{
uint8_t i;
struct rte_kni *kni;
memset(&conf, 0, sizeof(conf));
if (params[port_id]->nb_lcore_k) {
- rte_snprintf(conf.name, RTE_KNI_NAMESIZE, "vEth%u_%u", port_id, i);
+ snprintf(conf.name, RTE_KNI_NAMESIZE, "vEth%u_%u", port_id, i);
conf.core_id = params[port_id]->lcore_k[i];
conf.force_bind = 1;
} else
- rte_snprintf(conf.name, RTE_KNI_NAMESIZE, "vEth%u", port_id);
+ snprintf(conf.name, RTE_KNI_NAMESIZE, "vEth%u", port_id);
conf.group_id = (uint16_t)port_id;
conf.mbuf_size = MAX_PACKET_SZ;
conf.addr = dev_info.pci_dev->addr;
conf.id = dev_info.pci_dev->id;
+ /* Get the interface default mac address */
+ rte_eth_macaddr_get(port_id, (struct ether_addr *)&conf.mac_addr);
+
memset(&ops, 0, sizeof(ops));
ops.port_id = port_id;
ops.change_mtu = kni_change_mtu;
ops.config_network_if = kni_config_network_interface;
+ ops.config_mac_address = kni_config_mac_address;
kni = rte_kni_alloc(pktmbuf_pool, &conf, &ops);
} else
int i, j, nb_token;
char *str_fld[_NUM_FLD];
unsigned long int_fld[_NUM_FLD];
- uint8_t port_id, nb_kni_port_params = 0;
+ uint16_t port_id, nb_kni_port_params = 0;
memset(&kni_port_params_array, 0, sizeof(kni_port_params_array));
goto fail;
}
- rte_snprintf(s, sizeof(s), "%.*s", size, p);
+ snprintf(s, sizeof(s), "%.*s", size, p);
nb_token = rte_strsplit(s, sizeof(s), str_fld, _NUM_FLD, ',');
if (nb_token <= FLD_LCORE_TX) {
For the case that reads from a NIC port and writes to the kernel NIC interfaces,
the packet reception is the same as in L2 Forwarding sample application
-(see Section 9.4.6 "Receive, Process and Transmit Packets").
+(see :ref:`l2_fwd_app_rx_tx_packets`).
The packet transmission is done by sending mbufs into the kernel NIC interfaces by rte_kni_tx_burst().
The KNI library automatically frees the mbufs after the kernel successfully copied the mbufs.
For the other case that reads from kernel NIC interfaces and writes to a physical NIC port, packets are retrieved by reading
mbufs from kernel NIC interfaces by `rte_kni_rx_burst()`.
The packet transmission is the same as in the L2 Forwarding sample application
-(see Section 9.4.6 "Receive, Process and Transmit Packet's").
+(see :ref:`l2_fwd_app_rx_tx_packets`).
.. code-block:: c
To execute specific PMD operations in user space requested by some Linux* commands,
callbacks must be implemented and filled in the struct rte_kni_ops structure.
-Currently, setting a new MTU and configuring the network interface (up/ down) are supported.
+Currently, setting a new MTU, change in MAC address, configuring promiscusous mode and
+configuring the network interface(up/down) re supported.
+Default implementation for following is available in rte_kni library.
+Application may choose to not implement following callbacks:
+
+- ``config_mac_address``
+- ``config_promiscusity``
+
.. code-block:: c
static struct rte_kni_ops kni_ops = {
.change_mtu = kni_change_mtu,
.config_network_if = kni_config_network_interface,
+ .config_mac_address = kni_config_mac_address,
+ .config_promiscusity = kni_config_promiscusity,
};
/* Callback for request of changing MTU */
static int
- kni_change_mtu(uint8_t port_id, unsigned new_mtu)
+ kni_change_mtu(uint16_t port_id, unsigned new_mtu)
{
int ret;
struct rte_eth_conf conf;
- if (port_id >= rte_eth_dev_count()) {
- RTE_LOG(ERR, APP, "Invalid port id %d\n", port_id);
- return -EINVAL;
- }
-
RTE_LOG(INFO, APP, "Change MTU of port %d to %u\n", port_id, new_mtu);
/* Stop specific port */
/* Callback for request of configuring network interface up/down */
static int
- kni_config_network_interface(uint8_t port_id, uint8_t if_up)
+ kni_config_network_interface(uint16_t port_id, uint8_t if_up)
{
int ret = 0;
- if (port_id >= rte_eth_dev_count() || port_id >= RTE_MAX_ETHPORTS) {
- RTE_LOG(ERR, APP, "Invalid port id %d\n", port_id);
- return -EINVAL;
- }
-
RTE_LOG(INFO, APP, "Configure network interface of %d %s\n",
port_id, if_up ? "up" : "down");
RTE_LOG(ERR, APP, "Failed to start port %d\n", port_id);
return ret;
}
+
+ /* Callback for request of configuring device mac address */
+
+ static int
+ kni_config_mac_address(uint16_t port_id, uint8_t mac_addr[])
+ {
+ .....
+ }
+
+ /* Callback for request of configuring promiscuous mode */
+
+ static int
+ kni_config_promiscusity(uint16_t port_id, uint8_t to_on)
+ {
+ .....
+ }