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 pipeline_atq 74 pipeline_queue 75 76* ``--socket_id <n>`` 77 78 Set the socket id of the application resources. 79 80* ``--pool-sz <n>`` 81 82 Set the number of mbufs to be allocated from the mempool. 83 84* ``--plcores <CORELIST>`` 85 86 Set the list of cores to be used as producers. 87 88* ``--wlcores <CORELIST>`` 89 90 Set the list of cores to be used as workers. 91 92* ``--stlist <type_list>`` 93 94 Set the scheduled type of each stage where ``type_list`` size 95 determines the number of stages used in the test application. 96 Each type_list member can be one of the following:: 97 98 P or p : Parallel schedule type 99 O or o : Ordered schedule type 100 A or a : Atomic schedule type 101 102 Application expects the ``type_list`` in comma separated form (i.e. ``--stlist o,a,a,a``) 103 104* ``--nb_flows <n>`` 105 106 Set the number of flows to produce. 107 108* ``--nb_pkts <n>`` 109 110 Set the number of packets to produce. 0 implies no limit. 111 112* ``--worker_deq_depth <n>`` 113 114 Set the dequeue depth of the worker. 115 116* ``--fwd_latency`` 117 118 Perform forward latency measurement. 119 120* ``--queue_priority`` 121 122 Enable queue priority. 123 124* ``--prod_type_ethdev`` 125 126 Use ethernet device as producer. 127 128* ``--prod_type_timerdev`` 129 130 Use event timer adapter as producer. 131 132* ``--prod_type_timerdev_burst`` 133 134 Use burst mode event timer adapter as producer. 135 136* ``--timer_tick_nsec`` 137 138 Used to dictate number of nano seconds between bucket traversal of the 139 event timer adapter. Refer `rte_event_timer_adapter_conf`. 140 141* ``--max_tmo_nsec`` 142 143 Used to configure event timer adapter max arm timeout in nano seconds. 144 145* ``--expiry_nsec`` 146 147 Dictate the number of nano seconds after which the event timer expires. 148 149* ``--nb_timers`` 150 151 Number of event timers each producer core will generate. 152 153* ``--nb_timer_adptrs`` 154 155 Number of event timer adapters to be used. Each adapter is used in 156 round robin manner by the producer cores. 157 158* ``--deq_tmo_nsec`` 159 160 Global dequeue timeout for all the event ports if the provided dequeue 161 timeout is out of the supported range of event device it will be 162 adjusted to the highest/lowest supported dequeue timeout supported. 163 164 165Eventdev Tests 166-------------- 167 168ORDER_QUEUE Test 169~~~~~~~~~~~~~~~~ 170 171This is a functional test case that aims at testing the following: 172 173#. Verify the ingress order maintenance. 174#. Verify the exclusive(atomic) access to given atomic flow per eventdev port. 175 176.. _table_eventdev_order_queue_test: 177 178.. table:: Order queue test eventdev configuration. 179 180 +---+--------------+----------------+------------------------+ 181 | # | Items | Value | Comments | 182 | | | | | 183 +===+==============+================+========================+ 184 | 1 | nb_queues | 2 | q0(ordered), q1(atomic)| 185 | | | | | 186 +---+--------------+----------------+------------------------+ 187 | 2 | nb_producers | 1 | | 188 | | | | | 189 +---+--------------+----------------+------------------------+ 190 | 3 | nb_workers | >= 1 | | 191 | | | | | 192 +---+--------------+----------------+------------------------+ 193 | 4 | nb_ports | nb_workers + | Workers use port 0 to | 194 | | | 1 | port n-1. Producer uses| 195 | | | | port n | 196 +---+--------------+----------------+------------------------+ 197 198.. _figure_eventdev_order_queue_test: 199 200.. figure:: img/eventdev_order_queue_test.* 201 202 order queue test operation. 203 204The order queue test configures the eventdev with two queues and an event 205producer to inject the events to q0(ordered) queue. Both q0(ordered) and 206q1(atomic) are linked to all the workers. 207 208The event producer maintains a sequence number per flow and injects the events 209to the ordered queue. The worker receives the events from ordered queue and 210forwards to atomic queue. Since the events from an ordered queue can be 211processed in parallel on the different workers, the ingress order of events 212might have changed on the downstream atomic queue enqueue. On enqueue to the 213atomic queue, the eventdev PMD driver reorders the event to the original 214ingress order(i.e producer ingress order). 215 216When the event is dequeued from the atomic queue by the worker, this test 217verifies the expected sequence number of associated event per flow by comparing 218the free running expected sequence number per flow. 219 220Application options 221^^^^^^^^^^^^^^^^^^^ 222 223Supported application command line options are following:: 224 225 --verbose 226 --dev 227 --test 228 --socket_id 229 --pool_sz 230 --plcores 231 --wlcores 232 --nb_flows 233 --nb_pkts 234 --worker_deq_depth 235 --deq_tmo_nsec 236 237Example 238^^^^^^^ 239 240Example command to run order queue test: 241 242.. code-block:: console 243 244 sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \ 245 --test=order_queue --plcores 1 --wlcores 2,3 246 247 248ORDER_ATQ Test 249~~~~~~~~~~~~~~ 250 251This test verifies the same aspects of ``order_queue`` test, the difference is 252the number of queues used, this test operates on a single ``all types queue(atq)`` 253instead of two different queues for ordered and atomic. 254 255.. _table_eventdev_order_atq_test: 256 257.. table:: Order all types queue test eventdev configuration. 258 259 +---+--------------+----------------+------------------------+ 260 | # | Items | Value | Comments | 261 | | | | | 262 +===+==============+================+========================+ 263 | 1 | nb_queues | 1 | q0(all types queue) | 264 | | | | | 265 +---+--------------+----------------+------------------------+ 266 | 2 | nb_producers | 1 | | 267 | | | | | 268 +---+--------------+----------------+------------------------+ 269 | 3 | nb_workers | >= 1 | | 270 | | | | | 271 +---+--------------+----------------+------------------------+ 272 | 4 | nb_ports | nb_workers + | Workers use port 0 to | 273 | | | 1 | port n-1.Producer uses | 274 | | | | port n. | 275 +---+--------------+----------------+------------------------+ 276 277.. _figure_eventdev_order_atq_test: 278 279.. figure:: img/eventdev_order_atq_test.* 280 281 order all types queue test operation. 282 283Application options 284^^^^^^^^^^^^^^^^^^^ 285 286Supported application command line options are following:: 287 288 --verbose 289 --dev 290 --test 291 --socket_id 292 --pool_sz 293 --plcores 294 --wlcores 295 --nb_flows 296 --nb_pkts 297 --worker_deq_depth 298 --deq_tmo_nsec 299 300Example 301^^^^^^^ 302 303Example command to run order ``all types queue`` test: 304 305.. code-block:: console 306 307 sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \ 308 --test=order_atq --plcores 1 --wlcores 2,3 309 310 311PERF_QUEUE Test 312~~~~~~~~~~~~~~~ 313 314This is a performance test case that aims at testing the following: 315 316#. Measure the number of events can be processed in a second. 317#. Measure the latency to forward an event. 318 319.. _table_eventdev_perf_queue_test: 320 321.. table:: Perf queue test eventdev configuration. 322 323 +---+--------------+----------------+-----------------------------------------+ 324 | # | Items | Value | Comments | 325 | | | | | 326 +===+==============+================+=========================================+ 327 | 1 | nb_queues | nb_producers * | Queues will be configured based on the | 328 | | | nb_stages | user requested sched type list(--stlist)| 329 +---+--------------+----------------+-----------------------------------------+ 330 | 2 | nb_producers | >= 1 | Selected through --plcores command line | 331 | | | | argument. | 332 +---+--------------+----------------+-----------------------------------------+ 333 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 334 | | | | argument | 335 +---+--------------+----------------+-----------------------------------------+ 336 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n-1. | 337 | | | nb_producers | Producers use port n to port p | 338 +---+--------------+----------------+-----------------------------------------+ 339 340.. _figure_eventdev_perf_queue_test: 341 342.. figure:: img/eventdev_perf_queue_test.* 343 344 perf queue test operation. 345 346The perf queue test configures the eventdev with Q queues and P ports, where 347Q and P is a function of the number of workers, the number of producers and 348number of stages as mentioned in :numref:`table_eventdev_perf_queue_test`. 349 350The user can choose the number of workers, the number of producers and number of 351stages through the ``--wlcores``, ``--plcores`` and the ``--stlist`` application 352command line arguments respectively. 353 354The producer(s) injects the events to eventdev based the first stage sched type 355list requested by the user through ``--stlist`` the command line argument. 356 357Based on the number of stages to process(selected through ``--stlist``), 358The application forwards the event to next upstream queue and terminates when it 359reaches the last stage in the pipeline. On event termination, application 360increments the number events processed and print periodically in one second 361to get the number of events processed in one second. 362 363When ``--fwd_latency`` command line option selected, the application inserts 364the timestamp in the event on the first stage and then on termination, it 365updates the number of cycles to forward a packet. The application uses this 366value to compute the average latency to a forward packet. 367 368When ``--prod_type_ethdev`` command line option is selected, the application 369uses the probed ethernet devices as producers by configuring them as Rx 370adapters instead of using synthetic producers. 371 372Application options 373^^^^^^^^^^^^^^^^^^^ 374 375Supported application command line options are following:: 376 377 --verbose 378 --dev 379 --test 380 --socket_id 381 --pool_sz 382 --plcores 383 --wlcores 384 --stlist 385 --nb_flows 386 --nb_pkts 387 --worker_deq_depth 388 --fwd_latency 389 --queue_priority 390 --prod_type_ethdev 391 --prod_type_timerdev_burst 392 --prod_type_timerdev 393 --timer_tick_nsec 394 --max_tmo_nsec 395 --expiry_nsec 396 --nb_timers 397 --nb_timer_adptrs 398 --deq_tmo_nsec 399 400Example 401^^^^^^^ 402 403Example command to run perf queue test: 404 405.. code-block:: console 406 407 sudo build/app/dpdk-test-eventdev -c 0xf -s 0x1 --vdev=event_sw0 -- \ 408 --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0 409 410Example command to run perf queue test with ethernet ports: 411 412.. code-block:: console 413 414 sudo build/app/dpdk-test-eventdev --vdev=event_sw0 -- \ 415 --test=perf_queue --plcores=2 --wlcore=3 --stlist=p --prod_type_ethdev 416 417Example command to run perf queue test with event timer adapter: 418 419.. code-block:: console 420 421 sudo build/app/dpdk-test-eventdev --vdev="event_octeontx" -- \ 422 --wlcores 4 --plcores 12 --test perf_queue --stlist=a \ 423 --prod_type_timerdev --fwd_latency 424 425PERF_ATQ Test 426~~~~~~~~~~~~~~~ 427 428This is a performance test case that aims at testing the following with 429``all types queue`` eventdev scheme. 430 431#. Measure the number of events can be processed in a second. 432#. Measure the latency to forward an event. 433 434.. _table_eventdev_perf_atq_test: 435 436.. table:: Perf all types queue test eventdev configuration. 437 438 +---+--------------+----------------+-----------------------------------------+ 439 | # | Items | Value | Comments | 440 | | | | | 441 +===+==============+================+=========================================+ 442 | 1 | nb_queues | nb_producers | Queues will be configured based on the | 443 | | | | user requested sched type list(--stlist)| 444 +---+--------------+----------------+-----------------------------------------+ 445 | 2 | nb_producers | >= 1 | Selected through --plcores command line | 446 | | | | argument. | 447 +---+--------------+----------------+-----------------------------------------+ 448 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 449 | | | | argument | 450 +---+--------------+----------------+-----------------------------------------+ 451 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n-1. | 452 | | | nb_producers | Producers use port n to port p | 453 +---+--------------+----------------+-----------------------------------------+ 454 455.. _figure_eventdev_perf_atq_test: 456 457.. figure:: img/eventdev_perf_atq_test.* 458 459 perf all types queue test operation. 460 461 462The ``all types queues(atq)`` perf test configures the eventdev with Q queues 463and P ports, where Q and P is a function of the number of workers and number of 464producers as mentioned in :numref:`table_eventdev_perf_atq_test`. 465 466 467The atq queue test functions as same as ``perf_queue`` test. The difference 468is, It uses, ``all type queue scheme`` instead of separate queues for each 469stage and thus reduces the number of queues required to realize the use case 470and enables flow pinning as the event does not move to the next queue. 471 472 473Application options 474^^^^^^^^^^^^^^^^^^^ 475 476Supported application command line options are following:: 477 478 --verbose 479 --dev 480 --test 481 --socket_id 482 --pool_sz 483 --plcores 484 --wlcores 485 --stlist 486 --nb_flows 487 --nb_pkts 488 --worker_deq_depth 489 --fwd_latency 490 --prod_type_ethdev 491 --prod_type_timerdev_burst 492 --prod_type_timerdev 493 --timer_tick_nsec 494 --max_tmo_nsec 495 --expiry_nsec 496 --nb_timers 497 --nb_timer_adptrs 498 --deq_tmo_nsec 499 500Example 501^^^^^^^ 502 503Example command to run perf ``all types queue`` test: 504 505.. code-block:: console 506 507 sudo build/app/dpdk-test-eventdev --vdev=event_octeontx -- \ 508 --test=perf_atq --plcores=2 --wlcore=3 --stlist=p --nb_pkts=0 509 510Example command to run perf ``all types queue`` test with event timer adapter: 511 512.. code-block:: console 513 514 sudo build/app/dpdk-test-eventdev --vdev="event_octeontx" -- \ 515 --wlcores 4 --plcores 12 --test perf_atq --verbose 20 \ 516 --stlist=a --prod_type_timerdev --fwd_latency 517 518 519PIPELINE_QUEUE Test 520~~~~~~~~~~~~~~~~~~~ 521 522This is a pipeline test case that aims at testing the following: 523 524#. Measure the end-to-end performance of an event dev with a ethernet dev. 525#. Maintain packet ordering from Rx to Tx. 526 527.. _table_eventdev_pipeline_queue_test: 528 529.. table:: Pipeline queue test eventdev configuration. 530 531 +---+--------------+----------------+-----------------------------------------+ 532 | # | Items | Value | Comments | 533 | | | | | 534 +===+==============+================+=========================================+ 535 | 1 | nb_queues | (nb_producers | Queues will be configured based on the | 536 | | | * nb_stages) + | user requested sched type list(--stlist)| 537 | | | nb_producers | At the last stage of the schedule list | 538 | | | | the event is enqueued onto per port | 539 | | | | unique queue which is then Transmitted. | 540 +---+--------------+----------------+-----------------------------------------+ 541 | 2 | nb_producers | >= 1 | Producers will be configured based on | 542 | | | | the number of detected ethernet devices.| 543 | | | | Each ethdev will be configured as an Rx | 544 | | | | adapter. | 545 +---+--------------+----------------+-----------------------------------------+ 546 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 547 | | | | argument | 548 +---+--------------+----------------+-----------------------------------------+ 549 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n. | 550 | | | (nb_produces * | Producers use port n+1 to port n+m, | 551 | | | 2) | depending on the Rx adapter capability. | 552 | | | | Consumers use port n+m+1 to port n+o | 553 | | | | depending on the Tx adapter capability. | 554 +---+--------------+----------------+-----------------------------------------+ 555 556.. _figure_eventdev_pipeline_queue_test_generic: 557 558.. figure:: img/eventdev_pipeline_queue_test_generic.* 559 560.. _figure_eventdev_pipeline_queue_test_internal_port: 561 562.. figure:: img/eventdev_pipeline_queue_test_internal_port.* 563 564 pipeline queue test operation. 565 566The pipeline queue test configures the eventdev with Q queues and P ports, 567where Q and P is a function of the number of workers, the number of producers 568and number of stages as mentioned in :numref:`table_eventdev_pipeline_queue_test`. 569 570The user can choose the number of workers and number of stages through the 571``--wlcores`` and the ``--stlist`` application command line arguments 572respectively. 573 574The number of producers depends on the number of ethernet devices detected and 575each ethernet device is configured as a event_eth_rx_adapter that acts as a 576producer. 577 578The producer(s) injects the events to eventdev based the first stage sched type 579list requested by the user through ``--stlist`` the command line argument. 580 581Based on the number of stages to process(selected through ``--stlist``), 582The application forwards the event to next upstream queue and when it reaches 583the last stage in the pipeline if the event type is ``atomic`` it is enqueued 584onto ethdev Tx queue else to maintain ordering the event type is set to 585``atomic`` and enqueued onto the last stage queue. 586 587If the ethdev and eventdev pair have ``RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT`` 588capability then the worker cores enqueue the packets to the eventdev directly 589using ``rte_event_eth_tx_adapter_enqueue`` else the worker cores enqueue the 590packet onto the ``SINGLE_LINK_QUEUE`` that is managed by the Tx adapter. 591The Tx adapter dequeues the packet and transmits it. 592 593On packet Tx, application increments the number events processed and print 594periodically in one second to get the number of events processed in one 595second. 596 597 598Application options 599^^^^^^^^^^^^^^^^^^^ 600 601Supported application command line options are following:: 602 603 --verbose 604 --dev 605 --test 606 --socket_id 607 --pool_sz 608 --wlcores 609 --stlist 610 --worker_deq_depth 611 --prod_type_ethdev 612 --deq_tmo_nsec 613 614 615.. Note:: 616 617 * The ``--prod_type_ethdev`` is mandatory for running this test. 618 619Example 620^^^^^^^ 621 622Example command to run pipeline queue test: 623 624.. code-block:: console 625 626 sudo build/app/dpdk-test-eventdev -c 0xf -s 0x8 --vdev=event_sw0 -- \ 627 --test=pipeline_queue --wlcore=1 --prod_type_ethdev --stlist=a 628 629 630PIPELINE_ATQ Test 631~~~~~~~~~~~~~~~~~~~ 632 633This is a pipeline test case that aims at testing the following with 634``all types queue`` eventdev scheme. 635 636#. Measure the end-to-end performance of an event dev with a ethernet dev. 637#. Maintain packet ordering from Rx to Tx. 638 639.. _table_eventdev_pipeline_atq_test: 640 641.. table:: Pipeline atq test eventdev configuration. 642 643 +---+--------------+----------------+-----------------------------------------+ 644 | # | Items | Value | Comments | 645 | | | | | 646 +===+==============+================+=========================================+ 647 | 1 | nb_queues | nb_producers + | Queues will be configured based on the | 648 | | | x | user requested sched type list(--stlist)| 649 | | | | where x = nb_producers in generic | 650 | | | | pipeline and 0 if all the ethdev | 651 | | | | being used have Internal port capability| 652 +---+--------------+----------------+-----------------------------------------+ 653 | 2 | nb_producers | >= 1 | Producers will be configured based on | 654 | | | | the number of detected ethernet devices.| 655 | | | | Each ethdev will be configured as an Rx | 656 | | | | adapter. | 657 +---+--------------+----------------+-----------------------------------------+ 658 | 3 | nb_workers | >= 1 | Selected through --wlcores command line | 659 | | | | argument | 660 +---+--------------+----------------+-----------------------------------------+ 661 | 4 | nb_ports | nb_workers + | Workers use port 0 to port n. | 662 | | | nb_producers + | Producers use port n+1 to port n+m, | 663 | | | x | depending on the Rx adapter capability. | 664 | | | | x = nb_producers in generic pipeline and| 665 | | | | 0 if all the ethdev being used have | 666 | | | | Internal port capability. | 667 | | | | Consumers may use port n+m+1 to port n+o| 668 | | | | depending on the Tx adapter capability. | 669 +---+--------------+----------------+-----------------------------------------+ 670 671.. _figure_eventdev_pipeline_atq_test_generic: 672 673.. figure:: img/eventdev_pipeline_atq_test_generic.* 674 675.. _figure_eventdev_pipeline_atq_test_internal_port: 676 677.. figure:: img/eventdev_pipeline_atq_test_internal_port.* 678 679 pipeline atq test operation. 680 681The pipeline atq test configures the eventdev with Q queues and P ports, 682where Q and P is a function of the number of workers, the number of producers 683and number of stages as mentioned in :numref:`table_eventdev_pipeline_atq_test`. 684 685The atq queue test functions as same as ``pipeline_queue`` test. The difference 686is, It uses, ``all type queue scheme`` instead of separate queues for each 687stage and thus reduces the number of queues required to realize the use case. 688 689 690Application options 691^^^^^^^^^^^^^^^^^^^ 692 693Supported application command line options are following:: 694 695 --verbose 696 --dev 697 --test 698 --socket_id 699 --pool_sz 700 --wlcores 701 --stlist 702 --worker_deq_depth 703 --prod_type_ethdev 704 --deq_tmo_nsec 705 706 707.. Note:: 708 709 * The ``--prod_type_ethdev`` is mandatory for running this test. 710 711Example 712^^^^^^^ 713 714Example command to run pipeline queue test: 715 716.. code-block:: console 717 718 sudo build/app/dpdk-test-eventdev -c 0xf -s 0x8 --vdev=event_sw0 -- \ 719 --test=pipeline_atq --wlcore=1 --prod_type_ethdev --stlist=a 720