3 Copyright(c) 2017 Intel Corporation. All rights reserved.
6 Redistribution and use in source and binary forms, with or without
7 modification, are permitted provided that the following conditions
10 * Redistributions of source code must retain the above copyright
11 notice, this list of conditions and the following disclaimer.
12 * Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in
14 the documentation and/or other materials provided with the
16 * Neither the name of Intel Corporation nor the names of its
17 contributors may be used to endorse or promote products derived
18 from this software without specific prior written permission.
20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 Eventdev Pipeline Sample Application
33 ====================================
35 The eventdev pipeline sample application is a sample app that demonstrates
36 the usage of the eventdev API using the software PMD. It shows how an
37 application can configure a pipeline and assign a set of worker cores to
38 perform the processing required.
40 The application has a range of command line arguments allowing it to be
41 configured for various numbers worker cores, stages,queue depths and cycles per
42 stage of work. This is useful for performance testing as well as quickly testing
43 a particular pipeline configuration.
46 Compiling the Application
47 -------------------------
49 To compile the sample application see :doc:`compiling`.
51 The application is located in the ``examples`` sub-directory.
55 Running the Application
56 -----------------------
58 The application has a lot of command line options. This allows specification of
59 the eventdev PMD to use, and a number of attributes of the processing pipeline
62 An example eventdev pipeline running with the software eventdev PMD using
63 these settings is shown below:
65 * ``-r1``: core mask 0x1 for RX
66 * ``-t1``: core mask 0x1 for TX
67 * ``-e4``: core mask 0x4 for the software scheduler
68 * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th
69 * ``-s4``: 4 atomic stages
70 * ``-n0``: process infinite packets (run forever)
71 * ``-c32``: worker dequeue depth of 32
72 * ``-W1000``: do 1000 cycles of work per packet in each stage
73 * ``-D``: dump statistics on exit
75 .. code-block:: console
77 ./build/eventdev_pipeline --vdev event_sw0 -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D
79 The application has some sanity checking built-in, so if there is a function
80 (eg; the RX core) which doesn't have a cpu core mask assigned, the application
81 will print an error message:
83 .. code-block:: console
85 Core part of pipeline was not assigned any cores. This will stall the
86 pipeline, please check core masks (use -h for details on setting core masks):
90 Configuration of the eventdev is covered in detail in the programmers guide,
91 see the Event Device Library section.
94 Observing the Application
95 -------------------------
97 At runtime the eventdev pipeline application prints out a summary of the
98 configuration, and some runtime statistics like packets per second. On exit the
99 worker statistics are printed, along with a full dump of the PMD statistics if
100 required. The following sections show sample output for each of the output
106 This provides an overview of the pipeline,
107 scheduling type at each stage, and parameters to options such as how many
108 flows to use and what eventdev PMD is in use. See the following sample output
111 .. code-block:: console
124 Stage 0, Type Atomic Priority = 128
125 Stage 1, Type Atomic Priority = 128
126 Stage 2, Type Atomic Priority = 128
127 Stage 3, Type Atomic Priority = 128
132 At runtime, the statistics of the consumer are printed, stating the number of
133 packets received, runtime in milliseconds, average mpps, and current mpps.
135 .. code-block:: console
137 # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
142 At shutdown, the application prints the number of packets received and
143 transmitted, and an overview of the distribution of work across worker cores.
145 .. code-block:: console
147 Signal 2 received, preparing to exit...
148 worker 12 thread done. RX=4966581 TX=4966581
149 worker 13 thread done. RX=4963329 TX=4963329
150 worker 14 thread done. RX=4953614 TX=4953614
151 worker 0 thread done. RX=0 TX=0
152 worker 11 thread done. RX=4970549 TX=4970549
153 worker 10 thread done. RX=4986391 TX=4986391
154 worker 9 thread done. RX=4970528 TX=4970528
155 worker 15 thread done. RX=4974087 TX=4974087
156 worker 8 thread done. RX=4979908 TX=4979908
157 worker 2 thread done. RX=0 TX=0
159 Port Workload distribution:
160 worker 0 : 12.5 % (4979876 pkts)
161 worker 1 : 12.5 % (4970497 pkts)
162 worker 2 : 12.5 % (4986359 pkts)
163 worker 3 : 12.5 % (4970517 pkts)
164 worker 4 : 12.5 % (4966566 pkts)
165 worker 5 : 12.5 % (4963297 pkts)
166 worker 6 : 12.5 % (4953598 pkts)
167 worker 7 : 12.5 % (4974055 pkts)
169 To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to
170 this application. When the app is terminated using ``Ctrl+C``, the
171 ``rte_event_dev_dump()`` function is called, resulting in a dump of the
172 statistics that the PMD provides. The statistics provided depend on the PMD
173 used, see the Event Device Drivers section for a list of eventdev PMDs.