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 }; 104 105- ``pf_mode_en``: identifies whether only PF is to be used, or the VFs. PF and 106 VFs are mutually exclusive and cannot run simultaneously. 107 Set to 1 for PF mode enabled. 108 If PF mode is enabled all queues available in the device are assigned 109 exclusively to PF and 0 queues given to VFs. 110 111- ``vf_*l_queues_number``: defines the hardware queue mapping for every VF. 112 113- ``*l_bandwidth``: in case of congestion on PCIe interface. The device 114 allocates different bandwidth to UL and DL. The weight is configured by this 115 setting. The unit of weight is 3 code blocks. For example, if the code block 116 cbps (code block per second) ratio between UL and DL is 12:1, then the 117 configuration value should be set to 36:3. The schedule algorithm is based 118 on code block regardless the length of each block. 119 120- ``*l_load_balance``: hardware queues are load-balanced in a round-robin 121 fashion. Queues get filled first-in first-out until they reach a pre-defined 122 watermark level, if exceeded, they won't get assigned new code blocks.. 123 This watermark is defined by this setting. 124 125 If all hardware queues exceeds the watermark, no code blocks will be 126 streamed in from UL/DL code block FIFO. 127 128 129An example configuration code calling the function ``rte_fpga_5gnr_fec_configure()`` is shown 130below: 131 132.. code-block:: c 133 134 struct rte_fpga_5gnr_fec_conf conf; 135 unsigned int i; 136 137 memset(&conf, 0, sizeof(struct rte_fpga_5gnr_fec_conf)); 138 conf.pf_mode_en = 1; 139 140 for (i = 0; i < FPGA_5GNR_FEC_NUM_VFS; ++i) { 141 conf.vf_ul_queues_number[i] = 4; 142 conf.vf_dl_queues_number[i] = 4; 143 } 144 conf.ul_bandwidth = 12; 145 conf.dl_bandwidth = 5; 146 conf.dl_load_balance = 64; 147 conf.ul_load_balance = 64; 148 149 /* setup FPGA PF */ 150 ret = rte_fpga_5gnr_fec_configure(info->dev_name, &conf); 151 TEST_ASSERT_SUCCESS(ret, 152 "Failed to configure 5GNR FPGA PF for bbdev %s", 153 info->dev_name); 154 155 156Test Application 157---------------- 158 159BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing 160the functionality of the device, depending on the device's capabilities. 161 162For more details on how to use the test application, 163see :ref:`test_bbdev_application`. 164 165 166Test Vectors 167~~~~~~~~~~~~ 168 169In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides 170a range of additional tests under the test_vectors folder, which may be useful. The results 171of these tests will depend on the FPGA 5GNR FEC capabilities. 172 173 174Alternate Baseband Device configuration tool 175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 176 177On top of the embedded configuration feature supported in test-bbdev using "- -init-device" 178option, there is also a tool available to perform that device configuration using a companion 179application. 180The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF 181and not only limited to the PF as captured above. 182 183See for more details: https://github.com/intel/pf-bb-config 184 185Specifically for the BBDEV FPGA 5GNR FEC PMD, the command below can be used: 186 187.. code-block:: console 188 189 ./pf_bb_config FPGA_5GNR -c fpga_5gnr/fpga_5gnr_config_vf.cfg 190 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 191