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
  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  **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
 109 Test Cases
 110 ~~~~~~~~~~
 111
 112 There 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 measurment 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
 156 Parameter Globbing
 157 ~~~~~~~~~~~~~~~~~~
 158
 159 Thanks to the globbing functionality in python test-bbdev.py script allows to
 160 run 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
 168 It 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
 216 It 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
 225 Running Tests
 226 -------------
 227
 228 Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for
 229 x86_64-native-linuxapp-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-linuxapp-icc
 259      |-- app
 260          |-- testbbdev
 261
 262 All bbdev devices
 263 ~~~~~~~~~~~~~~~~~
 264
 265 .. code-block:: console
 266
 267   ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
 268   -v turbo_dec_default.data
 269
 270 It runs all available tests using the test vector filled based on
 271 *turbo_dec_default.data* file.
 272 By default number of operations to process on device is set to 32, timeout is
 273 set to 300s and operations enqueue/dequeue burst size is set to 32.
 274 Moreover a bbdev (*baseband_null*) device will be created.
 275
 276 baseband turbo_sw device
 277 ~~~~~~~~~~~~~~~~~~~~~~~~
 278
 279 .. code-block:: console
 280
 281   ./test-bbdev.py -p ../../x86_64-native-linuxapp-icc/app/testbbdev
 282   -e="--vdev=baseband_turbo_sw" -t 120 -c validation
 283   -v ./test_vectors/turbo_* -n 64 -b 8 32
 284
 285 It runs **validation** test for each vector file that matches the given pattern.
 286 Number of operations to process on device is set to 64 and operations timeout is
 287 set to 120s and enqueue/dequeue burst size is set to 8 and to 32.
 288 Moreover a bbdev (*baseband_turbo_sw*) device will be created.
 289
 290
 291 bbdev null device
 292 ~~~~~~~~~~~~~~~~~
 293
 294 Executing bbdev null device with *bbdev_null.data* helps in measuring the
 295 overhead 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
 304 baseband_null device does not have to be defined explicitly as it is created by default.
 305
 306
 307
 308 Test Vector files
 309 =================
 310
 311 Test Vector files contain the data which is used to set turbo decoder/encoder
 312 parameters and buffers for validation purpose. New test vector files should be
 313 stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of
 314 the syntax of the test vector files is in the following section.
 315
 316
 317 Basic principles for test vector files
 318 --------------------------------------
 319 Line started with ``#`` is treated as a comment and is ignored.
 320
 321 If variable is a chain of values, values should be separated by a comma. If
 322 assignment is split into several lines, each line (except the last one) has to
 323 be ended with a comma.
 324 There is no comma after last value in last line. Correct assignment should
 325 look like the following:
 326
 327 .. parsed-literal::
 328
 329  variable =
 330  value, value, value, value,
 331  value, value
 332
 333 In case where variable is a single value correct assignment looks like the
 334 following:
 335
 336 .. parsed-literal::
 337
 338  variable =
 339  value
 340
 341 Length of chain variable is calculated by parser. Can not be defined
 342 explicitly.
 343
 344 Variable op_type has to be defined as a first variable in file. It specifies
 345 what 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
 348 Full details of the meaning and valid values for the below fields are
 349 documented in *rte_bbdev_op.h*
 350
 351
 352 Turbo decoder test vectors template
 353 -----------------------------------
 354
 355 For 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
 362 Chain of uint32_t values. Note that it is possible to define more than one
 363 input/output entries which will result in chaining two or more data structures
 364 for *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
 372 Chain 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
 380 Chain 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
 388 Chain of uint32_t values
 389
 390 .. parsed-literal::
 391
 392     hard_output0 =
 393     0xa7d6732e
 394
 395 Chain of uint32_t values
 396
 397 .. parsed-literal::
 398
 399     hard_output1 =
 400     0xa61
 401
 402 Chain of uint32_t values
 403
 404 .. parsed-literal::
 405
 406     soft_output0 =
 407     0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f
 408
 409 Chain of uint32_t values
 410
 411 .. parsed-literal::
 412
 413     soft_output1 =
 414     0x817f7f81, 0x7f7f7f81, 0x7f7f8181
 415
 416 uint32_t value
 417
 418 .. parsed-literal::
 419
 420     e =
 421     44
 422
 423 uint16_t value
 424
 425 .. parsed-literal::
 426
 427     k =
 428     40
 429
 430 uint8_t value
 431
 432 .. parsed-literal::
 433
 434     rv_index =
 435     0
 436
 437 uint8_t value
 438
 439 .. parsed-literal::
 440
 441     iter_max =
 442     8
 443
 444 uint8_t value
 445
 446 .. parsed-literal::
 447
 448     iter_min =
 449     4
 450
 451 uint8_t value
 452
 453 .. parsed-literal::
 454
 455     expected_iter_count =
 456     8
 457
 458 uint8_t value
 459
 460 .. parsed-literal::
 461
 462     ext_scale =
 463     15
 464
 465 uint8_t value
 466
 467 .. parsed-literal::
 468
 469     num_maps =
 470     0
 471
 472 Chain 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
 502 Example:
 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
 510 Chain of operation statuses that are expected after operation is performed.
 511 Following 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
 529 Turbo encoder test vectors template
 530 -----------------------------------
 531
 532 For 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
 539 Chain of uint32_t values
 540
 541 .. parsed-literal::
 542
 543     input0 =
 544     0x11d2bcac, 0x4d
 545
 546 Chain of uint32_t values
 547
 548 .. parsed-literal::
 549
 550     output0 =
 551     0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29,
 552     0xa25b7f47, 0x2aa224ce, 0x79f2
 553
 554 uint32_t value
 555
 556 .. parsed-literal::
 557
 558     e =
 559     272
 560
 561 uint16_t value
 562
 563 .. parsed-literal::
 564
 565     k =
 566     40
 567
 568 uint16_t value
 569
 570 .. parsed-literal::
 571
 572     ncb =
 573     192
 574
 575 uint8_t value
 576
 577 .. parsed-literal::
 578
 579     rv_index =
 580     0
 581
 582 Chain 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
 595 force 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
 603 Chain of operation statuses that are expected after operation is performed.
 604 Following 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