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