1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2019 Intel Corporation 3 4Intel(R) FPGA LTE FEC Poll Mode Driver 5====================================== 6 7The BBDEV FPGA LTE FEC poll mode driver (PMD) supports an FPGA implementation of a VRAN 8Turbo Encode / Decode LTE wireless acceleration function, using Intel's PCI-e and FPGA 9based Vista Creek device. 10 11Features 12-------- 13 14FPGA LTE FEC PMD supports the following features: 15 16- Turbo Encode in the DL with total throughput of 4.5 Gbits/s 17- Turbo Decode in the UL with total throughput of 1.5 Gbits/s assuming 8 decoder iterations 18- 8 VFs per PF (physical device) 19- Maximum of 32 UL queues per VF 20- Maximum of 32 DL queues per VF 21- PCIe Gen-3 x8 Interface 22- MSI-X 23- SR-IOV 24 25 26FPGA LTE FEC PMD supports the following BBDEV capabilities: 27 28* For the turbo encode operation: 29 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` : set to attach CRC24B to CB(s) 30 - ``RTE_BBDEV_TURBO_RATE_MATCH`` : if set then do not do Rate Match bypass 31 - ``RTE_BBDEV_TURBO_ENC_INTERRUPTS`` : set for encoder dequeue interrupts 32 33 34* For the turbo decode operation: 35 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` : check CRC24B from CB(s) 36 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` : perform subblock de-interleave 37 - ``RTE_BBDEV_TURBO_DEC_INTERRUPTS`` : set for decoder dequeue interrupts 38 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` : set if negative LLR encoder i/p is supported 39 - ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` : keep CRC24B bits appended while decoding 40 41 42Limitations 43----------- 44 45FPGA LTE FEC does not support the following: 46 47- Scatter-Gather function 48 49 50Installation 51-------------- 52 53Section 3 of the DPDK manual provides instructions on installing and compiling DPDK. 54 55DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual. 56The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The 57hugepage configuration of a server may be examined using: 58 59.. code-block:: console 60 61 grep Huge* /proc/meminfo 62 63 64Initialization 65-------------- 66 67When the device first powers up, its PCI Physical Functions (PF) can be listed through this command: 68 69.. code-block:: console 70 71 sudo lspci -vd1172:5052 72 73The physical and virtual functions are compatible with Linux UIO drivers: 74``vfio_pci`` and ``igb_uio``. However, in order to work the FPGA LTE FEC device firstly needs 75to be bound to one of these linux drivers through DPDK. 76 77For more details on how to bind the PF device and create VF devices, see 78:ref:`linux_gsg_binding_kernel`. 79 80 81Configure the VFs through PF 82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 83 84The PCI virtual functions must be configured before working or getting assigned 85to VMs/Containers. The configuration involves allocating the number of hardware 86queues, priorities, load balance, bandwidth and other settings necessary for the 87device to perform FEC functions. 88 89This configuration needs to be executed at least once after reboot or PCI FLR and can 90be achieved by using the function ``rte_fpga_lte_fec_configure()``, which sets up the 91parameters defined in ``rte_fpga_lte_fec_conf`` structure: 92 93.. code-block:: c 94 95 struct rte_fpga_lte_fec_conf { 96 bool pf_mode_en; 97 uint8_t vf_ul_queues_number[FPGA_LTE_FEC_NUM_VFS]; 98 uint8_t vf_dl_queues_number[FPGA_LTE_FEC_NUM_VFS]; 99 uint8_t ul_bandwidth; 100 uint8_t dl_bandwidth; 101 uint8_t ul_load_balance; 102 uint8_t dl_load_balance; 103 uint16_t flr_time_out; 104 }; 105 106- ``pf_mode_en``: identifies whether only PF is to be used, or the VFs. PF and 107 VFs are mutually exclusive and cannot run simultaneously. 108 Set to 1 for PF mode enabled. 109 If PF mode is enabled all queues available in the device are assigned 110 exclusively to PF and 0 queues given to VFs. 111 112- ``vf_*l_queues_number``: defines the hardware queue mapping for every VF. 113 114- ``*l_bandwidth``: in case of congestion on PCIe interface. The device 115 allocates different bandwidth to UL and DL. The weight is configured by this 116 setting. The unit of weight is 3 code blocks. For example, if the code block 117 cbps (code block per second) ratio between UL and DL is 12:1, then the 118 configuration value should be set to 36:3. The schedule algorithm is based 119 on code block regardless the length of each block. 120 121- ``*l_load_balance``: hardware queues are load-balanced in a round-robin 122 fashion. Queues get filled first-in first-out until they reach a pre-defined 123 watermark level, if exceeded, they won't get assigned new code blocks.. 124 This watermark is defined by this setting. 125 126 If all hardware queues exceeds the watermark, no code blocks will be 127 streamed in from UL/DL code block FIFO. 128 129- ``flr_time_out``: specifies how many 16.384us to be FLR time out. The 130 time_out = flr_time_out x 16.384us. For instance, if you want to set 10ms for 131 the FLR time out then set this setting to 0x262=610. 132 133 134An example configuration code calling the function ``rte_fpga_lte_fec_configure()`` is shown 135below: 136 137.. code-block:: c 138 139 struct rte_fpga_lte_fec_conf conf; 140 unsigned int i; 141 142 memset(&conf, 0, sizeof(struct rte_fpga_lte_fec_conf)); 143 conf.pf_mode_en = 1; 144 145 for (i = 0; i < FPGA_LTE_FEC_NUM_VFS; ++i) { 146 conf.vf_ul_queues_number[i] = 4; 147 conf.vf_dl_queues_number[i] = 4; 148 } 149 conf.ul_bandwidth = 12; 150 conf.dl_bandwidth = 5; 151 conf.dl_load_balance = 64; 152 conf.ul_load_balance = 64; 153 154 /* setup FPGA PF */ 155 ret = rte_fpga_lte_fec_configure(info->dev_name, &conf); 156 TEST_ASSERT_SUCCESS(ret, 157 "Failed to configure 4G FPGA PF for bbdev %s", 158 info->dev_name); 159 160 161Test Application 162---------------- 163 164BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing 165the functionality of the device, depending on the device's capabilities. 166 167For more details on how to use the test application, 168see :ref:`test_bbdev_application`. 169 170Test Vectors 171~~~~~~~~~~~~ 172 173In addition to the simple turbo decoder and turbo encoder tests, bbdev also provides 174a range of additional tests under the test_vectors folder, which may be useful. The results 175of these tests will depend on the FPGA LTE FEC capabilities: 176 177* turbo decoder tests: 178 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_high_snr.data`` 179 - ``turbo_dec_c1_k6144_r0_e10376_crc24b_sbd_negllr_low_snr.data`` 180 - ``turbo_dec_c1_k6144_r0_e34560_negllr.data`` 181 - ``turbo_dec_c1_k6144_r0_e34560_sbd_negllr.data`` 182 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr_crc24b.data`` 183 - ``turbo_dec_c2_k3136_r0_e4920_sbd_negllr.data`` 184 185 186* turbo encoder tests: 187 - ``turbo_enc_c1_k40_r0_e1190_rm.data`` 188 - ``turbo_enc_c1_k40_r0_e1194_rm.data`` 189 - ``turbo_enc_c1_k40_r0_e1196_rm.data`` 190 - ``turbo_enc_c1_k40_r0_e272_rm.data`` 191 - ``turbo_enc_c1_k6144_r0_e18444.data`` 192 - ``turbo_enc_c1_k6144_r0_e32256_crc24b_rm.data`` 193 - ``turbo_enc_c2_k5952_r0_e17868_crc24b.data`` 194 - ``turbo_enc_c3_k4800_r2_e14412_crc24b.data`` 195 - ``turbo_enc_c4_k4800_r2_e14412_crc24b.data`` 196 197 198Alternate Baseband Device configuration tool 199~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 200 201On top of the embedded configuration feature supported in test-bbdev using "- -init-device" 202option, there is also a tool available to perform that device configuration using a companion 203application. 204The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF 205and not only limited to the PF as captured above. 206 207See for more details: https://github.com/intel/pf-bb-config 208 209Specifically for the BBDEV FPGA LTE FEC PMD, the command below can be used: 210 211.. code-block:: console 212 213 ./pf_bb_config FPGA_LTE -c fpga_lte/fpga_lte_config_vf.cfg 214 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./turbo_dec_default.data 215