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 (*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 http://dpdk.org/doc. 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 The following tests can be run: 74 75 * unittest 76 Small unit tests witch check basic functionality of bbdev library. 77 * latency 78 Test calculates three latency metrics: 79 80 * offload_latency_tc 81 measures the cost of offloading enqueue and dequeue operations. 82 * offload_latency_empty_q_tc 83 measures the cost of offloading a dequeue operation from an empty queue. 84 checks how long last dequeueing if there is no operations to dequeue 85 * operation_latency_tc 86 measures the time difference from the first attempt to enqueue till the 87 first successful dequeue. 88 * validation 89 Test do enqueue on given vector and compare output after dequeueing. 90 * throughput 91 Test measures the achieved throughput on the available lcores. 92 Results are printed in million operations per second and million bits per second. 93 * interrupt 94 The same test as 'throughput' but uses interrupts instead of PMD to perform 95 the dequeue. 96 97 **Example usage:** 98 99 ``./test-bbdev.py -c validation`` 100 Runs validation test suite 101 102 ``./test-bbdev.py -c latency throughput`` 103 Runs latency and throughput test suites 104 105``-v TEST_VECTOR [TEST_VECTOR ...], --test_vector TEST_VECTOR [TEST_VECTOR ...]`` 106 Specifies paths to the test vector files. If not specified path is set based 107 on *$RTE_SDK* environment variable concatenated with 108 "*/app/test-bbdev/test_vectors/bbdev_vector_null.data*" and indicates default 109 data file. 110 111 **Example usage:** 112 113 ``./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_td_test1.data`` 114 Fills vector based on bbdev_vector_td_test1.data file and runs all tests 115 116 ``./test-bbdev.py -v bbdev_vector_td_test1.data bbdev_vector_te_test2.data`` 117 The bbdev test app is executed twice. First time vector is filled based on 118 *bbdev_vector_td_test1.data* file and second time based on 119 *bbdev_vector_te_test2.data* file. For both executions all tests are run. 120 121``-n NUM_OPS, --num_ops NUM_OPS`` 122 Specifies number of operations to process on device. If not specified num_ops 123 is set to 32 operations. 124 125``-l NUM_LCORES, --num_lcores NUM_LCORES`` 126 Specifies number of lcores to run. If not specified num_lcores is set 127 according to value from RTE configuration (EAL coremask) 128 129``-b BURST_SIZE [BURST_SIZE ...], --burst-size BURST_SIZE [BURST_SIZE ...]`` 130 Specifies operations enqueue/dequeue burst size. If not specified burst_size is 131 set to 32. Maximum is 512. 132 133 134Parameter globbing 135~~~~~~~~~~~~~~~~~~ 136 137Thanks to the globbing functionality in python test-bbdev.py script allows to 138run tests with different set of vector files without giving all of them explicitly. 139 140**Example usage:** 141 142.. code-block:: console 143 144 ./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_*.data 145 146It runs all tests with following vectors: 147 148- ``bbdev_vector_null.data`` 149 150- ``bbdev_vector_td_default.data`` 151 152- ``bbdev_vector_te_default.data`` 153 154 155.. code-block:: console 156 157 ./test-bbdev.py -v app/test-bbdev/test_vectors/bbdev_vector_t?_default.data 158 159It runs all tests with "default" vectors: 160 161- ``bbdev_vector_te_default.data`` 162 163- ``bbdev_vector_td_default.data`` 164 165 166Running Tests 167------------- 168 169Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for 170x86_64-native-linuxapp-icc target: 171 172:: 173 174 |-- app 175 |-- test-bbdev 176 |-- test_vectors 177 |-- bbdev_vector_null.data 178 |-- bbdev_vector_td_default.data 179 |-- bbdev_vector_te_default.data 180 181 |-- x86_64-native-linuxapp-icc 182 |-- app 183 |-- testbbdev 184 185All bbdev devices 186~~~~~~~~~~~~~~~~~ 187 188.. code-block:: console 189 190 ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev 191 -v ./test_vectors/bbdev_vector_td_default.data 192 193It runs all available tests using the test vector filled based on 194*bbdev_vector_td_default.data* file. 195By default number of operations to process on device is set to 32, timeout is 196set to 300s and operations enqueue/dequeue burst size is set to 32. 197Moreover a bbdev (*bbdev_null*) device will be created. 198 199bbdev turbo_sw device 200~~~~~~~~~~~~~~~~~~~~~ 201 202.. code-block:: console 203 204 ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev 205 -e="--vdev=turbo_sw" -t 120 -c validation 206 -v ./test_vectors/bbdev_vector_t?_default.data -n 64 -b 8 32 207 208It runs **validation** test for each vector file that matches the given pattern. 209Number of operations to process on device is set to 64 and operations timeout is 210set to 120s and enqueue/dequeue burst size is set to 8 and to 32. 211Moreover a bbdev (*turbo_sw*) device will be created. 212 213 214bbdev null device 215~~~~~~~~~~~~~~~~~ 216 217Executing bbdev null device with *bbdev_vector_null.data* helps in measuring the 218overhead introduced by the bbdev framework. 219 220.. code-block:: console 221 222 ./test-bbdev.py -e="--vdev=bbdev_null0" 223 -v ./test_vectors/bbdev_vector_null.data 224 225**Note:** 226 227bbdev_null device does not have to be defined explicitly as it is created by default. 228 229 230 231Test Vector files 232================= 233 234Test Vector files contain the data which is used to set turbo decoder/encoder 235parameters and buffers for validation purpose. New test vector files should be 236stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of 237the syntax of the test vector files is in the following section. 238 239 240Basic principles for test vector files 241-------------------------------------- 242Line started with ``#`` is treated as a comment and is ignored. 243 244If variable is a chain of values, values should be separated by a comma. If 245assignment is split into several lines, each line (except the last one) has to 246be ended with a comma. 247There is no comma after last value in last line. Correct assignment should 248look like the following: 249 250.. parsed-literal:: 251 252 variable = 253 value, value, value, value, 254 value, value 255 256In case where variable is a single value correct assignment looks like the 257following: 258 259.. parsed-literal:: 260 261 variable = 262 value 263 264Length of chain variable is calculated by parser. Can not be defined 265explicitly. 266 267Variable op_type has to be defined as a first variable in file. It specifies 268what type of operations will be executed. For decoder op_type has to be set to 269``RTE_BBDEV_OP_TURBO_DEC`` and for encoder to ``RTE_BBDEV_OP_TURBO_ENC``. 270 271Full details of the meaning and valid values for the below fields are 272documented in *rte_bbdev_op.h* 273 274 275Turbo decoder test vectors template 276----------------------------------- 277 278For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC`` 279 280.. parsed-literal:: 281 282 op_type = 283 RTE_BBDEV_OP_TURBO_DEC 284 285Chain of uint32_t values. Note that it is possible to define more than one 286input/output entries which will result in chaining two or more data structures 287for *segmented Transport Blocks* 288 289.. parsed-literal:: 290 291 input0 = 292 0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100, 293 0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00 294 295Chain of uint32_t values 296 297.. parsed-literal:: 298 299 input1 = 300 0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 301 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000 302 303Chain of uint32_t values 304 305.. parsed-literal:: 306 307 input2 = 308 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 309 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000 310 311Chain of uint32_t values 312 313.. parsed-literal:: 314 315 hard_output0 = 316 0xa7d6732e 317 318Chain of uint32_t values 319 320.. parsed-literal:: 321 322 hard_output1 = 323 0xa61 324 325Chain of uint32_t values 326 327.. parsed-literal:: 328 329 soft_output0 = 330 0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f 331 332Chain of uint32_t values 333 334.. parsed-literal:: 335 336 soft_output1 = 337 0x817f7f81, 0x7f7f7f81, 0x7f7f8181 338 339uint32_t value 340 341.. parsed-literal:: 342 343 e = 344 44 345 346uint16_t value 347 348.. parsed-literal:: 349 350 k = 351 40 352 353uint8_t value 354 355.. parsed-literal:: 356 357 rv_index = 358 0 359 360uint8_t value 361 362.. parsed-literal:: 363 364 iter_max = 365 8 366 367uint8_t value 368 369.. parsed-literal:: 370 371 iter_min = 372 4 373 374uint8_t value 375 376.. parsed-literal:: 377 378 expected_iter_count = 379 8 380 381uint8_t value 382 383.. parsed-literal:: 384 385 ext_scale = 386 15 387 388uint8_t value 389 390.. parsed-literal:: 391 392 num_maps = 393 0 394 395Chain of flags for turbo decoder operation. Following flags can be used: 396 397- ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` 398 399- ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` 400 401- ``RTE_BBDEV_TURBO_EQUALIZER`` 402 403- ``RTE_BBDEV_TURBO_SOFT_OUT_SATURATE`` 404 405- ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN`` 406 407- ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH`` 408 409- ``RTE_BBDEV_TURBO_SOFT_OUTPUT`` 410 411- ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` 412 413- ``RTE_BBDEV_TURBO_DEC_INTERRUPTS`` 414 415- ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` 416 417- ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` 418 419- ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT`` 420 421- ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT`` 422 423- ``RTE_BBDEV_TURBO_MAP_DEC`` 424 425Example: 426 427 .. parsed-literal:: 428 429 op_flags = 430 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER, 431 RTE_BBDEV_TURBO_SOFT_OUTPUT 432 433Chain of operation statuses that are expected after operation is performed. 434Following statuses can be used: 435 436- ``DMA`` 437 438- ``FCW`` 439 440- ``CRC`` 441 442- ``OK`` 443 444``OK`` means no errors are expected. Cannot be used with other values. 445 446.. parsed-literal:: 447 448 expected_status = 449 FCW, CRC 450 451 452Turbo encoder test vectors template 453----------------------------------- 454 455For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC`` 456 457.. parsed-literal:: 458 459 op_type = 460 RTE_BBDEV_OP_TURBO_ENC 461 462Chain of uint32_t values 463 464.. parsed-literal:: 465 466 input0 = 467 0x11d2bcac, 0x4d 468 469Chain of uint32_t values 470 471.. parsed-literal:: 472 473 output0 = 474 0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29, 475 0xa25b7f47, 0x2aa224ce, 0x79f2 476 477uint32_t value 478 479.. parsed-literal:: 480 481 e = 482 272 483 484uint16_t value 485 486.. parsed-literal:: 487 488 k = 489 40 490 491uint16_t value 492 493.. parsed-literal:: 494 495 ncb = 496 192 497 498uint8_t value 499 500.. parsed-literal:: 501 502 rv_index = 503 0 504 505Chain of flags for turbo encoder operation. Following flags can be used: 506 507- ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` 508 509- ``RTE_BBDEV_TURBO_RATE_MATCH`` 510 511- ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` 512 513- ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` 514 515- ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` 516 517``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to 518force the input data to be memory split and formed as a segmented mbuf. 519 520 521.. parsed-literal:: 522 523 op_flags = 524 RTE_BBDEV_TURBO_RATE_MATCH 525 526Chain of operation statuses that are expected after operation is performed. 527Following statuses can be used: 528 529- ``DMA`` 530 531- ``FCW`` 532 533- ``OK`` 534 535``OK`` means no errors are expected. Cannot be used with other values. 536 537.. parsed-literal:: 538 539 expected_status = 540 OK 541