1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2020 Intel Corporation. 3 4VMDq Forwarding Sample Application 5========================================== 6 7The VMDq Forwarding sample application is a simple example of packet processing using the DPDK. 8The application performs L2 forwarding using VMDq to divide the incoming traffic into queues. 9The traffic splitting is performed in hardware by the VMDq feature of the Intel® 82599 and X710/XL710 Ethernet Controllers. 10 11Overview 12-------- 13 14This sample application can be used as a starting point for developing a new application that is based on the DPDK and 15uses VMDq for traffic partitioning. 16 17VMDq filters split the incoming packets up into different "pools" - each with its own set of RX queues - based upon 18the MAC address and VLAN ID within the VLAN tag of the packet. 19 20All traffic is read from a single incoming port and output on another port, without any processing being performed. 21With Intel® 82599 NIC, for example, the traffic is split into 128 queues on input, where each thread of the application reads from 22multiple queues. When run with 8 threads, that is, with the -c FF option, each thread receives and forwards packets from 16 queues. 23 24As supplied, the sample application configures the VMDq feature to have 32 pools with 4 queues each. 25The Intel® 82599 10 Gigabit Ethernet Controller NIC also supports the splitting of traffic into 16 pools of 2 queues. 26While the Intel® X710 or XL710 Ethernet Controller NICs support many configurations of VMDq pools of 4 or 8 queues each. 27And queues numbers for each VMDq pool can be changed by setting RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM 28in config/rte_config.h file. 29The nb-pools and enable-rss parameters can be passed on the command line, after the EAL parameters: 30 31.. code-block:: console 32 33 ./<build_dir>/examples/dpdk-vmdq [EAL options] -- -p PORTMASK --nb-pools NP --enable-rss 34 35where, NP can be 8, 16 or 32, rss is disabled by default. 36 37In Linux* user space, the application can display statistics with the number of packets received on each queue. 38To have the application display the statistics, send a SIGHUP signal to the running application process. 39 40The VMDq Forwarding sample application is in many ways simpler than the L2 Forwarding application 41(see :doc:`l2_forward_real_virtual`) 42as it performs unidirectional L2 forwarding of packets from one port to a second port. 43No command-line options are taken by this application apart from the standard EAL command-line options. 44 45Compiling the Application 46------------------------- 47 48To compile the sample application see :doc:`compiling`. 49 50The application is located in the ``vmdq`` sub-directory. 51 52Running the Application 53----------------------- 54 55To run the example in a Linux environment: 56 57.. code-block:: console 58 59 user@target:~$ ./<build_dir>/examples/dpdk-vmdq -l 0-3 -n 4 -- -p 0x3 --nb-pools 16 60 61Refer to the *DPDK Getting Started Guide* for general information on running applications and 62the Environment Abstraction Layer (EAL) options. 63 64Explanation 65----------- 66 67The following sections provide some explanation of the code. 68 69Initialization 70~~~~~~~~~~~~~~ 71 72The EAL, driver and PCI configuration is performed largely as in the L2 Forwarding sample application, 73as is the creation of the mbuf pool. 74See :doc:`l2_forward_real_virtual`. 75Where this example application differs is in the configuration of the NIC port for RX. 76 77The VMDq hardware feature is configured at port initialization time by setting the appropriate values in the 78rte_eth_conf structure passed to the rte_eth_dev_configure() API. 79Initially in the application, 80a default structure is provided for VMDq configuration to be filled in later by the application. 81 82.. literalinclude:: ../../../examples/vmdq/main.c 83 :language: c 84 :start-after: Default structure for VMDq. 8< 85 :end-before: >8 End of Empty vdmq configuration structure. 86 87The get_eth_conf() function fills in an rte_eth_conf structure with the appropriate values, 88based on the global vlan_tags array. 89For the VLAN IDs, each one can be allocated to possibly multiple pools of queues. 90For destination MAC, each VMDq pool will be assigned with a MAC address. In this sample, each VMDq pool 91is assigned to the MAC like 52:54:00:12:<port_id>:<pool_id>, that is, 92the MAC of VMDq pool 2 on port 1 is 52:54:00:12:01:02. 93 94.. literalinclude:: ../../../examples/vmdq/main.c 95 :language: c 96 :start-after: vlan_tags 8< 97 :end-before: >8 End of vlan_tags. 98 99.. literalinclude:: ../../../examples/vmdq/main.c 100 :language: c 101 :start-after: Pool mac address template. 8< 102 :end-before: >8 End of mac addr template. 103 104.. literalinclude:: ../../../examples/vmdq/main.c 105 :language: c 106 :start-after: Building correct configuration for vdmq. 8< 107 :end-before: >8 End of get_eth_conf. 108 109Once the network port has been initialized using the correct VMDq values, 110the initialization of the port's RX and TX hardware rings is performed similarly to that 111in the L2 Forwarding sample application. 112See :doc:`l2_forward_real_virtual` for more information. 113 114Statistics Display 115~~~~~~~~~~~~~~~~~~ 116 117When run in a Linux environment, 118the VMDq Forwarding sample application can display statistics showing the number of packets read from each RX queue. 119This is provided by way of a signal handler for the SIGHUP signal, 120which simply prints to standard output the packet counts in grid form. 121Each row of the output is a single pool with the columns being the queue number within that pool. 122 123To generate the statistics output, use the following command: 124 125.. code-block:: console 126 127 user@host$ sudo killall -HUP vmdq_app 128 129Please note that the statistics output will appear on the terminal where the vmdq_app is running, 130rather than the terminal from which the HUP signal was sent. 131