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 (N3000, referred to as VC_5GNR in the code) 10as well as Arrow Creek (N6000, referred to as AGX100 in the code). 11 12Features 13-------- 14 15FPGA 5GNR FEC PMD supports the following BBDEV capabilities: 16 17- LDPC Encode in the DL 18- LDPC Decode in the UL 19- 8 VFs per PF (physical device) 20- Maximum of 32 UL queues per VF 21- Maximum of 32 DL queues per VF 22- PCIe Gen-3 x8 Interface 23- MSI-X 24- SR-IOV 25 26FPGA 5GNR FEC PMD supports the following BBDEV capabilities: 27 28* For the LDPC encode operation: 29 - ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` : set to attach CRC24B to CB(s) 30 - ``RTE_BBDEV_LDPC_RATE_MATCH`` : if set then do not do Rate Match bypass 31 32* For the LDPC decode operation: 33 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` : check CRC24B from CB(s) 34 - ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` : disable early termination 35 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` : drops CRC24B bits appended while decoding 36 - ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` : provides an input for HARQ combining 37 - ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` : provides an input for HARQ combining 38 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE`` : HARQ memory input is internal 39 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE`` : HARQ memory output is internal 40 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK`` : loopback data to/from HARQ memory 41 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS`` : HARQ memory includes the fillers bits 42 43 44Limitations 45----------- 46 47FPGA 5GNR FEC does not support the following: 48 49- Scatter-Gather function 50 51 52Installation 53------------ 54 55Section 3 of the DPDK manual provides instructions on installing and compiling DPDK. 56 57DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual. 58The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The 59hugepage configuration of a server may be examined using: 60 61.. code-block:: console 62 63 grep Huge* /proc/meminfo 64 65 66Initialization 67-------------- 68 69When the device first powers up, its PCI Physical Functions (PF) can be listed through this command: 70 71Vista Creek (N3000) 72 73.. code-block:: console 74 75 sudo lspci -vd8086:0d8f 76 77Arrow Creek (N6000) 78 79.. code-block:: console 80 81 sudo lspci -vd8086:5799 82 83The physical and virtual functions are compatible with Linux UIO drivers: 84``vfio_pci`` and ``igb_uio``. However, in order to work the FPGA 5GNR FEC device firstly needs 85to be bound to one of these linux drivers through DPDK. 86 87For more details on how to bind the PF device and create VF devices, see 88:ref:`linux_gsg_binding_kernel`. 89 90 91Configure the VFs through PF 92~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 93 94The PCI virtual functions must be configured before working or getting assigned 95to VMs/Containers. The configuration involves allocating the number of hardware 96queues, priorities, load balance, bandwidth and other settings necessary for the 97device to perform FEC functions. 98 99This configuration needs to be executed at least once after reboot or PCI FLR and can 100be achieved by using the function ``rte_fpga_5gnr_fec_configure()``, which sets up the 101parameters defined in ``rte_fpga_5gnr_fec_conf`` structure: 102 103.. code-block:: c 104 105 struct rte_fpga_5gnr_fec_conf { 106 bool pf_mode_en; 107 uint8_t vf_ul_queues_number[FPGA_5GNR_FEC_NUM_VFS]; 108 uint8_t vf_dl_queues_number[FPGA_5GNR_FEC_NUM_VFS]; 109 uint8_t ul_bandwidth; 110 uint8_t dl_bandwidth; 111 uint8_t ul_load_balance; 112 uint8_t dl_load_balance; 113 }; 114 115- ``pf_mode_en``: identifies whether only PF is to be used, or the VFs. PF and 116 VFs are mutually exclusive and cannot run simultaneously. 117 Set to 1 for PF mode enabled. 118 If PF mode is enabled all queues available in the device are assigned 119 exclusively to PF and 0 queues given to VFs. 120 121- ``vf_*l_queues_number``: defines the hardware queue mapping for every VF. 122 123- ``*l_bandwidth``: Only used for the Vista Creek schedule algorithm 124 in case of congestion on PCIe interface. 125 The device allocates different bandwidth to UL and DL. 126 The weight is configured by this setting. 127 The unit of weight is 3 code blocks. 128 For example, if the code block cbps (code block per second) ratio 129 between UL and DL is 12:1, then the configuration value should be set to 36:3. 130 The schedule algorithm is based on code block regardless the length of each block. 131 132- ``*l_load_balance``: hardware queues are load-balanced in a round-robin 133 fashion. Queues get filled first-in first-out until they reach a pre-defined 134 watermark level, if exceeded, they won't get assigned new code blocks.. 135 This watermark is defined by this setting. 136 137 If all hardware queues exceeds the watermark, no code blocks will be 138 streamed in from UL/DL code block FIFO. 139 140 141An example configuration code calling the function ``rte_fpga_5gnr_fec_configure()`` is shown 142below: 143 144.. code-block:: c 145 146 struct rte_fpga_5gnr_fec_conf conf; 147 unsigned int i; 148 149 memset(&conf, 0, sizeof(struct rte_fpga_5gnr_fec_conf)); 150 conf.pf_mode_en = 1; 151 152 for (i = 0; i < FPGA_5GNR_FEC_NUM_VFS; ++i) { 153 conf.vf_ul_queues_number[i] = 4; 154 conf.vf_dl_queues_number[i] = 4; 155 } 156 conf.ul_bandwidth = 12; 157 conf.dl_bandwidth = 5; 158 conf.dl_load_balance = 64; 159 conf.ul_load_balance = 64; 160 161 /* setup FPGA PF */ 162 ret = rte_fpga_5gnr_fec_configure(info->dev_name, &conf); 163 TEST_ASSERT_SUCCESS(ret, 164 "Failed to configure 5GNR FPGA PF for bbdev %s", 165 info->dev_name); 166 167 168Test Application 169---------------- 170 171BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing 172the functionality of the device, depending on the device's capabilities. 173 174.. code-block:: console 175 176 "-p", "--testapp-path": specifies path to the bbdev test app. 177 "-e", "--eal-params" : EAL arguments which are passed to the test app. 178 "-t", "--timeout" : Timeout in seconds (default=300). 179 "-c", "--test-cases" : Defines test cases to run. Run all if not specified. 180 "-v", "--test-vector" : Test vector path (default=dpdk_path+/app/test-bbdev/test_vectors/bbdev_null.data). 181 "-n", "--num-ops" : Number of operations to process on device (default=32). 182 "-b", "--burst-size" : Operations enqueue/dequeue burst size (default=32). 183 "-l", "--num-lcores" : Number of lcores to run (default=16). 184 "-i", "--init-device" : Initialise PF device with default values. 185 186 187To execute the test application tool using simple decode or encode data, 188type one of the following: 189 190.. code-block:: console 191 192 ./test-bbdev.py -c validation -n 64 -b 1 -v ./ldpc_dec_default.data 193 ./test-bbdev.py -c validation -n 64 -b 1 -v ./ldpc_enc_default.data 194 195 196The test application ``test-bbdev.py`` supports the ability to configure the PF device 197with a default set of values, if the "-i" or "- -init-device" option is included. 198The default values are defined in ``test_bbdev_perf.c`` as: 199 200- VF_UL_QUEUE_VALUE 4 201- VF_DL_QUEUE_VALUE 4 202- UL_BANDWIDTH 3 203- DL_BANDWIDTH 3 204- UL_LOAD_BALANCE 128 205- DL_LOAD_BALANCE 128 206 207 208Test Vectors 209~~~~~~~~~~~~ 210 211In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides 212a range of additional tests under the test_vectors folder, which may be useful. The results 213of these tests will depend on the FPGA 5GNR FEC capabilities. 214 215 216Alternate Baseband Device configuration tool 217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 218 219On top of the embedded configuration feature supported in test-bbdev using "- -init-device" 220option, there is also a tool available to perform that device configuration using a companion 221application. 222The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF 223and not only limited to the PF as captured above. 224 225See for more details: https://github.com/intel/pf-bb-config 226 227Specifically for the BBDEV FPGA 5GNR FEC PMD, the command below can be used: 228 229Vista Creek (N3000) 230 231.. code-block:: console 232 233 ./pf_bb_config FPGA_5GNR -c fpga_5gnr/fpga_5gnr_config_vf.cfg 234 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 235 236Arrow Creek (N6000) 237 238.. code-block:: console 239 240 ./pf_bb_config AGX100 -c agx100/agx100_config_1vf.cfg 241 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 242