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