1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2017 Intel Corporation.
4 Eventdev Pipeline Sample Application
5 ====================================
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.
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.
18 Compiling the Application
19 -------------------------
21 To compile the sample application see :doc:`compiling`.
23 The application is located in the ``examples`` sub-directory.
27 Running the Application
28 -----------------------
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
34 An example eventdev pipeline running with the software eventdev PMD using
35 these settings is shown below:
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
47 .. code-block:: console
49 ./<build_dir>/examples/dpdk-eventdev_pipeline --vdev event_sw0 -- -r1 -t1 /
50 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D
52 The 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
54 will print an error message:
56 .. code-block:: console
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):
63 Configuration of the eventdev is covered in detail in the programmers guide,
64 see the Event Device Library section.
67 Observing the Application
68 -------------------------
70 At runtime the eventdev pipeline application prints out a summary of the
71 configuration, and some runtime statistics like packets per second. On exit the
72 worker statistics are printed, along with a full dump of the PMD statistics if
73 required. The following sections show sample output for each of the output
79 This provides an overview of the pipeline,
80 scheduling type at each stage, and parameters to options such as how many
81 flows to use and what eventdev PMD is in use. See the following sample output
84 .. code-block:: console
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
105 At runtime, the statistics of the consumer are printed, stating the number of
106 packets received, runtime in milliseconds, average mpps, and current mpps.
108 .. code-block:: console
110 # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
115 At shutdown, the application prints the number of packets received and
116 transmitted, and an overview of the distribution of work across worker cores.
118 .. code-block:: console
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
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)
142 To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to
143 this application. When the app is terminated using ``Ctrl+C``, the
144 ``rte_event_dev_dump()`` function is called, resulting in a dump of the
145 statistics that the PMD provides. The statistics provided depend on the PMD
146 used, see the Event Device Drivers section for a list of eventdev PMDs.