1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Cavium, Inc 3 4dpdk-test-eventdev Application 5============================== 6 7The ``dpdk-test-eventdev`` tool is a Data Plane Development Kit (DPDK) 8application that allows exercising various eventdev use cases. 9This application has a generic framework to add new eventdev based test cases to 10verify functionality and measure the performance parameters of DPDK eventdev 11devices. 12 13Compiling the Application 14------------------------- 15 16**Build the application** 17 18Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the 19``dpdk-test-eventdev`` application. 20 21Initially, the user must select a DPDK target to choose the correct target type 22and compiler options to use when building the libraries. 23The user must have all libraries, modules, updates and compilers installed 24in the system prior to this, 25as described in the earlier chapters in this Getting Started Guide. 26 27Running the Application 28----------------------- 29 30The application has a number of command line options: 31 32.. code-block:: console 33 34 dpdk-test-eventdev [EAL Options] -- [application options] 35 36EAL Options 37~~~~~~~~~~~ 38 39The following are the EAL command-line options that can be used in conjunction 40with the ``dpdk-test-eventdev`` application. 41See the DPDK Getting Started Guides for more information on these options. 42 43* ``-c <COREMASK>`` or ``-l <CORELIST>`` 44 45 Set the hexadecimal bitmask of the cores to run on. The corelist is a 46 list of cores to use. 47 48* ``--vdev <driver><id>`` 49 50 Add a virtual eventdev device. 51 52Application Options 53~~~~~~~~~~~~~~~~~~~ 54 55The following are the application command-line options: 56 57* ``--verbose`` 58 59 Set verbose level. Default is 1. Value > 1 displays more details. 60 61* ``--dev <n>`` 62 63 Set the device id of the event device. 64 65* ``--test <name>`` 66 67 Set test name, where ``name`` is one of the following:: 68 69 order_queue 70 order_atq 71 perf_queue 72 perf_atq 73 74* ``--socket_id <n>`` 75 76 Set the socket id of the application resources. 77 78* ``--pool-sz <n>`` 79 80 Set the number of mbufs to be allocated from the mempool. 81 82* ``--plcores <CORELIST>`` 83 84 Set the list of cores to be used as producers. 85 86* ``--wlcores <CORELIST>`` 87 88 Set the list of cores to be used as workers. 89 90* ``--stlist <type_list>`` 91 92 Set the scheduled type of each stage where ``type_list`` size 93 determines the number of stages used in the test application. 94 Each type_list member can be one of the following:: 95 96 P or p : Parallel schedule type 97 O or o : Ordered schedule type 98 A or a : Atomic schedule type 99 100 Application expects the ``type_list`` in comma separated form (i.e. ``--stlist o,a,a,a``) 101 102* ``--nb_flows <n>`` 103 104 Set the number of flows to produce. 105 106* ``--nb_pkts <n>`` 107 108 Set the number of packets to produce. 0 implies no limit. 109 110* ``--worker_deq_depth <n>`` 111 112 Set the dequeue depth of the worker. 113 114* ``--fwd_latency`` 115 116 Perform forward latency measurement. 117 118* ``--queue_priority`` 119 120 Enable queue priority. 121 122* ``--prod_type_ethdev`` 123 124 Use ethernet device as producer. 125 126Eventdev Tests 127-------------- 128 129ORDER_QUEUE Test 130~~~~~~~~~~~~~~~~ 131 132This is a functional test case that aims at testing the following: 133 134#. Verify the ingress order maintenance. 135#. Verify the exclusive(atomic) access to given atomic flow per eventdev port. 136 137.. _table_eventdev_order_queue_test: 138 139.. table:: Order queue test eventdev configuration. 140 141 +---+--------------+----------------+------------------------+ 142 | # | Items | Value | Comments | 143 | | | | | 144 +===+==============+================+========================+ 145 | 1 | nb_queues | 2 | q0(ordered), q1(atomic)| 146 | | | | | 147 +---+--------------+----------------+------------------------+ 148 | 2 | nb_producers | 1 | | 149 | | | | | 150 +---+--------------+----------------+------------------------+ 151 | 3 | nb_workers | >= 1 | | 152 | | | | | 153 +---+--------------+----------------+------------------------+ 154 | 4 | nb_ports | nb_workers + | Workers use port 0 to | 155 | | | 1 | port n-1. Producer uses| 156 | | | | port n | 157 +---+--------------+----------------+------------------------+ 158 159.. _figure_eventdev_order_queue_test: 160 161.. figure:: img/eventdev_order_queue_test.* 162 163 order queue test operation. 164 165The order queue test configures the eventdev with two queues and an event 166producer to inject the events to q0(ordered) queue. Both q0(ordered) and 167q1(atomic) are linked to all the workers. 168 169The event producer maintains a sequence number per flow and injects the events 170to the ordered queue. The worker receives the events from ordered queue and 171forwards to atomic queue. Since the events from an ordered queue can be 172processed in parallel on the different workers, the ingress order of events 173might have changed on the downstream atomic queue enqueue. On enqueue to the 174atomic queue, the eventdev PMD driver reorders the event to the original 175ingress order(i.e producer ingress order). 176 177When the event is dequeued from the atomic queue by the worker, this test 178verifies the expected sequence number of associated event per flow by comparing 179the free running expected sequence number per flow. 180 181Application options 182^^^^^^^^^^^^^^^^^^^ 183 184Supported application command line options are following:: 185 186 --verbose 187 --dev 188 --test 189 --socket_id 190 --pool_sz 191 --plcores 192 --wlcores 193 --nb_flows 194 --nb_pkts 195 --worker_deq_depth 196 197Example 198^^^^^^^ 199 200Example command to run order queue test: 201 202.. code-block:: console 203 204 sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \ 205 --test=order_queue --plcores 1 --wlcores 2,3 206 207 208ORDER_ATQ Test 209~~~~~~~~~~~~~~ 210 211This test verifies the same aspects of ``order_queue`` test, the difference is 212the number of queues used, this test operates on a single ``all types queue(atq)`` 213instead of two different queues for ordered and atomic. 214 215.. _table_eventdev_order_atq_test: 216 217.. table:: Order all types queue test eventdev configuration. 218 219 +---+--------------+----------------+------------------------+ 220 | # | Items | Value | Comments | 221 | | | | | 222 +===+==============+================+========================+ 223 | 1 | nb_queues | 1 | q0(all types queue) | 224 | | | | | 225 +---+--------------+----------------+------------------------+ 226 | 2 | nb_producers | 1 | | 227 | | | | | 228 +---+--------------+----------------+------------------------+ 229 | 3 | nb_workers | >= 1 | | 230 | | | | | 231 +---+--------------+----------------+------------------------+ 232 | 4 | nb_ports | nb_workers + | Workers use port 0 to | 233 | | | 1 | port n-1.Producer uses | 234 | | | | port n. | 235 +---+--------------+----------------+------------------------+ 236 237.. _figure_eventdev_order_atq_test: 238 239.. figure:: img/eventdev_order_atq_test.* 240 241 order all types queue test operation. 242 243Application options 244^^^^^^^^^^^^^^^^^^^ 245 246Supported application command line options are following:: 247 248 --verbose 249 --dev 250 --test 251 --socket_id 252 --pool_sz 253 --plcores 254 --wlcores 255 --nb_flows 256 --nb_pkts 257 --worker_deq_depth 258 259Example 260^^^^^^^ 261 262Example command to run order ``all types queue`` test: 263 264.. code-block:: console 265 266 sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \ 267 --test=order_atq --plcores 1 --wlcores 2,3 268 269 270PERF_QUEUE Test 271~~~~~~~~~~~~~~~ 272 273This is a performance test case that aims at testing the following: 274 275#. Measure the number of events can be processed in a second. 276#. Measure the latency to forward an event. 277 278.. _table_eventdev_perf_queue_test: 279 280.. table:: Perf queue test eventdev configuration. 281 282 +---+--------------+----------------+-----------------------------------------+ 283 | # | Items | Value | Comments | 284 | | | | | 285 +===+==============+================+=========================================+ 286 | 1 | nb_queues | nb_producers * | Queues will be configured based on the | 287 | | | nb_stages | user requested sched type list(--stlist)| 288 +---+--------------+----------------+-----------------------------------------+ 289 | 2 | nb_producers | >= 1 | Selected through --plcores command line | 290 | | | | argument. | 291 +---+--------------+----------------+-----------------------------------------+ 292 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 293 | | | | argument | 294 +---+--------------+----------------+-----------------------------------------+ 295 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n-1. | 296 | | | nb_producers | Producers use port n to port p | 297 +---+--------------+----------------+-----------------------------------------+ 298 299.. _figure_eventdev_perf_queue_test: 300 301.. figure:: img/eventdev_perf_queue_test.* 302 303 perf queue test operation. 304 305The perf queue test configures the eventdev with Q queues and P ports, where 306Q and P is a function of the number of workers, the number of producers and 307number of stages as mentioned in :numref:`table_eventdev_perf_queue_test`. 308 309The user can choose the number of workers, the number of producers and number of 310stages through the ``--wlcores``, ``--plcores`` and the ``--stlist`` application 311command line arguments respectively. 312 313The producer(s) injects the events to eventdev based the first stage sched type 314list requested by the user through ``--stlist`` the command line argument. 315 316Based on the number of stages to process(selected through ``--stlist``), 317The application forwards the event to next upstream queue and terminates when it 318reaches the last stage in the pipeline. On event termination, application 319increments the number events processed and print periodically in one second 320to get the number of events processed in one second. 321 322When ``--fwd_latency`` command line option selected, the application inserts 323the timestamp in the event on the first stage and then on termination, it 324updates the number of cycles to forward a packet. The application uses this 325value to compute the average latency to a forward packet. 326 327When ``--prod_type_ethdev`` command line option is selected, the application 328uses the probed ethernet devices as producers by configuring them as Rx 329adapters instead of using synthetic producers. 330 331Application options 332^^^^^^^^^^^^^^^^^^^ 333 334Supported application command line options are following:: 335 336 --verbose 337 --dev 338 --test 339 --socket_id 340 --pool_sz 341 --plcores 342 --wlcores 343 --stlist 344 --nb_flows 345 --nb_pkts 346 --worker_deq_depth 347 --fwd_latency 348 --queue_priority 349 --prod_type_ethdev 350 351Example 352^^^^^^^ 353 354Example command to run perf queue test: 355 356.. code-block:: console 357 358 sudo build/app/dpdk-test-eventdev -c 0xf -s 0x1 --vdev=event_sw0 -- \ 359 --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0 360 361Example command to run perf queue test with ethernet ports: 362 363.. code-block:: console 364 365 sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \ 366 --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --prod_type_ethdev 367 368PERF_ATQ Test 369~~~~~~~~~~~~~~~ 370 371This is a performance test case that aims at testing the following with 372``all types queue`` eventdev scheme. 373 374#. Measure the number of events can be processed in a second. 375#. Measure the latency to forward an event. 376 377.. _table_eventdev_perf_atq_test: 378 379.. table:: Perf all types queue test eventdev configuration. 380 381 +---+--------------+----------------+-----------------------------------------+ 382 | # | Items | Value | Comments | 383 | | | | | 384 +===+==============+================+=========================================+ 385 | 1 | nb_queues | nb_producers | Queues will be configured based on the | 386 | | | | user requested sched type list(--stlist)| 387 +---+--------------+----------------+-----------------------------------------+ 388 | 2 | nb_producers | >= 1 | Selected through --plcores command line | 389 | | | | argument. | 390 +---+--------------+----------------+-----------------------------------------+ 391 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 392 | | | | argument | 393 +---+--------------+----------------+-----------------------------------------+ 394 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n-1. | 395 | | | nb_producers | Producers use port n to port p | 396 +---+--------------+----------------+-----------------------------------------+ 397 398.. _figure_eventdev_perf_atq_test: 399 400.. figure:: img/eventdev_perf_atq_test.* 401 402 perf all types queue test operation. 403 404 405The ``all types queues(atq)`` perf test configures the eventdev with Q queues 406and P ports, where Q and P is a function of the number of workers and number of 407producers as mentioned in :numref:`table_eventdev_perf_atq_test`. 408 409 410The atq queue test functions as same as ``perf_queue`` test. The difference 411is, It uses, ``all type queue scheme`` instead of separate queues for each 412stage and thus reduces the number of queues required to realize the use case 413and enables flow pinning as the event does not move to the next queue. 414 415 416Application options 417^^^^^^^^^^^^^^^^^^^ 418 419Supported application command line options are following:: 420 421 --verbose 422 --dev 423 --test 424 --socket_id 425 --pool_sz 426 --plcores 427 --wlcores 428 --stlist 429 --nb_flows 430 --nb_pkts 431 --worker_deq_depth 432 --fwd_latency 433 --prod_type_ethdev 434 435Example 436^^^^^^^ 437 438Example command to run perf ``all types queue`` test: 439 440.. code-block:: console 441 442 sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \ 443 --test=perf_atq --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0 444 445 446PIPELINE_QUEUE Test 447~~~~~~~~~~~~~~~~~~~ 448 449This is a pipeline test case that aims at testing the following: 450 451#. Measure the end-to-end performance of an event dev with a ethernet dev. 452#. Maintain packet ordering from Rx to Tx. 453 454.. _table_eventdev_pipeline_queue_test: 455 456.. table:: Pipeline queue test eventdev configuration. 457 458 +---+--------------+----------------+-----------------------------------------+ 459 | # | Items | Value | Comments | 460 | | | | | 461 +===+==============+================+=========================================+ 462 | 1 | nb_queues | (nb_producers | Queues will be configured based on the | 463 | | | * nb_stages) + | user requested sched type list(--stlist)| 464 | | | x | Here value of x is 1 in generic pipeline| 465 | | | | and nb_producers in lockfree pipeline | 466 +---+--------------+----------------+-----------------------------------------+ 467 | 2 | nb_producers | >= 1 | Producers will be configured based on | 468 | | | | the number of detected ethernet devices.| 469 | | | | Each ethdev will be configured as an Rx | 470 | | | | adapter. | 471 +---+--------------+----------------+-----------------------------------------+ 472 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 473 | | | | argument | 474 +---+--------------+----------------+-----------------------------------------+ 475 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n. | 476 | | | nb_producers | Producers use port n+1 to port n+m, | 477 | | | | depending on the Rx adapter capability. | 478 +---+--------------+----------------+-----------------------------------------+ 479 480.. _figure_eventdev_pipeline_queue_test_generic: 481 482.. figure:: img/eventdev_pipeline_queue_test_generic.* 483 484.. _figure_eventdev_pipeline_queue_test_lockfree: 485 486.. figure:: img/eventdev_pipeline_queue_test_lockfree.* 487 488 pipeline queue test operation. 489 490The pipeline queue test configures the eventdev with Q queues and P ports, 491where Q and P is a function of the number of workers, the number of producers 492and number of stages as mentioned in :numref:`table_eventdev_pipeline_queue_test`. 493 494The user can choose the number of workers and number of stages through the 495``--wlcores`` and the ``--stlist`` application command line arguments 496respectively. 497 498The number of producers depends on the number of ethernet devices detected and 499each ethernet device is configured as a event_eth_rx_adapter that acts as a 500producer. 501 502The producer(s) injects the events to eventdev based the first stage sched type 503list requested by the user through ``--stlist`` the command line argument. 504 505Based on the number of stages to process(selected through ``--stlist``), 506The application forwards the event to next upstream queue and when it reaches 507the last stage in the pipeline if the event type is ``atomic`` it is enqueued 508onto ethdev Tx queue else to maintain ordering the event type is set to 509``atomic`` and enqueued onto the last stage queue. 510 511If the ethernet has ``DEV_TX_OFFLOAD_MT_LOCKFREE`` capability then the worker 512cores transmit the packets directly. Else the worker cores enqueue the packet 513onto the ``SINGLE_LINK_QUEUE`` that is managed by a Tx service. The Tx service 514dequeues the packet and transmits it. 515 516On packet Tx, application increments the number events processed and print 517periodically in one second to get the number of events processed in one 518second. 519 520 521Application options 522^^^^^^^^^^^^^^^^^^^ 523 524Supported application command line options are following:: 525 526 --verbose 527 --dev 528 --test 529 --socket_id 530 --pool_sz 531 --wlcores 532 --stlist 533 --worker_deq_depth 534 --prod_type_ethdev 535 536 537.. Note:: 538 539 * The ``--prod_type_ethdev`` is mandatory for running this test. 540 541Example 542^^^^^^^ 543 544Example command to run pipeline queue test: 545 546.. code-block:: console 547 548 sudo build/app/dpdk-test-eventdev -c 0xf -s 0x8 --vdev=event_sw0 -- \ 549 --test=pipeline_queue --wlcore=1 --prod_type_ethdev --stlist=a 550 551 552PIPELINE_ATQ Test 553~~~~~~~~~~~~~~~~~~~ 554 555This is a pipeline test case that aims at testing the following with 556``all types queue`` eventdev scheme. 557 558#. Measure the end-to-end performance of an event dev with a ethernet dev. 559#. Maintain packet ordering from Rx to Tx. 560 561.. _table_eventdev_pipeline_atq_test: 562 563.. table:: Pipeline atq test eventdev configuration. 564 565 +---+--------------+----------------+-----------------------------------------+ 566 | # | Items | Value | Comments | 567 | | | | | 568 +===+==============+================+=========================================+ 569 | 1 | nb_queues | nb_producers + | Queues will be configured based on the | 570 | | | x | user requested sched type list(--stlist)| 571 | | | | where x = 1 in generic pipeline and 0 | 572 | | | | in lockfree pipeline | 573 +---+--------------+----------------+-----------------------------------------+ 574 | 2 | nb_producers | >= 1 | Producers will be configured based on | 575 | | | | the number of detected ethernet devices.| 576 | | | | Each ethdev will be configured as an Rx | 577 | | | | adapter. | 578 +---+--------------+----------------+-----------------------------------------+ 579 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 580 | | | | argument | 581 +---+--------------+----------------+-----------------------------------------+ 582 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n. | 583 | | | nb_producers | Producers use port n+1 to port n+m, | 584 | | | | depending on the Rx adapter capability. | 585 +---+--------------+----------------+-----------------------------------------+ 586 587.. _figure_eventdev_pipeline_atq_test_generic: 588 589.. figure:: img/eventdev_pipeline_atq_test_generic.* 590 591.. _figure_eventdev_pipeline_atq_test_lockfree: 592 593.. figure:: img/eventdev_pipeline_atq_test_lockfree.* 594 595 pipeline atq test operation. 596 597The pipeline atq test configures the eventdev with Q queues and P ports, 598where Q and P is a function of the number of workers, the number of producers 599and number of stages as mentioned in :numref:`table_eventdev_pipeline_atq_test`. 600 601The atq queue test functions as same as ``pipeline_queue`` test. The difference 602is, It uses, ``all type queue scheme`` instead of separate queues for each 603stage and thus reduces the number of queues required to realize the use case. 604 605 606Application options 607^^^^^^^^^^^^^^^^^^^ 608 609Supported application command line options are following:: 610 611 --verbose 612 --dev 613 --test 614 --socket_id 615 --pool_sz 616 --wlcores 617 --stlist 618 --worker_deq_depth 619 --prod_type_ethdev 620 621 622.. Note:: 623 624 * The ``--prod_type_ethdev`` is mandatory for running this test. 625 626Example 627^^^^^^^ 628 629Example command to run pipeline queue test: 630 631.. code-block:: console 632 633 sudo build/app/dpdk-test-eventdev -c 0xf -s 0x8 --vdev=event_sw0 -- \ 634 --test=pipeline_atq --wlcore=1 --prod_type_ethdev --stlist=a 635