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 31dpdk-test-eventdev Application 32============================== 33 34The ``dpdk-test-eventdev`` tool is a Data Plane Development Kit (DPDK) 35application that allows exercising various eventdev use cases. 36This application has a generic framework to add new eventdev based test cases to 37verify functionality and measure the performance parameters of DPDK eventdev 38devices. 39 40Compiling the Application 41------------------------- 42 43**Build the application** 44 45Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the 46``dpdk-test-eventdev`` application. 47 48Initially, the user must select a DPDK target to choose the correct target type 49and compiler options to use when building the libraries. 50The user must have all libraries, modules, updates and compilers installed 51in the system prior to this, 52as described in the earlier chapters in this Getting Started Guide. 53 54Running the Application 55----------------------- 56 57The application has a number of command line options: 58 59.. code-block:: console 60 61 dpdk-test-eventdev [EAL Options] -- [application options] 62 63EAL Options 64~~~~~~~~~~~ 65 66The following are the EAL command-line options that can be used in conjunction 67with the ``dpdk-test-eventdev`` application. 68See 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 79Application Options 80~~~~~~~~~~~~~~~~~~~ 81 82The 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 150Eventdev Tests 151-------------- 152 153ORDER_QUEUE Test 154~~~~~~~~~~~~~~~~ 155 156This 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 189The order queue test configures the eventdev with two queues and an event 190producer to inject the events to q0(ordered) queue. Both q0(ordered) and 191q1(atomic) are linked to all the workers. 192 193The event producer maintains a sequence number per flow and injects the events 194to the ordered queue. The worker receives the events from ordered queue and 195forwards to atomic queue. Since the events from an ordered queue can be 196processed in parallel on the different workers, the ingress order of events 197might have changed on the downstream atomic queue enqueue. On enqueue to the 198atomic queue, the eventdev PMD driver reorders the event to the original 199ingress order(i.e producer ingress order). 200 201When the event is dequeued from the atomic queue by the worker, this test 202verifies the expected sequence number of associated event per flow by comparing 203the free running expected sequence number per flow. 204 205Application options 206^^^^^^^^^^^^^^^^^^^ 207 208Supported 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 221Example 222^^^^^^^ 223 224Example 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 232ORDER_ATQ Test 233~~~~~~~~~~~~~~ 234 235This test verifies the same aspects of ``order_queue`` test, the difference is 236the number of queues used, this test operates on a single ``all types queue(atq)`` 237instead 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 267Application options 268^^^^^^^^^^^^^^^^^^^ 269 270Supported 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 283Example 284^^^^^^^ 285 286Example 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 294PERF_QUEUE Test 295~~~~~~~~~~~~~~~ 296 297This 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 329The perf queue test configures the eventdev with Q queues and P ports, where 330Q and P is a function of the number of workers, the number of producers and 331number of stages as mentioned in :numref:`table_eventdev_perf_queue_test`. 332 333The user can choose the number of workers, the number of producers and number of 334stages through the ``--wlcores``, ``--plcores`` and the ``--stlist`` application 335command line arguments respectively. 336 337The producer(s) injects the events to eventdev based the first stage sched type 338list requested by the user through ``--stlist`` the command line argument. 339 340Based on the number of stages to process(selected through ``--stlist``), 341The application forwards the event to next upstream queue and terminates when it 342reaches the last stage in the pipeline. On event termination, application 343increments the number events processed and print periodically in one second 344to get the number of events processed in one second. 345 346When ``--fwd_latency`` command line option selected, the application inserts 347the timestamp in the event on the first stage and then on termination, it 348updates the number of cycles to forward a packet. The application uses this 349value to compute the average latency to a forward packet. 350 351Application options 352^^^^^^^^^^^^^^^^^^^ 353 354Supported 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 370Example 371^^^^^^^ 372 373Example 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 381PERF_ATQ Test 382~~~~~~~~~~~~~~~ 383 384This 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 418The ``all types queues(atq)`` perf test configures the eventdev with Q queues 419and P ports, where Q and P is a function of the number of workers and number of 420producers as mentioned in :numref:`table_eventdev_perf_atq_test`. 421 422 423The atq queue test functions as same as ``perf_queue`` test. The difference 424is, It uses, ``all type queue scheme`` instead of separate queues for each 425stage and thus reduces the number of queues required to realize the use case 426and enables flow pinning as the event does not move to the next queue. 427 428 429Application options 430^^^^^^^^^^^^^^^^^^^ 431 432Supported 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 447Example 448^^^^^^^ 449 450Example 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 456