doc/guides/sample_app_ug/eventdev_pipeline_sw_pmd.rst

   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
  32 Eventdev Pipeline SW PMD Sample Application
  33 ===========================================
  34
  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.
  39
  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.
  44
  45
  46 Compiling the Application
  47 -------------------------
  48
  49 To compile the application:
  50
  51 #.  Go to the sample application directory:
  52
  53     .. code-block:: console
  54
  55         export RTE_SDK=/path/to/rte_sdk
  56         cd ${RTE_SDK}/examples/eventdev_pipeline_sw_pmd
  57
  58 #.  Set the target (a default target is used if not specified). For example:
  59
  60     .. code-block:: console
  61
  62         export RTE_TARGET=x86_64-native-linuxapp-gcc
  63
  64     See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
  65
  66 #.  Build the application:
  67
  68     .. code-block:: console
  69
  70         make
  71
  72 Running the Application
  73 -----------------------
  74
  75 The application has a lot of command line options. This allows specification of
  76 the eventdev PMD to use, and a number of attributes of the processing pipeline
  77 options.
  78
  79 An example eventdev pipeline running with the software eventdev PMD using
  80 these settings is shown below:
  81
  82  * ``-r1``: core mask 0x1 for RX
  83  * ``-t1``: core mask 0x1 for TX
  84  * ``-e4``: core mask 0x4 for the software scheduler
  85  * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th
  86  * ``-s4``: 4 atomic stages
  87  * ``-n0``: process infinite packets (run forever)
  88  * ``-c32``: worker dequeue depth of 32
  89  * ``-W1000``: do 1000 cycles of work per packet in each stage
  90  * ``-D``: dump statistics on exit
  91
  92 .. code-block:: console
  93
  94     ./build/eventdev_pipeline_sw_pmd --vdev event_sw0 -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D
  95
  96 The application has some sanity checking built-in, so if there is a function
  97 (eg; the RX core) which doesn't have a cpu core mask assigned, the application
  98 will print an error message:
  99
 100 .. code-block:: console
 101
 102   Core part of pipeline was not assigned any cores. This will stall the
 103   pipeline, please check core masks (use -h for details on setting core masks):
 104           rx: 0
 105           tx: 1
 106
 107 Configuration of the eventdev is covered in detail in the programmers guide,
 108 see the Event Device Library section.
 109
 110
 111 Observing the Application
 112 -------------------------
 113
 114 At runtime the eventdev pipeline application prints out a summary of the
 115 configuration, and some runtime statistics like packets per second. On exit the
 116 worker statistics are printed, along with a full dump of the PMD statistics if
 117 required. The following sections show sample output for each of the output
 118 types.
 119
 120 Configuration
 121 ~~~~~~~~~~~~~
 122
 123 This provides an overview of the pipeline,
 124 scheduling type at each stage, and parameters to options such as how many
 125 flows to use and what eventdev PMD is in use. See the following sample output
 126 for details:
 127
 128 .. code-block:: console
 129
 130   Config:
 131         ports: 2
 132         workers: 8
 133         packets: 0
 134         priorities: 1
 135         Queue-prio: 0
 136         qid0 type: atomic
 137         Cores available: 44
 138         Cores used: 10
 139         Eventdev 0: event_sw
 140   Stages:
 141         Stage 0, Type Atomic    Priority = 128
 142         Stage 1, Type Atomic    Priority = 128
 143         Stage 2, Type Atomic    Priority = 128
 144         Stage 3, Type Atomic    Priority = 128
 145
 146 Runtime
 147 ~~~~~~~
 148
 149 At runtime, the statistics of the consumer are printed, stating the number of
 150 packets received, runtime in milliseconds, average mpps, and current mpps.
 151
 152 .. code-block:: console
 153
 154   # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
 155
 156 Shutdown
 157 ~~~~~~~~
 158
 159 At shutdown, the application prints the number of packets received and
 160 transmitted, and an overview of the distribution of work across worker cores.
 161
 162 .. code-block:: console
 163
 164         Signal 2 received, preparing to exit...
 165           worker 12 thread done. RX=4966581 TX=4966581
 166           worker 13 thread done. RX=4963329 TX=4963329
 167           worker 14 thread done. RX=4953614 TX=4953614
 168           worker 0 thread done. RX=0 TX=0
 169           worker 11 thread done. RX=4970549 TX=4970549
 170           worker 10 thread done. RX=4986391 TX=4986391
 171           worker 9 thread done. RX=4970528 TX=4970528
 172           worker 15 thread done. RX=4974087 TX=4974087
 173           worker 8 thread done. RX=4979908 TX=4979908
 174           worker 2 thread done. RX=0 TX=0
 175
 176         Port Workload distribution:
 177         worker 0 :      12.5 % (4979876 pkts)
 178         worker 1 :      12.5 % (4970497 pkts)
 179         worker 2 :      12.5 % (4986359 pkts)
 180         worker 3 :      12.5 % (4970517 pkts)
 181         worker 4 :      12.5 % (4966566 pkts)
 182         worker 5 :      12.5 % (4963297 pkts)
 183         worker 6 :      12.5 % (4953598 pkts)
 184         worker 7 :      12.5 % (4974055 pkts)
 185
 186 To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to
 187 this application. When the app is terminated using ``Ctrl+C``, the
 188 ``rte_event_dev_dump()`` function is called, resulting in a dump of the
 189 statistics that the PMD provides. The statistics provided depend on the PMD
 190 used, see the Event Device Drivers section for a list of eventdev PMDs.