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