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