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_dir>/examples/dpdk-eventdev_pipeline --vdev event_sw0 -- -r1 -t1 / 50 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D 51 52The application has some sanity checking built-in, so if there is a function 53(e.g.; the RX core) which doesn't have a cpu core mask assigned, the application 54will print an error message: 55 56.. code-block:: console 57 58 Core part of pipeline was not assigned any cores. This will stall the 59 pipeline, please check core masks (use -h for details on setting core masks): 60 rx: 0 61 tx: 1 62 63Configuration of the eventdev is covered in detail in the programmers guide, 64see the Event Device Library section. 65 66 67Observing the Application 68------------------------- 69 70At runtime the eventdev pipeline application prints out a summary of the 71configuration, and some runtime statistics like packets per second. On exit the 72worker statistics are printed, along with a full dump of the PMD statistics if 73required. The following sections show sample output for each of the output 74types. 75 76Configuration 77~~~~~~~~~~~~~ 78 79This provides an overview of the pipeline, 80scheduling type at each stage, and parameters to options such as how many 81flows to use and what eventdev PMD is in use. See the following sample output 82for details: 83 84.. code-block:: console 85 86 Config: 87 ports: 2 88 workers: 8 89 packets: 0 90 priorities: 1 91 Queue-prio: 0 92 qid0 type: atomic 93 Cores available: 44 94 Cores used: 10 95 Eventdev 0: event_sw 96 Stages: 97 Stage 0, Type Atomic Priority = 128 98 Stage 1, Type Atomic Priority = 128 99 Stage 2, Type Atomic Priority = 128 100 Stage 3, Type Atomic Priority = 128 101 102Runtime 103~~~~~~~ 104 105At runtime, the statistics of the consumer are printed, stating the number of 106packets received, runtime in milliseconds, average mpps, and current mpps. 107 108.. code-block:: console 109 110 # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps] 111 112Shutdown 113~~~~~~~~ 114 115At shutdown, the application prints the number of packets received and 116transmitted, and an overview of the distribution of work across worker cores. 117 118.. code-block:: console 119 120 Signal 2 received, preparing to exit... 121 worker 12 thread done. RX=4966581 TX=4966581 122 worker 13 thread done. RX=4963329 TX=4963329 123 worker 14 thread done. RX=4953614 TX=4953614 124 worker 0 thread done. RX=0 TX=0 125 worker 11 thread done. RX=4970549 TX=4970549 126 worker 10 thread done. RX=4986391 TX=4986391 127 worker 9 thread done. RX=4970528 TX=4970528 128 worker 15 thread done. RX=4974087 TX=4974087 129 worker 8 thread done. RX=4979908 TX=4979908 130 worker 2 thread done. RX=0 TX=0 131 132 Port Workload distribution: 133 worker 0 : 12.5 % (4979876 pkts) 134 worker 1 : 12.5 % (4970497 pkts) 135 worker 2 : 12.5 % (4986359 pkts) 136 worker 3 : 12.5 % (4970517 pkts) 137 worker 4 : 12.5 % (4966566 pkts) 138 worker 5 : 12.5 % (4963297 pkts) 139 worker 6 : 12.5 % (4953598 pkts) 140 worker 7 : 12.5 % (4974055 pkts) 141 142To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to 143this application. When the app is terminated using ``Ctrl+C``, the 144``rte_event_dev_dump()`` function is called, resulting in a dump of the 145statistics that the PMD provides. The statistics provided depend on the PMD 146used, see the Event Device Drivers section for a list of eventdev PMDs. 147