1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2017 Intel Corporation
4 dpdk-test-bbdev Application
5 ===========================
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 Tests available for execution are: latency, throughput, validation,
10 bler and sanity tests. Execution of tests can be customized using various
11 parameters passed to a python running script.
13 Compiling the Application
14 -------------------------
16 **Step 1: PMD setting**
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
22 ``CONFIG_RTE_LIBRTE_PMD_<name>=y``
24 Setting example for (*baseband_turbo_sw*) PMD
26 ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y``
28 **Step 2: Build the application**
30 Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the
31 ``dpdk-test-bbdev`` application.
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.
39 Running the Application
40 -----------------------
42 The tool application has a number of command line options:
44 .. code-block:: console
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 ...]]
56 The following are the command-line options:
59 Shows help message and exit.
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*".
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`.
69 ``-t TIMEOUT, --timeout TIMEOUT``
70 Specifies timeout in seconds. If not specified timeout is set to 300 seconds.
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.
77 ``./test-bbdev.py -c validation``
78 Runs validation test suite
80 ``./test-bbdev.py -c latency throughput``
81 Runs latency and throughput test suites
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
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
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.
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.
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)
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.
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.
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.
122 There are 7 main test cases that can be executed using testbbdev tool:
124 * Sanity checks [-c unittest]
125 - Performs sanity checks on BBDEV interface, validating basic functionality
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
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
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.
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
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
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.
168 * Interrupt-mode Throughput [-c interrupt]
169 - Similar to Throughput test case, but using interrupts. No polling.
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.
178 **Example usage for 4G:**
180 .. code-block:: console
182 ./test-bbdev.py -v app/test-bbdev/test_vectors/turbo_<enc/dec>_c<c>_k<k>_r<r>_e<e>_<extra-info>.data
184 It runs all tests with following vectors:
186 - ``bbdev_null.data``
188 - ``turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data``
190 - ``turbo_enc_c1_k40_r0_e1196_rm.data``
192 - ``turbo_enc_c2_k5952_r0_e17868_crc24b.data``
194 - ``turbo_dec_c1_k40_r0_e17280_sbd_negllr.data``
196 - ``turbo_dec_c1_k6144_r0_e34560_sbd_posllr.data``
198 - ``turbo_enc_c1_k40_r0_e272_rm.data``
200 - ``turbo_enc_c3_k4800_r2_e14412_crc24b.data``
202 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data``
204 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data``
206 - ``turbo_enc_c1_k6144_r0_e120_rm_rvidx.data``
208 - ``turbo_enc_c4_k4800_r2_e14412_crc24b.data``
210 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data``
212 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data``
214 - ``turbo_enc_c1_k6144_r0_e18444.data``
216 - ``turbo_dec_c1_k6144_r0_e34560_negllr.data``
218 - ``turbo_enc_c1_k40_r0_e1190_rm.data``
220 - ``turbo_enc_c1_k6144_r0_e18448_crc24a.data``
222 - ``turbo_dec_c1_k6144_r0_e34560_posllr.data``
224 - ``turbo_enc_c1_k40_r0_e1194_rm.data``
226 - ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data``
228 .. code-block:: console
230 ./test-bbdev.py -v app/test-bbdev/turbo_*_default.data
232 It runs all tests with "default" vectors.
234 * ``turbo_dec_default.data`` is a soft link to
235 ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data``
237 * ``turbo_enc_default.data`` is a soft link to
238 ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data``
240 * ``ldpc_dec_default.data`` is a soft link to
241 ``ldpc_dec_v6563.data``
243 * ``ldpc_enc_default.data`` is a soft link to
244 ``ldpc_enc_c1_k8148_r0_e9372_rm.data``
249 All default reference test-vectors are stored in the test_vector
251 The prefix trivially defines which type of operation is included :
252 turbo_enc, turbo_dec, ldpc_enc, ldpc_dec.
253 The details of the configuration are captured in the file but some
254 vector name refer more explicitly processing specificity such as
255 'HARQ' when HARQ retransmission is used, 'loopback' when the data
256 is purely read/written for external DDR, lbrm when limited buffer
257 rate matching is expected, or crc_fail when a CRC failure is expected.
258 They are chosen to have a good coverage across sizes and processing
259 parameters while still keeping their number limited as part of sanity
262 Shortened tree of isg_cid-wireless_dpdk_ae with dpdk compiled for
263 x86_64-native-linux-icc target:
271 |-- x86_64-native-linux-icc
278 .. code-block:: console
280 ./test-bbdev.py -p ../../x86_64-native-linux-icc/app/testbbdev
281 -v turbo_dec_default.data
283 It runs all available tests using the test vector filled based on
284 *turbo_dec_default.data* file.
285 By default number of operations to process on device is set to 32, timeout is
286 set to 300s and operations enqueue/dequeue burst size is set to 32.
287 Moreover a bbdev (*baseband_null*) device will be created.
289 baseband turbo_sw device
290 ~~~~~~~~~~~~~~~~~~~~~~~~
292 .. code-block:: console
294 ./test-bbdev.py -p ../../x86_64-native-linux-icc/app/testbbdev
295 -e="--vdev=baseband_turbo_sw" -t 120 -c validation
296 -v ./test_vectors/* -n 64 -b 8 32
298 It runs **validation** test for each vector file that matches the given pattern.
299 Number of operations to process on device is set to 64 and operations timeout is
300 set to 120s and enqueue/dequeue burst size is set to 8 and to 32.
301 Moreover a bbdev (*baseband_turbo_sw*) device will be created.
307 Executing bbdev null device with *bbdev_null.data* helps in measuring the
308 overhead introduced by the bbdev framework.
310 .. code-block:: console
312 ./test-bbdev.py -e="--vdev=baseband_null0"
313 -v ./test_vectors/bbdev_null.data
317 baseband_null device does not have to be defined explicitly as it is created by default.
324 Test Vector files contain the data which is used to set turbo decoder/encoder
325 parameters and buffers for validation purpose. New test vector files should be
326 stored in ``app/test-bbdev/test_vectors/`` directory. Detailed description of
327 the syntax of the test vector files is in the following section.
330 Basic principles for test vector files
331 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
332 Line started with ``#`` is treated as a comment and is ignored.
334 If variable is a chain of values, values should be separated by a comma. If
335 assignment is split into several lines, each line (except the last one) has to
336 be ended with a comma.
337 There is no comma after last value in last line. Correct assignment should
338 look like the following:
343 value, value, value, value,
346 In case where variable is a single value correct assignment looks like the
354 Length of chain variable is calculated by parser. Can not be defined
357 Variable op_type has to be defined as a first variable in file. It specifies
358 what type of operations will be executed. For 4G decoder op_type has to be set to
359 ``RTE_BBDEV_OP_TURBO_DEC`` and for 4G encoder to ``RTE_BBDEV_OP_TURBO_ENC``.
361 Full details of the meaning and valid values for the below fields are
362 documented in *rte_bbdev_op.h*
365 Turbo decoder test vectors template
366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
368 For turbo decoder it has to be always set to ``RTE_BBDEV_OP_TURBO_DEC``
373 RTE_BBDEV_OP_TURBO_DEC
375 Chain of uint32_t values. Note that it is possible to define more than one
376 input/output entries which will result in chaining two or more data structures
377 for *segmented Transport Blocks*
382 0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100,
383 0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00
385 Chain of uint32_t values
390 0x7f7f0000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
391 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
393 Chain of uint32_t values
398 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
399 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000
401 Chain of uint32_t values
408 Chain of uint32_t values
415 Chain of uint32_t values
420 0x817f817f, 0x7f817f7f, 0x81818181, 0x817f7f81, 0x7f818181, 0x8181817f, 0x817f817f, 0x8181817f
422 Chain of uint32_t values
427 0x817f7f81, 0x7f7f7f81, 0x7f7f8181
468 expected_iter_count =
485 Chain of flags for LDPC decoder operation based on the rte_bbdev_op_td_flag_bitmasks:
492 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE, RTE_BBDEV_TURBO_EQUALIZER,
493 RTE_BBDEV_TURBO_SOFT_OUTPUT
495 Chain of operation statuses that are expected after operation is performed.
496 Following statuses can be used:
506 ``OK`` means no errors are expected. Cannot be used with other values.
514 Turbo encoder test vectors template
515 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
517 For turbo encoder it has to be always set to ``RTE_BBDEV_OP_TURBO_ENC``
522 RTE_BBDEV_OP_TURBO_ENC
524 Chain of uint32_t values
531 Chain of uint32_t values
536 0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29,
537 0xa25b7f47, 0x2aa224ce, 0x79f2
567 Chain of flags for LDPC decoder operation based on the rte_bbdev_op_te_flag_bitmasks:
569 ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` is used to indicate the parser to
570 force the input data to be memory split and formed as a segmented mbuf.
576 RTE_BBDEV_TURBO_RATE_MATCH
578 Chain of operation statuses that are expected after operation is performed.
579 Following statuses can be used:
587 ``OK`` means no errors are expected. Cannot be used with other values.
594 LDPC decoder test vectors template
595 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
597 For LDPC decoder it has to be always set to ``RTE_BBDEV_OP_LDPC_DEC``
602 RTE_BBDEV_OP_LDPC_DEC
604 Chain of uint32_t values. Note that it is possible to define more than one
605 input/output entries which will result in chaining two or more data structures
606 for *segmented Transport Blocks*
611 0x00000000, 0x7f817f00, 0x7f7f8100, 0x817f8100, 0x81008100, 0x7f818100, 0x81817f00, 0x7f818100,
612 0x81007f00, 0x7f818100, 0x817f8100, 0x81817f00, 0x81008100, 0x817f7f00, 0x7f7f8100, 0x81817f00
689 Chain of flags for LDPC decoder operation based on the rte_bbdev_op_ldpcdec_flag_bitmasks:
696 RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE, RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE,
697 RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE, RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION
699 Chain of operation statuses that are expected after operation is performed.
700 Following statuses can be used:
702 - ``OK`` : No error reported.
704 - ``SYN`` : LDPC syndrome parity check is failing.
706 - ``CRC`` : CRC parity check is failing when CRC check operation is included.
708 - ``SYNCRC`` : Both CRC and LDPC syndromes parity checks are failing.
710 ``OK`` means no errors are expected. Cannot be used with other values.
718 LDPC encoder test vectors template
719 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
721 For turbo encoder it has to be always set to ``RTE_BBDEV_OP_LDPC_ENC``
726 RTE_BBDEV_OP_LDPC_ENC
728 Chain of uint32_t values
735 Chain of uint32_t values
740 0xd2399179, 0x640eb999, 0x2cbaf577, 0xaf224ae2, 0x9d139927, 0xe6909b29,
741 0xa25b7f47, 0x2aa224ce, 0x79f2
801 Chain of flags for LDPC encoder operation based on the
802 rte_bbdev_op_ldpcenc_flag_bitmasks:
807 RTE_BBDEV_LDPC_RATE_MATCH
809 Chain of operation statuses that are expected after operation is performed.
810 Following statuses can be used:
818 ``OK`` means no errors are expected. Cannot be used with other values.