doc/guides/tools/testbbdev.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation
   3
   4 dpdk-test-bbdev Application
   5 ===========================
   6
   7 The ``dpdk-test-bbdev`` tool is a Data Plane Development Kit (DPDK) utility that
   8 allows measuring performance parameters of PMDs available in the bbdev framework.
   9 Available tests available for execution are: latency, throughput, validation and
  10 sanity tests. Execution of tests can be customized using various parameters
  11 passed to a python running script.
  12
  13 Compiling the Application
  14 -------------------------
  15
  16 **Step 1: PMD setting**
  17
  18 The ``dpdk-test-bbdev`` tool depends on crypto device drivers PMD which
  19 are disabled by default in the build configuration file ``common_base``.
  20 The bbdevice drivers PMD which should be tested can be enabled by setting
  21
  22    ``CONFIG_RTE_LIBRTE_PMD_<name>=y``
  23
  24 Setting example for (*turbo_sw*) PMD
  25
  26    ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y``
  27
  28 **Step 2: Build the application**
  29
  30 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
  31 ``dpdk-test-bbdev`` application.
  32
  33 Initially, the user must select a DPDK target to choose the correct target type
  34 and compiler options to use when building the libraries.
  35 The user must have all libraries, modules, updates and compilers installed
  36 in the system prior to this, as described in the earlier chapters in this
  37 Getting Started Guide.
  38
  39 Running the Application
  40 -----------------------
  41
  42 The 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
  51 command-line Options
  52 ~~~~~~~~~~~~~~~~~~~~
  53
  54 The 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_null.data*" and indicates default
 109  data file.
 110
 111  **Example usage:**
 112
 113  ``./test-bbdev.py -v app/test-bbdev/test_vectors/turbo_dec_test1.data``
 114   Fills vector based on turbo_dec_test1.data file and runs all tests
 115
 116  ``./test-bbdev.py -v turbo_dec_test1.data turbo_enc_test2.data``
 117   The bbdev test app is executed twice. First time vector is filled based on
 118   *turbo_dec_test1.data* file and second time based on
 119   *turb_enc_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
 134 Parameter globbing
 135 ~~~~~~~~~~~~~~~~~~
 136
 137 Thanks to the globbing functionality in python test-bbdev.py script allows to
 138 run 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/turbo_<enc/dec>_c<c>_k<k>_r<r>_e<e>_<extra-info>.data
 145
 146 It runs all tests with following vectors:
 147
 148 - ``bbdev_null.data``
 149
 150 - ``turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data``
 151
 152 - ``turbo_enc_c1_k40_r0_e1196_rm.data``
 153
 154 - ``turbo_enc_c2_k5952_r0_e17868_crc24b.data``
 155
 156 - ``turbo_dec_c1_k40_r0_e17280_sbd_negllr.data``
 157
 158 - ``turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data``
 159
 160 - ``turbo_enc_c1_k40_r0_e272_rm.data``
 161
 162 - ``turbo_enc_c3_k4800_r2_e14412_crc24b.data``
 163
 164 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data``
 165
 166 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data``
 167
 168 - ``turbo_enc_c1_k6144_r0_e120_rm_rvidx.data``
 169
 170 - ``turbo_enc_c4_k4800_r2_e14412_crc24b.data``
 171
 172 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data``
 173
 174 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data``
 175
 176 - ``turbo_enc_c1_k6144_r0_e18444.data``
 177
 178 - ``turbo_dec_c1_k6144_r0_e34560_negllr.data``
 179
 180 - ``turbo_enc_c1_k40_r0_e1190_rm.data``
 181
 182 - ``turbo_enc_c1_k6144_r0_e18448_crc24a.data``
 183
 184 - ``turbo_dec_c1_k6144_r0_e34560_posllr.data``
 185
 186 - ``turbo_enc_c1_k40_r0_e1194_rm.data``
 187
 188 - ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data``
 189
 190 .. code-block:: console
 191
 192   ./test-bbdev.py -v app/test-bbdev/turbo_*_default.data
 193
 194 It runs all tests with "default" vectors.
 195
 196 * ``turbo_dec_default.data`` is a soft link to
 197   ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data``
 198
 199 * ``turbo_enc_default.data`` is a soft link to
 200   ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data``
 201
 202
 203 Running Tests
 204 -------------
 205
 206 Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for
 207 x86_64-native-linuxapp-icc target:
 208
 209 ::
 210
 211  |-- app
 212      |-- test-bbdev
 213          |-- test_vectors
 214              |-- bbdev_null.data
 215              |-- turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data
 216              |-- turbo_enc_c1_k40_r0_e1196_rm.data
 217              |-- turbo_enc_c2_k5952_r0_e17868_crc24b.data
 218              |-- turbo_dec_c1_k40_r0_e17280_sbd_negllr.data
 219              |-- turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data
 220              |-- turbo_enc_c1_k40_r0_e272_rm.data
 221              |-- turbo_enc_c3_k4800_r2_e14412_crc24b.data
 222              |-- turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data
 223              |-- turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data
 224              |-- turbo_enc_c1_k6144_r0_e120_rm_rvidx.data
 225              |-- turbo_enc_c4_k4800_r2_e14412_crc24b.data
 226              |-- turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data
 227              |-- turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data
 228              |-- turbo_enc_c1_k6144_r0_e18444.data
 229              |-- turbo_dec_c1_k6144_r0_e34560_negllr.data
 230              |-- turbo_enc_c1_k40_r0_e1190_rm.data
 231              |-- turbo_enc_c1_k6144_r0_e18448_crc24a.data
 232              |-- turbo_dec_c1_k6144_r0_e34560_posllr.data
 233              |-- turbo_enc_c1_k40_r0_e1194_rm.data
 234              |-- turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data
 235
 236  |-- x86_64-native-linuxapp-icc
 237      |-- app
 238          |-- testbbdev
 239
 240 All bbdev devices
 241 ~~~~~~~~~~~~~~~~~
 242
 243 .. code-block:: console
 244
 245   ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
 246   -v turbo_dec_default.data
 247
 248 It runs all available tests using the test vector filled based on
 249 *turbo_dec_default.data* file.
 250 By default number of operations to process on device is set to 32, timeout is
 251 set to 300s and operations enqueue/dequeue burst size is set to 32.
 252 Moreover a bbdev (*bbdev_null*) device will be created.
 253
 254 bbdev turbo_sw device
 255 ~~~~~~~~~~~~~~~~~~~~~
 256
 257 .. code-block:: console
 258
 259   ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
 260   -e="--vdev=turbo_sw" -t 120 -c validation
 261   -v ./test_vectors/turbo_* -n 64 -b 8 32
 262
 263 It runs **validation** test for each vector file that matches the given pattern.
 264 Number of operations to process on device is set to 64 and operations timeout is
 265 set to 120s and enqueue/dequeue burst size is set to 8 and to 32.
 266 Moreover a bbdev (*turbo_sw*) device will be created.
 267
 268
 269 bbdev null device
 270 ~~~~~~~~~~~~~~~~~
 271
 272 Executing bbdev null device with *bbdev_null.data* helps in measuring the
 273 overhead introduced by the bbdev framework.
 274
 275 .. code-block:: console
 276
 277   ./test-bbdev.py -e="--vdev=bbdev_null0"
 278   -v ./test_vectors/bbdev_null.data
 279
 280 **Note:**
 281
 282 bbdev_null device does not have to be defined explicitly as it is created by default.
 283
 284
 285
 286 Test Vector files
 287 =================
 288
 289 Test Vector files contain the data which is used to set turbo decoder/encoder
 290 parameters and buffers for validation purpose. New test vector files should be
 291 stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of
 292 the syntax of the test vector files is in the following section.
 293
 294
 295 Basic principles for test vector files
 296 --------------------------------------
 297 Line started with ``#`` is treated as a comment and is ignored.
 298
 299 If variable is a chain of values, values should be separated by a comma. If
 300 assignment is split into several lines, each line (except the last one) has to
 301 be ended with a comma.
 302 There is no comma after last value in last line. Correct assignment should
 303 look like the following:
 304
 305 .. parsed-literal::
 306
 307  variable =
 308  value, value, value, value,
 309  value, value
 310
 311 In case where variable is a single value correct assignment looks like the
 312 following:
 313
 314 .. parsed-literal::
 315
 316  variable =
 317  value
 318
 319 Length of chain variable is calculated by parser. Can not be defined
 320 explicitly.
 321
 322 Variable op_type has to be defined as a first variable in file. It specifies
 323 what type of operations will be executed. For decoder op_type has to be set to
 324 ``RTE_BBDEV_OP_TURBO_DEC`` and for encoder to ``RTE_BBDEV_OP_TURBO_ENC``.
 325
 326 Full details of the meaning and valid values for the below fields are
 327 documented in *rte_bbdev_op.h*
 328
 329
 330 Turbo decoder test vectors template
 331 -----------------------------------
 332
 333 For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC``
 334
 335 .. parsed-literal::
 336
 337     op_type =
 338     RTE_BBDEV_OP_TURBO_DEC
 339
 340 Chain of uint32_t values. Note that it is possible to define more than one
 341 input/output entries which will result in chaining two or more data structures
 342 for *segmented Transport Blocks*
 343
 344 .. parsed-literal::
 345
 346     input0 =
 347     0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100,
 348     0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00
 349
 350 Chain of uint32_t values
 351
 352 .. parsed-literal::
 353
 354     input1 =
 355     0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
 356     0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
 357
 358 Chain of uint32_t values
 359
 360 .. parsed-literal::
 361
 362     input2 =
 363     0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
 364     0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
 365
 366 Chain of uint32_t values
 367
 368 .. parsed-literal::
 369
 370     hard_output0 =
 371     0xa7d6732e
 372
 373 Chain of uint32_t values
 374
 375 .. parsed-literal::
 376
 377     hard_output1 =
 378     0xa61
 379
 380 Chain of uint32_t values
 381
 382 .. parsed-literal::
 383
 384     soft_output0 =
 385     0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f
 386
 387 Chain of uint32_t values
 388
 389 .. parsed-literal::
 390
 391     soft_output1 =
 392     0x817f7f81, 0x7f7f7f81, 0x7f7f8181
 393
 394 uint32_t value
 395
 396 .. parsed-literal::
 397
 398     e =
 399     44
 400
 401 uint16_t value
 402
 403 .. parsed-literal::
 404
 405     k =
 406     40
 407
 408 uint8_t value
 409
 410 .. parsed-literal::
 411
 412     rv_index =
 413     0
 414
 415 uint8_t value
 416
 417 .. parsed-literal::
 418
 419     iter_max =
 420     8
 421
 422 uint8_t value
 423
 424 .. parsed-literal::
 425
 426     iter_min =
 427     4
 428
 429 uint8_t value
 430
 431 .. parsed-literal::
 432
 433     expected_iter_count =
 434     8
 435
 436 uint8_t value
 437
 438 .. parsed-literal::
 439
 440     ext_scale =
 441     15
 442
 443 uint8_t value
 444
 445 .. parsed-literal::
 446
 447     num_maps =
 448     0
 449
 450 Chain of flags for turbo decoder operation. Following flags can be used:
 451
 452 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``
 453
 454 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B``
 455
 456 - ``RTE_BBDEV_TURBO_EQUALIZER``
 457
 458 - ``RTE_BBDEV_TURBO_SOFT_OUT_SATURATE``
 459
 460 - ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN``
 461
 462 - ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH``
 463
 464 - ``RTE_BBDEV_TURBO_SOFT_OUTPUT``
 465
 466 - ``RTE_BBDEV_TURBO_EARLY_TERMINATION``
 467
 468 - ``RTE_BBDEV_TURBO_DEC_INTERRUPTS``
 469
 470 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN``
 471
 472 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``
 473
 474 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT``
 475
 476 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT``
 477
 478 - ``RTE_BBDEV_TURBO_MAP_DEC``
 479
 480 Example:
 481
 482     .. parsed-literal::
 483
 484         op_flags =
 485         RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER,
 486         RTE_BBDEV_TURBO_SOFT_OUTPUT
 487
 488 Chain of operation statuses that are expected after operation is performed.
 489 Following statuses can be used:
 490
 491 - ``DMA``
 492
 493 - ``FCW``
 494
 495 - ``CRC``
 496
 497 - ``OK``
 498
 499 ``OK`` means no errors are expected. Cannot be used with other values.
 500
 501 .. parsed-literal::
 502
 503     expected_status =
 504     FCW, CRC
 505
 506
 507 Turbo encoder test vectors template
 508 -----------------------------------
 509
 510 For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC``
 511
 512 .. parsed-literal::
 513
 514     op_type =
 515     RTE_BBDEV_OP_TURBO_ENC
 516
 517 Chain of uint32_t values
 518
 519 .. parsed-literal::
 520
 521     input0 =
 522     0x11d2bcac, 0x4d
 523
 524 Chain of uint32_t values
 525
 526 .. parsed-literal::
 527
 528     output0 =
 529     0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29,
 530     0xa25b7f47, 0x2aa224ce, 0x79f2
 531
 532 uint32_t value
 533
 534 .. parsed-literal::
 535
 536     e =
 537     272
 538
 539 uint16_t value
 540
 541 .. parsed-literal::
 542
 543     k =
 544     40
 545
 546 uint16_t value
 547
 548 .. parsed-literal::
 549
 550     ncb =
 551     192
 552
 553 uint8_t value
 554
 555 .. parsed-literal::
 556
 557     rv_index =
 558     0
 559
 560 Chain of flags for turbo encoder operation. Following flags can be used:
 561
 562 - ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``
 563
 564 - ``RTE_BBDEV_TURBO_RATE_MATCH``
 565
 566 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
 567
 568 - ``RTE_BBDEV_TURBO_CRC_24A_ATTACH``
 569
 570 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``
 571
 572 ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to
 573 force the input data to be memory split and formed as a segmented mbuf.
 574
 575
 576 .. parsed-literal::
 577
 578     op_flags =
 579     RTE_BBDEV_TURBO_RATE_MATCH
 580
 581 Chain of operation statuses that are expected after operation is performed.
 582 Following statuses can be used:
 583
 584 - ``DMA``
 585
 586 - ``FCW``
 587
 588 - ``OK``
 589
 590 ``OK`` means no errors are expected. Cannot be used with other values.
 591
 592 .. parsed-literal::
 593
 594     expected_status =
 595     OK