1 2.. BSD LICENSE 3 Copyright(c) 2017 Intel Corporation. All rights reserved. 4 All rights reserved. 5 6 Redistribution and use in source and binary forms, with or without 7 modification, are permitted provided that the following conditions 8 are met: 9 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 15 distribution. 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. 19 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. 31 32Eventdev Pipeline Sample Application 33==================================== 34 35The eventdev pipeline sample application is a sample app that demonstrates 36the usage of the eventdev API using the software PMD. It shows how an 37application can configure a pipeline and assign a set of worker cores to 38perform the processing required. 39 40The application has a range of command line arguments allowing it to be 41configured for various numbers worker cores, stages,queue depths and cycles per 42stage of work. This is useful for performance testing as well as quickly testing 43a particular pipeline configuration. 44 45 46Compiling the Application 47------------------------- 48 49To compile the sample application see :doc:`compiling`. 50 51The application is located in the ``examples`` sub-directory. 52 53 54 55Running the Application 56----------------------- 57 58The application has a lot of command line options. This allows specification of 59the eventdev PMD to use, and a number of attributes of the processing pipeline 60options. 61 62An example eventdev pipeline running with the software eventdev PMD using 63these settings is shown below: 64 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 74 75.. code-block:: console 76 77 ./build/eventdev_pipeline --vdev event_sw0 -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D 78 79The 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 81will print an error message: 82 83.. code-block:: console 84 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): 87 rx: 0 88 tx: 1 89 90Configuration of the eventdev is covered in detail in the programmers guide, 91see the Event Device Library section. 92 93 94Observing the Application 95------------------------- 96 97At runtime the eventdev pipeline application prints out a summary of the 98configuration, and some runtime statistics like packets per second. On exit the 99worker statistics are printed, along with a full dump of the PMD statistics if 100required. The following sections show sample output for each of the output 101types. 102 103Configuration 104~~~~~~~~~~~~~ 105 106This provides an overview of the pipeline, 107scheduling type at each stage, and parameters to options such as how many 108flows to use and what eventdev PMD is in use. See the following sample output 109for details: 110 111.. code-block:: console 112 113 Config: 114 ports: 2 115 workers: 8 116 packets: 0 117 priorities: 1 118 Queue-prio: 0 119 qid0 type: atomic 120 Cores available: 44 121 Cores used: 10 122 Eventdev 0: event_sw 123 Stages: 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 128 129Runtime 130~~~~~~~ 131 132At runtime, the statistics of the consumer are printed, stating the number of 133packets received, runtime in milliseconds, average mpps, and current mpps. 134 135.. code-block:: console 136 137 # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps] 138 139Shutdown 140~~~~~~~~ 141 142At shutdown, the application prints the number of packets received and 143transmitted, and an overview of the distribution of work across worker cores. 144 145.. code-block:: console 146 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 158 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) 168 169To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to 170this application. When the app is terminated using ``Ctrl+C``, the 171``rte_event_dev_dump()`` function is called, resulting in a dump of the 172statistics that the PMD provides. The statistics provided depend on the PMD 173used, see the Event Device Drivers section for a list of eventdev PMDs. 174