doc/guides/sample_app_ug/dist_app.rst

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