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