1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2020 Intel Corporation 3 4Intel(R) ACC100 5G/4G FEC Poll Mode Drivers 5====================================================== 6 7The BBDEV ACC100 5G/4G FEC poll mode driver (PMD) supports an 8implementation of a VRAN FEC wireless acceleration function. 9This device is also known as Mount Bryce. 10 11Features 12-------- 13 14ACC100 5G/4G FEC PMDs support the following features: 15 16- LDPC Encode in the DL (5GNR) 17- LDPC Decode in the UL (5GNR) 18- Turbo Encode in the DL (4G) 19- Turbo Decode in the UL (4G) 20- 16 VFs per PF (physical device) 21- Maximum of 128 queues per VF 22- PCIe Gen-3 x16 Interface 23- MSI 24- SR-IOV 25 26ACC100 5G/4G FEC PMDs support 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 - ``RTE_BBDEV_LDPC_INTERLEAVER_BYPASS`` : if set then bypass interleaver 32 33* For the LDPC decode operation: 34 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` : check CRC24B from CB(s) 35 - ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` : disable early termination 36 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` : drops CRC24B bits appended while decoding 37 - ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` : provides an input for HARQ combining 38 - ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` : provides an input for HARQ combining 39 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE`` : HARQ memory input is internal 40 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE`` : HARQ memory output is internal 41 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK`` : loopback data to/from HARQ memory 42 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS`` : HARQ memory includes the fillers bits 43 - ``RTE_BBDEV_LDPC_DEC_SCATTER_GATHER`` : supports scatter-gather for input/output data 44 - ``RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION`` : supports compression of the HARQ input/output 45 - ``RTE_BBDEV_LDPC_LLR_COMPRESSION`` : supports LLR input compression 46 47* For the turbo encode operation: 48 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` : set to attach CRC24B to CB(s) 49 - ``RTE_BBDEV_TURBO_RATE_MATCH`` : if set then do not do Rate Match bypass 50 - ``RTE_BBDEV_TURBO_ENC_INTERRUPTS`` : set for encoder dequeue interrupts 51 - ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` : set to bypass RV index 52 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` : supports scatter-gather for input/output data 53 54* For the turbo decode operation: 55 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` : check CRC24B from CB(s) 56 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` : perform subblock de-interleave 57 - ``RTE_BBDEV_TURBO_DEC_INTERRUPTS`` : set for decoder dequeue interrupts 58 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` : set if negative LLR encoder i/p is supported 59 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` : set if positive LLR encoder i/p is supported 60 - ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` : keep CRC24B bits appended while decoding 61 - ``RTE_BBDEV_TURBO_DEC_CRC_24B_DROP`` : option to drop the code block CRC after decoding 62 - ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` : set early termination feature 63 - ``RTE_BBDEV_TURBO_DEC_SCATTER_GATHER`` : supports scatter-gather for input/output data 64 - ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN`` : set half iteration granularity 65 66* PMD-specific build flags: 67 The ACC100 PMD includes some optional build flags which may be used for troubleshooting. 68 Recommended build configuration is for these to be kept as default. 69 - ``RTE_LIBRTE_BBDEV_SKIP_VALIDATE``: option to skip API input validation. 70 Recommended value is to keep the validation enabled by default 71 as a protection for negative scenarios at a cost of some cycles 72 spent to enforce these checks. 73 - ``ACC100_EXT_MEM``: default option with memory external to CPU on the PCIe card DDR itself. 74 Alternative build option will use CPU memory (not recommended). 75 76 77Installation 78------------ 79 80Section 3 of the DPDK manual provides instructions on installing and compiling DPDK. 81 82DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual. 83The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The 84hugepage configuration of a server may be examined using: 85 86.. code-block:: console 87 88 grep Huge* /proc/meminfo 89 90 91Initialization 92-------------- 93 94When the device first powers up, its PCI Physical Functions (PF) can be listed through these 95commands for ACC100: 96 97.. code-block:: console 98 99 sudo lspci -vd8086:0d5c 100 101The physical and virtual functions are compatible with Linux UIO drivers: 102``vfio_pci`` and ``igb_uio``. However, in order to work the 5G/4G 103FEC device first needs to be bound to one of these linux drivers through DPDK. 104 105For more details on how to bind the PF device and create VF devices, see 106:ref:`linux_gsg_binding_kernel`. 107 108 109Configure the VFs through PF 110~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 111 112The PCI virtual functions must be configured before working or getting assigned 113to VMs/Containers. The configuration involves allocating the number of hardware 114queues, priorities, load balance, bandwidth and other settings necessary for the 115device to perform FEC functions. 116 117This configuration needs to be executed at least once after reboot or PCI FLR and can 118be achieved by using the functions ``rte_acc10x_configure()``, 119which sets up the parameters defined in the compatible ``acc100_conf`` structure. 120 121Test Application 122---------------- 123 124BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing 125the functionality of the device, depending on the device's capabilities. 126 127For more details on how to use the test application, 128see :ref:`test_bbdev_application`. 129 130 131Test Vectors 132~~~~~~~~~~~~ 133 134In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides 135a range of additional tests under the test_vectors folder, which may be useful. The results 136of these tests will depend on the device 5G/4G FEC capabilities which may cause some 137testcases to be skipped, but no failure should be reported. 138 139 140Alternate Baseband Device configuration tool 141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 142 143On top of the embedded configuration feature supported in test-bbdev using "- -init-device" 144option mentioned above, there is also a tool available to perform that device configuration 145using a companion application. 146The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF 147and not only limited to the PF as captured above. 148 149See for more details: https://github.com/intel/pf-bb-config 150 151Specifically for the BBDEV ACC100 PMD, the command below can be used: 152 153.. code-block:: console 154 155 ./pf_bb_config ACC100 -c acc100/acc100_config_vf_5g.cfg 156 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 157