1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2019 Intel Corporation 3 4Intel(R) FPGA 5GNR FEC Poll Mode Driver 5======================================= 6 7The BBDEV FPGA 5GNR FEC poll mode driver (PMD) supports an FPGA implementation of a VRAN 8LDPC Encode / Decode 5GNR wireless acceleration function, using Intel's PCI-e and FPGA 9based Vista Creek device. 10 11Features 12-------- 13 14FPGA 5GNR FEC PMD supports the following features: 15 16- LDPC Encode in the DL 17- LDPC Decode in the UL 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 25FPGA 5GNR FEC PMD supports the following BBDEV capabilities: 26 27* For the LDPC encode operation: 28 - ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` : set to attach CRC24B to CB(s) 29 - ``RTE_BBDEV_LDPC_RATE_MATCH`` : if set then do not do Rate Match bypass 30 31* For the LDPC decode operation: 32 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` : check CRC24B from CB(s) 33 - ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` : disable early termination 34 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` : drops CRC24B bits appended while decoding 35 - ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` : provides an input for HARQ combining 36 - ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` : provides an input for HARQ combining 37 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE`` : HARQ memory input is internal 38 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE`` : HARQ memory output is internal 39 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK`` : loopback data to/from HARQ memory 40 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS`` : HARQ memory includes the fillers bits 41 42 43Limitations 44----------- 45 46FPGA 5GNR FEC does not support the following: 47 48- Scatter-Gather function 49 50 51Installation 52------------ 53 54Section 3 of the DPDK manual provides instructions on installing and compiling DPDK. 55 56DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual. 57The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The 58hugepage configuration of a server may be examined using: 59 60.. code-block:: console 61 62 grep Huge* /proc/meminfo 63 64 65Initialization 66-------------- 67 68When the device first powers up, its PCI Physical Functions (PF) can be listed through this command: 69 70.. code-block:: console 71 72 sudo lspci -vd8086:0d8f 73 74The physical and virtual functions are compatible with Linux UIO drivers: 75``vfio_pci`` and ``igb_uio``. However, in order to work the FPGA 5GNR FEC device firstly needs 76to be bound to one of these linux drivers through DPDK. 77 78For more details on how to bind the PF device and create VF devices, see 79:ref:`linux_gsg_binding_kernel`. 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_5gnr_fec_configure()``, which sets up the 91parameters defined in ``rte_fpga_5gnr_fec_conf`` structure: 92 93.. code-block:: c 94 95 struct rte_fpga_5gnr_fec_conf { 96 bool pf_mode_en; 97 uint8_t vf_ul_queues_number[FPGA_5GNR_FEC_NUM_VFS]; 98 uint8_t vf_dl_queues_number[FPGA_5GNR_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_5gnr_fec_configure()`` is shown 135below: 136 137.. code-block:: c 138 139 struct rte_fpga_5gnr_fec_conf conf; 140 unsigned int i; 141 142 memset(&conf, 0, sizeof(struct rte_fpga_5gnr_fec_conf)); 143 conf.pf_mode_en = 1; 144 145 for (i = 0; i < FPGA_5GNR_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_5gnr_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 170 171Test Vectors 172~~~~~~~~~~~~ 173 174In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides 175a range of additional tests under the test_vectors folder, which may be useful. The results 176of these tests will depend on the FPGA 5GNR FEC capabilities. 177 178 179Alternate Baseband Device configuration tool 180~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 181 182On top of the embedded configuration feature supported in test-bbdev using "- -init-device" 183option, there is also a tool available to perform that device configuration using a companion 184application. 185The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF 186and not only limited to the PF as captured above. 187 188See for more details: https://github.com/intel/pf-bb-config 189 190Specifically for the BBDEV FPGA 5GNR FEC PMD, the command below can be used: 191 192.. code-block:: console 193 194 ./pf_bb_config FPGA_5GNR -c fpga_5gnr/fpga_5gnr_config_vf.cfg 195 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 196