1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Distributor Sample Application 5============================== 6 7The distributor sample application is a simple example of packet distribution 8to cores using the Data Plane Development Kit (DPDK). It also makes use of 9Intel Speed Select Technology - Base Frequency (Intel SST-BF) to pin the 10distributor to the higher frequency core if available. 11 12Overview 13-------- 14 15The distributor application performs the distribution of packets that are received 16on an RX_PORT to different cores. When processed by the cores, the destination 17port of a packet is the port from the enabled port mask adjacent to the one on 18which the packet was received, that is, if the first four ports are enabled 19(port mask 0xf), ports 0 and 1 RX/TX into each other, and ports 2 and 3 RX/TX 20into each other. 21 22This application can be used to benchmark performance using the traffic 23generator as shown in the figure below. 24 25.. _figure_dist_perf: 26 27.. figure:: img/dist_perf.* 28 29 Performance Benchmarking Setup (Basic Environment) 30 31Compiling the Application 32------------------------- 33 34To compile the sample application see :doc:`compiling`. 35 36The application is located in the ``distributor`` sub-directory. 37 38Running the Application 39----------------------- 40 41#. The application has a number of command line options: 42 43 .. code-block:: console 44 45 ./<build-dir>/examples/dpdk-distributor [EAL options] -- -p PORTMASK 46 47 where, 48 49 * -p PORTMASK: Hexadecimal bitmask of ports to configure 50 51#. To run the application in linux environment with 10 lcores, 4 ports, 52 issue the command: 53 54 .. code-block:: console 55 56 $ ./<build-dir>/examples/dpdk-distributor -l 1-9,22 -n 4 -- -p f 57 58#. Refer to the DPDK Getting Started Guide for general information on running 59 applications and the Environment Abstraction Layer (EAL) options. 60 61Explanation 62----------- 63 64The distributor application consists of four types of threads: a receive 65thread (``lcore_rx()``), a distributor thread (``lcore_dist()``), a set of 66worker threads (``lcore_worker()``), and a transmit thread(``lcore_tx()``). 67How these threads work together is shown in :numref:`figure_dist_app` below. 68The ``main()`` function launches threads of these four types. Each thread 69has a while loop which will be doing processing and which is terminated 70only upon SIGINT or ctrl+C. 71 72The receive thread receives the packets using ``rte_eth_rx_burst()`` and will 73enqueue them to an rte_ring. The distributor thread will dequeue the packets 74from the ring and assign them to workers (using ``rte_distributor_process()`` API). 75This assignment is based on the tag (or flow ID) of the packet - indicated by 76the hash field in the mbuf. For IP traffic, this field is automatically filled 77by the NIC with the "usr" hash value for the packet, which works as a per-flow 78tag. The distributor thread communicates with the worker threads using a 79cache-line swapping mechanism, passing up to 8 mbuf pointers at a time 80(one cache line) to each worker. 81 82More than one worker thread can exist as part of the application, and these 83worker threads do simple packet processing by requesting packets from 84the distributor, doing a simple XOR operation on the input port mbuf field 85(to indicate the output port which will be used later for packet transmission) 86and then finally returning the packets back to the distributor thread. 87 88The distributor thread will then call the distributor api 89``rte_distributor_returned_pkts()`` to get the processed packets, and will enqueue 90them to another rte_ring for transfer to the TX thread for transmission on the 91output port. The transmit thread will dequeue the packets from the ring and 92transmit them on the output port specified in packet mbuf. 93 94Users who wish to terminate the running of the application have to press ctrl+C 95(or send SIGINT to the app). Upon this signal, a signal handler provided 96in the application will terminate all running threads gracefully and print 97final statistics to the user. 98 99.. _figure_dist_app: 100 101.. figure:: img/dist_app.* 102 103 Distributor Sample Application Layout 104 105 106Intel SST-BF Support 107-------------------- 108 109In DPDK 19.05, support was added to the power management library for 110Intel-SST-BF, a technology that allows some cores to run at a higher 111frequency than others. An application note for Intel SST-BF is available, 112and is entitled 113`Intel Speed Select Technology – Base Frequency - Enhancing Performance <https://builders.intel.com/docs/networkbuilders/intel-speed-select-technology-base-frequency-enhancing-performance.pdf>`_ 114 115The distributor application was also enhanced to be aware of these higher 116frequency SST-BF cores, and when starting the application, if high frequency 117SST-BF cores are present in the core mask, the application will identify these 118cores and pin the workloads appropriately. The distributor core is usually 119the bottleneck, so this is given first choice of the high frequency SST-BF 120cores, followed by the rx core and the tx core. 121 122Debug Logging Support 123--------------------- 124 125Debug logging is provided as part of the application; the user needs to uncomment 126the line "#define DEBUG" defined in start of the application in main.c to enable debug logs. 127 128Statistics 129---------- 130 131The main function will print statistics on the console every second. These 132statistics include the number of packets enqueued and dequeued at each stage 133in the application, and also key statistics per worker, including how many 134packets of each burst size (1-8) were sent to each worker thread. 135 136Application Initialization 137-------------------------- 138 139Command line parsing is done in the same way as it is done in the L2 Forwarding Sample 140Application. See :ref:`l2_fwd_app_cmd_arguments`. 141 142Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding 143Sample Application. See :ref:`l2_fwd_app_mbuf_init`. 144 145Driver Initialization is done in same way as it is done in the L2 Forwarding Sample 146Application. See :ref:`l2_fwd_app_dvr_init`. 147 148RX queue initialization is done in the same way as it is done in the L2 Forwarding 149Sample Application. See :ref:`l2_fwd_app_rx_init`. 150 151TX queue initialization is done in the same way as it is done in the L2 Forwarding 152Sample Application. See :ref:`l2_fwd_app_tx_init`. 153