doc/guides/sample_app_ug/eventdev_pipeline.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Eventdev Pipeline Sample Application
   5 ====================================
   6
   7 The eventdev pipeline sample application is a sample app that demonstrates
   8 the usage of the eventdev API using the software PMD. It shows how an
   9 application can configure a pipeline and assign a set of worker cores to
  10 perform the processing required.
  11
  12 The application has a range of command line arguments allowing it to be
  13 configured for various numbers worker cores, stages,queue depths and cycles per
  14 stage of work. This is useful for performance testing as well as quickly testing
  15 a particular pipeline configuration.
  16
  17
  18 Compiling the Application
  19 -------------------------
  20
  21 To compile the sample application see :doc:`compiling`.
  22
  23 The application is located in the ``examples`` sub-directory.
  24
  25
  26
  27 Running the Application
  28 -----------------------
  29
  30 The application has a lot of command line options. This allows specification of
  31 the eventdev PMD to use, and a number of attributes of the processing pipeline
  32 options.
  33
  34 An example eventdev pipeline running with the software eventdev PMD using
  35 these settings is shown below:
  36
  37  * ``-l 0,2,8-15``: lcore to use
  38  * ``-r1``: core mask 0x1 for RX
  39  * ``-t1``: core mask 0x1 for TX
  40  * ``-e4``: core mask 0x4 for the software scheduler
  41  * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th
  42  * ``-s4``: 4 atomic stages
  43  * ``-n0``: process infinite packets (run forever)
  44  * ``-c32``: worker dequeue depth of 32
  45  * ``-W1000``: do 1000 cycles of work per packet in each stage
  46  * ``-D``: dump statistics on exit
  47
  48 .. code-block:: console
  49
  50     ./<build_dir>/examples/dpdk-eventdev_pipeline -l 0,2,8-15 --vdev event_sw0 \
  51     -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D
  52
  53 The application has some sanity checking built-in, so if there is a function
  54 (e.g.; the RX core) which doesn't have a cpu core mask assigned, the application
  55 will print an error message:
  56
  57 .. code-block:: console
  58
  59   Core part of pipeline was not assigned any cores. This will stall the
  60   pipeline, please check core masks (use -h for details on setting core masks):
  61           rx: 0
  62           tx: 1
  63
  64 Configuration of the eventdev is covered in detail in the programmers guide,
  65 see the Event Device Library section.
  66
  67
  68 Observing the Application
  69 -------------------------
  70
  71 At runtime the eventdev pipeline application prints out a summary of the
  72 configuration, and some runtime statistics like packets per second. On exit the
  73 worker statistics are printed, along with a full dump of the PMD statistics if
  74 required. The following sections show sample output for each of the output
  75 types.
  76
  77 Configuration
  78 ~~~~~~~~~~~~~
  79
  80 This provides an overview of the pipeline,
  81 scheduling type at each stage, and parameters to options such as how many
  82 flows to use and what eventdev PMD is in use. See the following sample output
  83 for details:
  84
  85 .. code-block:: console
  86
  87   Config:
  88         ports: 2
  89         workers: 8
  90         packets: 0
  91         priorities: 1
  92         Queue-prio: 0
  93         qid0 type: atomic
  94         Cores available: 44
  95         Cores used: 10
  96         Eventdev 0: event_sw
  97   Stages:
  98         Stage 0, Type Atomic    Priority = 128
  99         Stage 1, Type Atomic    Priority = 128
 100         Stage 2, Type Atomic    Priority = 128
 101         Stage 3, Type Atomic    Priority = 128
 102
 103 Runtime
 104 ~~~~~~~
 105
 106 At runtime, the statistics of the consumer are printed, stating the number of
 107 packets received, runtime in milliseconds, average mpps, and current mpps.
 108
 109 .. code-block:: console
 110
 111   # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
 112
 113 Shutdown
 114 ~~~~~~~~
 115
 116 At shutdown, the application prints the number of packets received and
 117 transmitted, and an overview of the distribution of work across worker cores.
 118
 119 .. code-block:: console
 120
 121         Signal 2 received, preparing to exit...
 122           worker 12 thread done. RX=4966581 TX=4966581
 123           worker 13 thread done. RX=4963329 TX=4963329
 124           worker 14 thread done. RX=4953614 TX=4953614
 125           worker 0 thread done. RX=0 TX=0
 126           worker 11 thread done. RX=4970549 TX=4970549
 127           worker 10 thread done. RX=4986391 TX=4986391
 128           worker 9 thread done. RX=4970528 TX=4970528
 129           worker 15 thread done. RX=4974087 TX=4974087
 130           worker 8 thread done. RX=4979908 TX=4979908
 131           worker 2 thread done. RX=0 TX=0
 132
 133         Port Workload distribution:
 134         worker 0 :      12.5 % (4979876 pkts)
 135         worker 1 :      12.5 % (4970497 pkts)
 136         worker 2 :      12.5 % (4986359 pkts)
 137         worker 3 :      12.5 % (4970517 pkts)
 138         worker 4 :      12.5 % (4966566 pkts)
 139         worker 5 :      12.5 % (4963297 pkts)
 140         worker 6 :      12.5 % (4953598 pkts)
 141         worker 7 :      12.5 % (4974055 pkts)
 142
 143 To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to
 144 this application. When the app is terminated using ``Ctrl+C``, the
 145 ``rte_event_dev_dump()`` function is called, resulting in a dump of the
 146 statistics that the PMD provides. The statistics provided depend on the PMD
 147 used, see the Event Device Drivers section for a list of eventdev PMDs.