1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2022 Intel Corporation 3 4.. include:: <isonum.txt> 5 6Intel\ |reg| vRAN Boost Poll Mode Driver (PMD) 7============================================== 8 9The Intel\ |reg| vRAN Boost integrated accelerator enables 10cost-effective 4G and 5G next-generation virtualized Radio Access Network (vRAN) 11solutions. 12The Intel vRAN Boost v1.0 (VRB1 in the code) is specifically integrated on the 134th Gen Intel\ |reg| Xeon\ |reg| Scalable processor with Intel\ |reg| vRAN Boost, 14also known as Sapphire Rapids Edge Enhanced (SPR-EE). 15 16Features 17-------- 18 19Intel vRAN Boost v1.0 includes a 5G Low Density Parity Check (LDPC) encoder/decoder, 20rate match/dematch, Hybrid Automatic Repeat Request (HARQ) with access to DDR 21memory for buffer management, a 4G Turbo encoder/decoder, 22a Fast Fourier Transform (FFT) block providing DFT/iDFT processing offload 23for the 5G Sounding Reference Signal (SRS), a Queue Manager (QMGR), 24and a DMA subsystem. 25There is no dedicated on-card memory for HARQ, the coherent memory on the CPU side is being used. 26 27These hardware blocks provide the following features exposed by the PMD: 28 29- LDPC Encode in the Downlink (5GNR) 30- LDPC Decode in the Uplink (5GNR) 31- Turbo Encode in the Downlink (4G) 32- Turbo Decode in the Uplink (4G) 33- FFT processing 34- Single Root I/O Virtualization (SR-IOV) with 16 Virtual Functions (VFs) per Physical Function (PF) 35- Maximum of 256 queues per VF 36 37The Intel vRAN Boost v1.0 PMD supports the following bbdev capabilities: 38 39* For the LDPC encode operation: 40 - ``RTE_BBDEV_LDPC_CRC_24B_ATTACH``: set to attach CRC24B to CB(s). 41 - ``RTE_BBDEV_LDPC_RATE_MATCH``: if set then do not do Rate Match bypass. 42 - ``RTE_BBDEV_LDPC_INTERLEAVER_BYPASS``: if set then bypass interleaver. 43 44* For the LDPC decode operation: 45 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK``: check CRC24B from CB(s). 46 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP``: drops CRC24B bits appended while decoding. 47 - ``RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK``: check CRC24A from CB(s). 48 - ``RTE_BBDEV_LDPC_CRC_TYPE_16_CHECK``: check CRC16 from CB(s). 49 - ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE``: provides an input for HARQ combining. 50 - ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE``: provides an input for HARQ combining. 51 - ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE``: disable early termination. 52 - ``RTE_BBDEV_LDPC_DEC_SCATTER_GATHER``: supports scatter-gather for input/output data. 53 - ``RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION``: supports compression of the HARQ input/output. 54 - ``RTE_BBDEV_LDPC_LLR_COMPRESSION``: supports LLR input compression. 55 56* For the turbo encode operation: 57 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``: set to attach CRC24B to CB(s). 58 - ``RTE_BBDEV_TURBO_RATE_MATCH``: if set then do not do Rate Match bypass. 59 - ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS``: set to bypass RV index. 60 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``: supports scatter-gather for input/output data. 61 62* For the turbo decode operation: 63 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B``: check CRC24B from CB(s). 64 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE``: perform subblock de-interleave. 65 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN``: set if negative LLR input is supported. 66 - ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP``: keep CRC24B bits appended while decoding. 67 - ``RTE_BBDEV_TURBO_DEC_CRC_24B_DROP``: option to drop the code block CRC after decoding. 68 - ``RTE_BBDEV_TURBO_EARLY_TERMINATION``: set early termination feature. 69 - ``RTE_BBDEV_TURBO_DEC_SCATTER_GATHER``: supports scatter-gather for input/output data. 70 - ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN``: set half iteration granularity. 71 - ``RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH``: set to run an extra odd iteration after CRC match. 72 - ``RTE_BBDEV_TURBO_MAP_DEC``: supports flexible parallel MAP engine decoding. 73 74* For the FFT operation: 75 - ``RTE_BBDEV_FFT_WINDOWING``: flexible windowing capability. 76 - ``RTE_BBDEV_FFT_CS_ADJUSTMENT``: flexible adjustment of Cyclic Shift time offset. 77 - ``RTE_BBDEV_FFT_DFT_BYPASS``: set for bypass the DFT and get directly into iDFT input. 78 - ``RTE_BBDEV_FFT_IDFT_BYPASS``: set for bypass the IDFT and get directly the DFT output. 79 - ``RTE_BBDEV_FFT_WINDOWING_BYPASS``: set for bypass time domain windowing. 80 81 82Installation 83------------ 84 85Section 3 of the DPDK manual provides instructions on installing and compiling DPDK. 86 87DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual. 88The bbdev test application has been tested with a configuration 40 x 1GB hugepages. 89The hugepage configuration of a server may be examined using: 90 91.. code-block:: console 92 93 grep Huge* /proc/meminfo 94 95 96Initialization 97-------------- 98 99When the device first powers up, its PCI Physical Functions (PF) 100can be listed through these commands for Intel vRAN Boost v1: 101 102.. code-block:: console 103 104 sudo lspci -vd8086:57c0 105 106The physical and virtual functions are compatible with Linux UIO drivers: 107``vfio_pci`` and ``igb_uio``. 108However, in order to work the 5G/4G FEC device first needs to be bound 109to one of these Linux drivers through DPDK. 110 111For more details on how to bind the PF device and create VF devices, see 112:ref:`linux_gsg_binding_kernel`. 113 114 115Configure the VFs through PF 116~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117 118The PCI virtual functions must be configured before working or getting assigned 119to VMs/Containers. 120The configuration involves allocating the number of hardware queues, priorities, 121load balance, bandwidth and other settings necessary for the device 122to perform FEC functions. 123 124This configuration needs to be executed at least once after reboot or PCI FLR 125and can be achieved by using the functions ``rte_acc200_configure()``, 126which sets up the parameters defined in the compatible ``acc200_conf`` structure. 127 128 129Test Application 130---------------- 131 132BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing 133the functionality of the device, depending on the device's capabilities. 134 135For more details on how to use the test application, 136see :ref:`test_bbdev_application`. 137 138 139Test Vectors 140~~~~~~~~~~~~ 141 142In addition to the simple LDPC decoder and LDPC encoder tests, 143bbdev also provides a range of additional tests under the test_vectors folder, 144which may be useful. 145The results of these tests will depend on the device capabilities which may 146cause some test cases to be skipped, but no failure should be reported. 147 148 149Alternate Baseband Device configuration tool 150~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 151 152On top of the embedded configuration feature supported in test-bbdev using 153"- -init-device" option mentioned above, there is also a tool available 154to perform that device configuration using a companion application. 155The ``pf_bb_config`` application notably enables then to run bbdev-test 156from the VF and not only limited to the PF as captured above. 157 158See for more details: https://github.com/intel/pf-bb-config 159 160Specifically for the bbdev Intel vRAN Boost v1 PMD, the command below can be used 161(note that ACC200 was used previously to refer to VRB1): 162 163.. code-block:: console 164 165 pf_bb_config ACC200 -c ./acc200/acc200_config_vf_5g.cfg 166 test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 64 -l 1 -v ./ldpc_dec_default.data 167