1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation 3 4dpdk-test-bbdev Application 5=========================== 6 7The ``dpdk-test-bbdev`` tool is a Data Plane Development Kit (DPDK) utility that 8allows measuring performance parameters of PMDs available in the bbdev framework. 9Available tests available for execution are: latency, throughput, validation and 10sanity tests. Execution of tests can be customized using various parameters 11passed to a python running script. 12 13Compiling the Application 14------------------------- 15 16**Step 1: PMD setting** 17 18The ``dpdk-test-bbdev`` tool depends on crypto device drivers PMD which 19are disabled by default in the build configuration file ``common_base``. 20The bbdevice drivers PMD which should be tested can be enabled by setting 21 22 ``CONFIG_RTE_LIBRTE_PMD_<name>=y`` 23 24Setting example for (*baseband_turbo_sw*) PMD 25 26 ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` 27 28**Step 2: Build the application** 29 30Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the 31``dpdk-test-bbdev`` application. 32 33Initially, the user must select a DPDK target to choose the correct target type 34and compiler options to use when building the libraries. 35The user must have all libraries, modules, updates and compilers installed 36in the system prior to this, as described in the earlier chapters in this 37Getting Started Guide. 38 39Running the Application 40----------------------- 41 42The tool application has a number of command line options: 43 44.. code-block:: console 45 46 python test-bbdev.py [-h] [-p TESTAPP_PATH] [-e EAL_PARAMS] [-t TIMEOUT] 47 [-c TEST_CASE [TEST_CASE ...]] 48 [-v TEST_VECTOR [TEST_VECTOR...]] [-n NUM_OPS] 49 [-b BURST_SIZE [BURST_SIZE ...]] [-l NUM_LCORES] 50 51command-line Options 52~~~~~~~~~~~~~~~~~~~~ 53 54The following are the command-line options: 55 56``-h, --help`` 57 Shows help message and exit. 58 59``-p TESTAPP_PATH, --testapp_path TESTAPP_PATH`` 60 Indicates the path to the bbdev test app. If not specified path is set based 61 on *$RTE_SDK* environment variable concatenated with "*/build/app/testbbdev*". 62 63``-e EAL_PARAMS, --eal_params EAL_PARAMS`` 64 Specifies EAL arguments which are passed to the test app. For more details, 65 refer to DPDK documentation at :doc:`../linux_gsg/linux_eal_parameters`. 66 67``-t TIMEOUT, --timeout TIMEOUT`` 68 Specifies timeout in seconds. If not specified timeout is set to 300 seconds. 69 70``-c TEST_CASE [TEST_CASE ...], --test_cases TEST_CASE [TEST_CASE ...]`` 71 Defines test cases to run. If not specified all available tests are run. 72 73 **Example usage:** 74 75 ``./test-bbdev.py -c validation`` 76 Runs validation test suite 77 78 ``./test-bbdev.py -c latency throughput`` 79 Runs latency and throughput test suites 80 81``-v TEST_VECTOR [TEST_VECTOR ...], --test_vector TEST_VECTOR [TEST_VECTOR ...]`` 82 Specifies paths to the test vector files. If not specified path is set based 83 on *$RTE_SDK* environment variable concatenated with 84 "*/app/test-bbdev/test_vectors/bbdev_null.data*" and indicates default 85 data file. 86 87 **Example usage:** 88 89 ``./test-bbdev.py -v app/test-bbdev/test_vectors/turbo_dec_test1.data`` 90 Fills vector based on turbo_dec_test1.data file and runs all tests 91 92 ``./test-bbdev.py -v turbo_dec_test1.data turbo_enc_test2.data`` 93 The bbdev test app is executed twice. First time vector is filled based on 94 *turbo_dec_test1.data* file and second time based on 95 *turb_enc_test2.data* file. For both executions all tests are run. 96 97``-n NUM_OPS, --num_ops NUM_OPS`` 98 Specifies number of operations to process on device. If not specified num_ops 99 is set to 32 operations. 100 101``-l NUM_LCORES, --num_lcores NUM_LCORES`` 102 Specifies number of lcores to run. If not specified num_lcores is set 103 according to value from RTE configuration (EAL coremask) 104 105``-b BURST_SIZE [BURST_SIZE ...], --burst-size BURST_SIZE [BURST_SIZE ...]`` 106 Specifies operations enqueue/dequeue burst size. If not specified burst_size is 107 set to 32. Maximum is 512. 108 109Test Cases 110~~~~~~~~~~ 111 112There are 6 main test cases that can be executed using testbbdev tool: 113 114* Sanity checks [-c unittest] 115 - Performs sanity checks on BBDEV interface, validating basic functionality 116 117* Validation tests [-c validation] 118 - Performs full operation of enqueue and dequeue 119 - Compares the dequeued data buffer with a expected values in the test 120 vector (TV) being used 121 - Fails if any dequeued value does not match the data in the TV 122 123* Offload Cost measurement [-c offload] 124 - Measures the CPU cycles consumed from the receipt of a user enqueue 125 until it is put on the device queue 126 - The test measures 4 metrics 127 (a) *SW Enq Offload Cost*: Software only enqueue offload cost, the cycle 128 counts and time (us) from the point the enqueue API is called until 129 the point the operation is put on the accelerator queue. 130 (b) *Acc Enq Offload Cost*: The cycle count and time (us) from the 131 point the operation is put on the accelerator queue until the return 132 from enqueue. 133 (c) *SW Deq Offload Cost*: Software dequeue cost, the cycle counts and 134 time (us) consumed to dequeue one operation. 135 (d) *Empty Queue Enq Offload Cost*: The cycle count and time (us) 136 consumed to dequeue from an empty queue. 137 138* Latency measurement [-c latency] 139 - Measures the time consumed from the first enqueue until the first 140 appearance of a dequeued result 141 - This measurement represents the full latency of a bbdev operation 142 (encode or decode) to execute 143 144* Poll-mode Throughput measurement [-c throughput] 145 - Performs full operation of enqueue and dequeue 146 - Executes in poll mode 147 - Measures the achieved throughput on a subset or all available CPU cores 148 - Dequeued data is not validated against expected values stored in TV 149 - Results are printed in million operations per second and million bits 150 per second 151 152* Interrupt-mode Throughput [-c interrupt] 153 - Similar to Throughput test case, but using interrupts. No polling. 154 155 156Parameter Globbing 157~~~~~~~~~~~~~~~~~~ 158 159Thanks to the globbing functionality in python test-bbdev.py script allows to 160run tests with different set of vector files without giving all of them explicitly. 161 162**Example usage:** 163 164.. code-block:: console 165 166 ./test-bbdev.py -v app/test-bbdev/test_vectors/turbo_<enc/dec>_c<c>_k<k>_r<r>_e<e>_<extra-info>.data 167 168It runs all tests with following vectors: 169 170- ``bbdev_null.data`` 171 172- ``turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data`` 173 174- ``turbo_enc_c1_k40_r0_e1196_rm.data`` 175 176- ``turbo_enc_c2_k5952_r0_e17868_crc24b.data`` 177 178- ``turbo_dec_c1_k40_r0_e17280_sbd_negllr.data`` 179 180- ``turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data`` 181 182- ``turbo_enc_c1_k40_r0_e272_rm.data`` 183 184- ``turbo_enc_c3_k4800_r2_e14412_crc24b.data`` 185 186- ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data`` 187 188- ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data`` 189 190- ``turbo_enc_c1_k6144_r0_e120_rm_rvidx.data`` 191 192- ``turbo_enc_c4_k4800_r2_e14412_crc24b.data`` 193 194- ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data`` 195 196- ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data`` 197 198- ``turbo_enc_c1_k6144_r0_e18444.data`` 199 200- ``turbo_dec_c1_k6144_r0_e34560_negllr.data`` 201 202- ``turbo_enc_c1_k40_r0_e1190_rm.data`` 203 204- ``turbo_enc_c1_k6144_r0_e18448_crc24a.data`` 205 206- ``turbo_dec_c1_k6144_r0_e34560_posllr.data`` 207 208- ``turbo_enc_c1_k40_r0_e1194_rm.data`` 209 210- ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data`` 211 212.. code-block:: console 213 214 ./test-bbdev.py -v app/test-bbdev/turbo_*_default.data 215 216It runs all tests with "default" vectors. 217 218* ``turbo_dec_default.data`` is a soft link to 219 ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data`` 220 221* ``turbo_enc_default.data`` is a soft link to 222 ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data`` 223 224 225Running Tests 226------------- 227 228Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for 229x86_64-native-linux-icc target: 230 231:: 232 233 |-- app 234 |-- test-bbdev 235 |-- test_vectors 236 |-- bbdev_null.data 237 |-- turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data 238 |-- turbo_enc_c1_k40_r0_e1196_rm.data 239 |-- turbo_enc_c2_k5952_r0_e17868_crc24b.data 240 |-- turbo_dec_c1_k40_r0_e17280_sbd_negllr.data 241 |-- turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data 242 |-- turbo_enc_c1_k40_r0_e272_rm.data 243 |-- turbo_enc_c3_k4800_r2_e14412_crc24b.data 244 |-- turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data 245 |-- turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data 246 |-- turbo_enc_c1_k6144_r0_e120_rm_rvidx.data 247 |-- turbo_enc_c4_k4800_r2_e14412_crc24b.data 248 |-- turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data 249 |-- turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data 250 |-- turbo_enc_c1_k6144_r0_e18444.data 251 |-- turbo_dec_c1_k6144_r0_e34560_negllr.data 252 |-- turbo_enc_c1_k40_r0_e1190_rm.data 253 |-- turbo_enc_c1_k6144_r0_e18448_crc24a.data 254 |-- turbo_dec_c1_k6144_r0_e34560_posllr.data 255 |-- turbo_enc_c1_k40_r0_e1194_rm.data 256 |-- turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data 257 258 |-- x86_64-native-linux-icc 259 |-- app 260 |-- testbbdev 261 262All bbdev devices 263~~~~~~~~~~~~~~~~~ 264 265.. code-block:: console 266 267 ./test-bbdev.py -p ../../x86_64-native-linux-icc/app/testbbdev 268 -v turbo_dec_default.data 269 270It runs all available tests using the test vector filled based on 271*turbo_dec_default.data* file. 272By default number of operations to process on device is set to 32, timeout is 273set to 300s and operations enqueue/dequeue burst size is set to 32. 274Moreover a bbdev (*baseband_null*) device will be created. 275 276baseband turbo_sw device 277~~~~~~~~~~~~~~~~~~~~~~~~ 278 279.. code-block:: console 280 281 ./test-bbdev.py -p ../../x86_64-native-linux-icc/app/testbbdev 282 -e="--vdev=baseband_turbo_sw" -t 120 -c validation 283 -v ./test_vectors/turbo_* -n 64 -b 8 32 284 285It runs **validation** test for each vector file that matches the given pattern. 286Number of operations to process on device is set to 64 and operations timeout is 287set to 120s and enqueue/dequeue burst size is set to 8 and to 32. 288Moreover a bbdev (*baseband_turbo_sw*) device will be created. 289 290 291bbdev null device 292~~~~~~~~~~~~~~~~~ 293 294Executing bbdev null device with *bbdev_null.data* helps in measuring the 295overhead introduced by the bbdev framework. 296 297.. code-block:: console 298 299 ./test-bbdev.py -e="--vdev=baseband_null0" 300 -v ./test_vectors/bbdev_null.data 301 302**Note:** 303 304baseband_null device does not have to be defined explicitly as it is created by default. 305 306 307 308Test Vector files 309----------------- 310 311Test Vector files contain the data which is used to set turbo decoder/encoder 312parameters and buffers for validation purpose. New test vector files should be 313stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of 314the syntax of the test vector files is in the following section. 315 316 317Basic principles for test vector files 318~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 319Line started with ``#`` is treated as a comment and is ignored. 320 321If variable is a chain of values, values should be separated by a comma. If 322assignment is split into several lines, each line (except the last one) has to 323be ended with a comma. 324There is no comma after last value in last line. Correct assignment should 325look like the following: 326 327.. parsed-literal:: 328 329 variable = 330 value, value, value, value, 331 value, value 332 333In case where variable is a single value correct assignment looks like the 334following: 335 336.. parsed-literal:: 337 338 variable = 339 value 340 341Length of chain variable is calculated by parser. Can not be defined 342explicitly. 343 344Variable op_type has to be defined as a first variable in file. It specifies 345what type of operations will be executed. For decoder op_type has to be set to 346``RTE_BBDEV_OP_TURBO_DEC`` and for encoder to ``RTE_BBDEV_OP_TURBO_ENC``. 347 348Full details of the meaning and valid values for the below fields are 349documented in *rte_bbdev_op.h* 350 351 352Turbo decoder test vectors template 353~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 354 355For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC`` 356 357.. parsed-literal:: 358 359 op_type = 360 RTE_BBDEV_OP_TURBO_DEC 361 362Chain of uint32_t values. Note that it is possible to define more than one 363input/output entries which will result in chaining two or more data structures 364for *segmented Transport Blocks* 365 366.. parsed-literal:: 367 368 input0 = 369 0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100, 370 0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00 371 372Chain of uint32_t values 373 374.. parsed-literal:: 375 376 input1 = 377 0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 378 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000 379 380Chain of uint32_t values 381 382.. parsed-literal:: 383 384 input2 = 385 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 386 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000 387 388Chain of uint32_t values 389 390.. parsed-literal:: 391 392 hard_output0 = 393 0xa7d6732e 394 395Chain of uint32_t values 396 397.. parsed-literal:: 398 399 hard_output1 = 400 0xa61 401 402Chain of uint32_t values 403 404.. parsed-literal:: 405 406 soft_output0 = 407 0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f 408 409Chain of uint32_t values 410 411.. parsed-literal:: 412 413 soft_output1 = 414 0x817f7f81, 0x7f7f7f81, 0x7f7f8181 415 416uint32_t value 417 418.. parsed-literal:: 419 420 e = 421 44 422 423uint16_t value 424 425.. parsed-literal:: 426 427 k = 428 40 429 430uint8_t value 431 432.. parsed-literal:: 433 434 rv_index = 435 0 436 437uint8_t value 438 439.. parsed-literal:: 440 441 iter_max = 442 8 443 444uint8_t value 445 446.. parsed-literal:: 447 448 iter_min = 449 4 450 451uint8_t value 452 453.. parsed-literal:: 454 455 expected_iter_count = 456 8 457 458uint8_t value 459 460.. parsed-literal:: 461 462 ext_scale = 463 15 464 465uint8_t value 466 467.. parsed-literal:: 468 469 num_maps = 470 0 471 472Chain of flags for turbo decoder operation. Following flags can be used: 473 474- ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` 475 476- ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` 477 478- ``RTE_BBDEV_TURBO_EQUALIZER`` 479 480- ``RTE_BBDEV_TURBO_SOFT_OUT_SATURATE`` 481 482- ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN`` 483 484- ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH`` 485 486- ``RTE_BBDEV_TURBO_SOFT_OUTPUT`` 487 488- ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` 489 490- ``RTE_BBDEV_TURBO_DEC_INTERRUPTS`` 491 492- ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` 493 494- ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` 495 496- ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT`` 497 498- ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT`` 499 500- ``RTE_BBDEV_TURBO_MAP_DEC`` 501 502Example: 503 504 .. parsed-literal:: 505 506 op_flags = 507 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER, 508 RTE_BBDEV_TURBO_SOFT_OUTPUT 509 510Chain of operation statuses that are expected after operation is performed. 511Following statuses can be used: 512 513- ``DMA`` 514 515- ``FCW`` 516 517- ``CRC`` 518 519- ``OK`` 520 521``OK`` means no errors are expected. Cannot be used with other values. 522 523.. parsed-literal:: 524 525 expected_status = 526 FCW, CRC 527 528 529Turbo encoder test vectors template 530~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 531 532For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC`` 533 534.. parsed-literal:: 535 536 op_type = 537 RTE_BBDEV_OP_TURBO_ENC 538 539Chain of uint32_t values 540 541.. parsed-literal:: 542 543 input0 = 544 0x11d2bcac, 0x4d 545 546Chain of uint32_t values 547 548.. parsed-literal:: 549 550 output0 = 551 0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29, 552 0xa25b7f47, 0x2aa224ce, 0x79f2 553 554uint32_t value 555 556.. parsed-literal:: 557 558 e = 559 272 560 561uint16_t value 562 563.. parsed-literal:: 564 565 k = 566 40 567 568uint16_t value 569 570.. parsed-literal:: 571 572 ncb = 573 192 574 575uint8_t value 576 577.. parsed-literal:: 578 579 rv_index = 580 0 581 582Chain of flags for turbo encoder operation. Following flags can be used: 583 584- ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` 585 586- ``RTE_BBDEV_TURBO_RATE_MATCH`` 587 588- ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` 589 590- ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` 591 592- ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` 593 594``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to 595force the input data to be memory split and formed as a segmented mbuf. 596 597 598.. parsed-literal:: 599 600 op_flags = 601 RTE_BBDEV_TURBO_RATE_MATCH 602 603Chain of operation statuses that are expected after operation is performed. 604Following statuses can be used: 605 606- ``DMA`` 607 608- ``FCW`` 609 610- ``OK`` 611 612``OK`` means no errors are expected. Cannot be used with other values. 613 614.. parsed-literal:: 615 616 expected_status = 617 OK 618