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