doc/guides/tools/testeventdev.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Cavium, Inc. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Cavium, Inc nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 dpdk-test-eventdev Application
  32 ==============================
  33
  34 The ``dpdk-test-eventdev`` tool is a Data Plane Development Kit (DPDK)
  35 application that allows exercising various eventdev use cases.
  36 This application has a generic framework to add new eventdev based test cases to
  37 verify functionality and measure the performance parameters of DPDK eventdev
  38 devices.
  39
  40 Compiling the Application
  41 -------------------------
  42
  43 **Build the application**
  44
  45 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
  46 ``dpdk-test-eventdev`` application.
  47
  48 Initially, the user must select a DPDK target to choose the correct target type
  49 and compiler options to use when building the libraries.
  50 The user must have all libraries, modules, updates and compilers installed
  51 in the system prior to this,
  52 as described in the earlier chapters in this Getting Started Guide.
  53
  54 Running the Application
  55 -----------------------
  56
  57 The application has a number of command line options:
  58
  59 .. code-block:: console
  60
  61    dpdk-test-eventdev [EAL Options] -- [application options]
  62
  63 EAL Options
  64 ~~~~~~~~~~~
  65
  66 The following are the EAL command-line options that can be used in conjunction
  67 with the ``dpdk-test-eventdev`` application.
  68 See the DPDK Getting Started Guides for more information on these options.
  69
  70 *   ``-c <COREMASK>`` or ``-l <CORELIST>``
  71
  72         Set the hexadecimal bitmask of the cores to run on. The corelist is a
  73         list of cores to use.
  74
  75 *   ``--vdev <driver><id>``
  76
  77         Add a virtual eventdev device.
  78
  79 Application Options
  80 ~~~~~~~~~~~~~~~~~~~
  81
  82 The following are the application command-line options:
  83
  84 * ``--verbose``
  85
  86         Set verbose level. Default is 1. Value > 1 displays more details.
  87
  88 * ``--dev <n>``
  89
  90         Set the device id of the event device.
  91
  92 * ``--test <name>``
  93
  94         Set test name, where ``name`` is one of the following::
  95
  96          order_queue
  97          order_atq
  98          perf_queue
  99          perf_atq
 100
 101 * ``--socket_id <n>``
 102
 103         Set the socket id of the application resources.
 104
 105 * ``--pool-sz <n>``
 106
 107         Set the number of mbufs to be allocated from the mempool.
 108
 109 * ``--plcores <CORELIST>``
 110
 111         Set the list of cores to be used as producers.
 112
 113 * ``--wlcores <CORELIST>``
 114
 115         Set the list of cores to be used as workers.
 116
 117 * ``--stlist <type_list>``
 118
 119         Set the scheduled type of each stage where ``type_list`` size
 120         determines the number of stages used in the test application.
 121         Each type_list member can be one of the following::
 122
 123             P or p : Parallel schedule type
 124             O or o : Ordered schedule type
 125             A or a : Atomic schedule type
 126
 127         Application expects the ``type_list`` in comma separated form (i.e. ``--stlist o,a,a,a``)
 128
 129 * ``--nb_flows <n>``
 130
 131         Set the number of flows to produce.
 132
 133 * ``--nb_pkts <n>``
 134
 135         Set the number of packets to produce. 0 implies no limit.
 136
 137 * ``--worker_deq_depth <n>``
 138
 139         Set the dequeue depth of the worker.
 140
 141 * ``--fwd_latency``
 142
 143         Perform forward latency measurement.
 144
 145 * ``--queue_priority``
 146
 147         Enable queue priority.
 148
 149
 150 Eventdev Tests
 151 --------------
 152
 153 ORDER_QUEUE Test
 154 ~~~~~~~~~~~~~~~~
 155
 156 This is a functional test case that aims at testing the following:
 157
 158 #. Verify the ingress order maintenance.
 159 #. Verify the exclusive(atomic) access to given atomic flow per eventdev port.
 160
 161 .. _table_eventdev_order_queue_test:
 162
 163 .. table:: Order queue test eventdev configuration.
 164
 165    +---+--------------+----------------+------------------------+
 166    | # | Items        | Value          | Comments               |
 167    |   |              |                |                        |
 168    +===+==============+================+========================+
 169    | 1 | nb_queues    | 2              | q0(ordered), q1(atomic)|
 170    |   |              |                |                        |
 171    +---+--------------+----------------+------------------------+
 172    | 2 | nb_producers | 1              |                        |
 173    |   |              |                |                        |
 174    +---+--------------+----------------+------------------------+
 175    | 3 | nb_workers   | >= 1           |                        |
 176    |   |              |                |                        |
 177    +---+--------------+----------------+------------------------+
 178    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to  |
 179    |   |              | 1              | port n-1. Producer uses|
 180    |   |              |                | port n                 |
 181    +---+--------------+----------------+------------------------+
 182
 183 .. _figure_eventdev_order_queue_test:
 184
 185 .. figure:: img/eventdev_order_queue_test.*
 186
 187    order queue test operation.
 188
 189 The order queue test configures the eventdev with two queues and an event
 190 producer to inject the events to q0(ordered) queue. Both q0(ordered) and
 191 q1(atomic) are linked to all the workers.
 192
 193 The event producer maintains a sequence number per flow and injects the events
 194 to the ordered queue. The worker receives the events from ordered queue and
 195 forwards to atomic queue. Since the events from an ordered queue can be
 196 processed in parallel on the different workers, the ingress order of events
 197 might have changed on the downstream atomic queue enqueue. On enqueue to the
 198 atomic queue, the eventdev PMD driver reorders the event to the original
 199 ingress order(i.e producer ingress order).
 200
 201 When the event is dequeued from the atomic queue by the worker, this test
 202 verifies the expected sequence number of associated event per flow by comparing
 203 the free running expected sequence number per flow.
 204
 205 Application options
 206 ^^^^^^^^^^^^^^^^^^^
 207
 208 Supported application command line options are following::
 209
 210    --verbose
 211    --dev
 212    --test
 213    --socket_id
 214    --pool_sz
 215    --plcores
 216    --wlcores
 217    --nb_flows
 218    --nb_pkts
 219    --worker_deq_depth
 220
 221 Example
 222 ^^^^^^^
 223
 224 Example command to run order queue test:
 225
 226 .. code-block:: console
 227
 228    sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \
 229                 --test=order_queue --plcores 1 --wlcores 2,3
 230
 231
 232 ORDER_ATQ Test
 233 ~~~~~~~~~~~~~~
 234
 235 This test verifies the same aspects of ``order_queue`` test, the difference is
 236 the number of queues used, this test operates on a single ``all types queue(atq)``
 237 instead of two different queues for ordered and atomic.
 238
 239 .. _table_eventdev_order_atq_test:
 240
 241 .. table:: Order all types queue test eventdev configuration.
 242
 243    +---+--------------+----------------+------------------------+
 244    | # | Items        | Value          | Comments               |
 245    |   |              |                |                        |
 246    +===+==============+================+========================+
 247    | 1 | nb_queues    | 1              | q0(all types queue)    |
 248    |   |              |                |                        |
 249    +---+--------------+----------------+------------------------+
 250    | 2 | nb_producers | 1              |                        |
 251    |   |              |                |                        |
 252    +---+--------------+----------------+------------------------+
 253    | 3 | nb_workers   | >= 1           |                        |
 254    |   |              |                |                        |
 255    +---+--------------+----------------+------------------------+
 256    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to  |
 257    |   |              | 1              | port n-1.Producer uses |
 258    |   |              |                | port n.                |
 259    +---+--------------+----------------+------------------------+
 260
 261 .. _figure_eventdev_order_atq_test:
 262
 263 .. figure:: img/eventdev_order_atq_test.*
 264
 265    order all types queue test operation.
 266
 267 Application options
 268 ^^^^^^^^^^^^^^^^^^^
 269
 270 Supported application command line options are following::
 271
 272    --verbose
 273    --dev
 274    --test
 275    --socket_id
 276    --pool_sz
 277    --plcores
 278    --wlcores
 279    --nb_flows
 280    --nb_pkts
 281    --worker_deq_depth
 282
 283 Example
 284 ^^^^^^^
 285
 286 Example command to run order ``all types queue`` test:
 287
 288 .. code-block:: console
 289
 290    sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \
 291                         --test=order_atq --plcores 1 --wlcores 2,3
 292
 293
 294 PERF_QUEUE Test
 295 ~~~~~~~~~~~~~~~
 296
 297 This is a performance test case that aims at testing the following:
 298
 299 #. Measure the number of events can be processed in a second.
 300 #. Measure the latency to forward an event.
 301
 302 .. _table_eventdev_perf_queue_test:
 303
 304 .. table:: Perf queue test eventdev configuration.
 305
 306    +---+--------------+----------------+-----------------------------------------+
 307    | # | Items        | Value          | Comments                                |
 308    |   |              |                |                                         |
 309    +===+==============+================+=========================================+
 310    | 1 | nb_queues    | nb_producers * | Queues will be configured based on the  |
 311    |   |              | nb_stages      | user requested sched type list(--stlist)|
 312    +---+--------------+----------------+-----------------------------------------+
 313    | 2 | nb_producers | >= 1           | Selected through --plcores command line |
 314    |   |              |                | argument.                               |
 315    +---+--------------+----------------+-----------------------------------------+
 316    | 3 | nb_workers   | >= 1           | Selected through --wlcores command line |
 317    |   |              |                | argument                                |
 318    +---+--------------+----------------+-----------------------------------------+
 319    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to port n-1.         |
 320    |   |              | nb_producers   | Producers use port n to port p          |
 321    +---+--------------+----------------+-----------------------------------------+
 322
 323 .. _figure_eventdev_perf_queue_test:
 324
 325 .. figure:: img/eventdev_perf_queue_test.*
 326
 327    perf queue test operation.
 328
 329 The perf queue test configures the eventdev with Q queues and P ports, where
 330 Q and P is a function of the number of workers, the number of producers and
 331 number of stages as mentioned in :numref:`table_eventdev_perf_queue_test`.
 332
 333 The user can choose the number of workers, the number of producers and number of
 334 stages through the ``--wlcores``, ``--plcores`` and the ``--stlist`` application
 335 command line arguments respectively.
 336
 337 The producer(s) injects the events to eventdev based the first stage sched type
 338 list requested by the user through ``--stlist`` the command line argument.
 339
 340 Based on the number of stages to process(selected through ``--stlist``),
 341 The application forwards the event to next upstream queue and terminates when it
 342 reaches the last stage in the pipeline. On event termination, application
 343 increments the number events processed and print periodically in one second
 344 to get the number of events processed in one second.
 345
 346 When ``--fwd_latency`` command line option selected, the application inserts
 347 the timestamp in the event on the first stage and then on termination, it
 348 updates the number of cycles to forward a packet. The application uses this
 349 value to compute the average latency to a forward packet.
 350
 351 Application options
 352 ^^^^^^^^^^^^^^^^^^^
 353
 354 Supported application command line options are following::
 355
 356         --verbose
 357         --dev
 358         --test
 359         --socket_id
 360         --pool_sz
 361         --plcores
 362         --wlcores
 363         --stlist
 364         --nb_flows
 365         --nb_pkts
 366         --worker_deq_depth
 367         --fwd_latency
 368         --queue_priority
 369
 370 Example
 371 ^^^^^^^
 372
 373 Example command to run perf queue test:
 374
 375 .. code-block:: console
 376
 377    sudo build/app/dpdk-test-eventdev -c 0xf -s 0x1 --vdev=event_sw0 -- \
 378         --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0
 379
 380
 381 PERF_ATQ Test
 382 ~~~~~~~~~~~~~~~
 383
 384 This is a performance test case that aims at testing the following with
 385 ``all types queue`` eventdev scheme.
 386
 387 #. Measure the number of events can be processed in a second.
 388 #. Measure the latency to forward an event.
 389
 390 .. _table_eventdev_perf_atq_test:
 391
 392 .. table:: Perf all types queue test eventdev configuration.
 393
 394    +---+--------------+----------------+-----------------------------------------+
 395    | # | Items        | Value          | Comments                                |
 396    |   |              |                |                                         |
 397    +===+==============+================+=========================================+
 398    | 1 | nb_queues    | nb_producers   | Queues will be configured based on the  |
 399    |   |              |                | user requested sched type list(--stlist)|
 400    +---+--------------+----------------+-----------------------------------------+
 401    | 2 | nb_producers | >= 1           | Selected through --plcores command line |
 402    |   |              |                | argument.                               |
 403    +---+--------------+----------------+-----------------------------------------+
 404    | 3 | nb_workers   | >= 1           | Selected through --wlcores command line |
 405    |   |              |                | argument                                |
 406    +---+--------------+----------------+-----------------------------------------+
 407    | 4 | nb_ports     | nb_workers +   | Workers use port 0 to port n-1.         |
 408    |   |              | nb_producers   | Producers use port n to port p          |
 409    +---+--------------+----------------+-----------------------------------------+
 410
 411 .. _figure_eventdev_perf_atq_test:
 412
 413 .. figure:: img/eventdev_perf_atq_test.*
 414
 415    perf all types queue test operation.
 416
 417
 418 The ``all types queues(atq)`` perf test configures the eventdev with Q queues
 419 and P ports, where Q and P is a function of the number of workers and number of
 420 producers as mentioned in :numref:`table_eventdev_perf_atq_test`.
 421
 422
 423 The atq queue test functions as same as ``perf_queue`` test. The difference
 424 is, It uses, ``all type queue scheme`` instead of separate queues for each
 425 stage and thus reduces the number of queues required to realize the use case
 426 and enables flow pinning as the event does not move to the next queue.
 427
 428
 429 Application options
 430 ^^^^^^^^^^^^^^^^^^^
 431
 432 Supported application command line options are following::
 433
 434         --verbose
 435         --dev
 436         --test
 437         --socket_id
 438         --pool_sz
 439         --plcores
 440         --wlcores
 441         --stlist
 442         --nb_flows
 443         --nb_pkts
 444         --worker_deq_depth
 445         --fwd_latency
 446
 447 Example
 448 ^^^^^^^
 449
 450 Example command to run perf ``all types queue`` test:
 451
 452 .. code-block:: console
 453
 454    sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \
 455                 --test=perf_atq --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0