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