1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2020 Intel Corporation 3 4Intel(R) ACC100 and ACC101 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. 10The BBDEV ACC101, also known as Mount Cirrus, is a derivative device from Mount Bryce 11with functional and capacity improvements but still with the same exposed BBDEV capabilities. 12 13Features 14-------- 15 16ACC100 and ACC101 5G/4G FEC PMDs support the following features: 17 18- LDPC Encode in the DL (5GNR) 19- LDPC Decode in the UL (5GNR) 20- Turbo Encode in the DL (4G) 21- Turbo Decode in the UL (4G) 22- 16 VFs per PF (physical device) 23- Maximum of 128 queues per VF 24- PCIe Gen-3 x16 Interface 25- MSI 26- SR-IOV 27 28ACC100 and ACC101 5G/4G FEC PMDs support the following BBDEV capabilities: 29 30* For the LDPC encode operation: 31 - ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` : set to attach CRC24B to CB(s) 32 - ``RTE_BBDEV_LDPC_RATE_MATCH`` : if set then do not do Rate Match bypass 33 - ``RTE_BBDEV_LDPC_INTERLEAVER_BYPASS`` : if set then bypass interleaver 34 35* For the LDPC decode operation: 36 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` : check CRC24B from CB(s) 37 - ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` : disable early termination 38 - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` : drops CRC24B bits appended while decoding 39 - ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` : provides an input for HARQ combining 40 - ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` : provides an input for HARQ combining 41 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE`` : HARQ memory input is internal 42 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE`` : HARQ memory output is internal 43 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK`` : loopback data to/from HARQ memory 44 - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS`` : HARQ memory includes the fillers bits 45 - ``RTE_BBDEV_LDPC_DEC_SCATTER_GATHER`` : supports scatter-gather for input/output data 46 - ``RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION`` : supports compression of the HARQ input/output 47 - ``RTE_BBDEV_LDPC_LLR_COMPRESSION`` : supports LLR input compression 48 49* For the turbo encode operation: 50 - ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` : set to attach CRC24B to CB(s) 51 - ``RTE_BBDEV_TURBO_RATE_MATCH`` : if set then do not do Rate Match bypass 52 - ``RTE_BBDEV_TURBO_ENC_INTERRUPTS`` : set for encoder dequeue interrupts 53 - ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` : set to bypass RV index 54 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER`` : supports scatter-gather for input/output data 55 56* For the turbo decode operation: 57 - ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` : check CRC24B from CB(s) 58 - ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` : perform subblock de-interleave 59 - ``RTE_BBDEV_TURBO_DEC_INTERRUPTS`` : set for decoder dequeue interrupts 60 - ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` : set if negative LLR encoder i/p is supported 61 - ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` : set if positive LLR encoder i/p is supported 62 - ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` : keep CRC24B bits appended while decoding 63 - ``RTE_BBDEV_TURBO_DEC_CRC_24B_DROP`` : option to drop the code block CRC after decoding 64 - ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` : set early termination feature 65 - ``RTE_BBDEV_TURBO_DEC_SCATTER_GATHER`` : supports scatter-gather for input/output data 66 - ``RTE_BBDEV_TURBO_HALF_ITERATION_EVEN`` : set half iteration granularity 67 68Installation 69------------ 70 71Section 3 of the DPDK manual provides instructions on installing and compiling DPDK. 72 73DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual. 74The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The 75hugepage configuration of a server may be examined using: 76 77.. code-block:: console 78 79 grep Huge* /proc/meminfo 80 81 82Initialization 83-------------- 84 85When the device first powers up, its PCI Physical Functions (PF) can be listed through these 86commands for ACC100 and ACC101 respectively: 87 88.. code-block:: console 89 90 sudo lspci -vd8086:0d5c 91 sudo lspci -vd8086:57c4 92 93The physical and virtual functions are compatible with Linux UIO drivers: 94``vfio`` and ``igb_uio``. However, in order to work the 5G/4G 95FEC device first needs to be bound to one of these linux drivers through DPDK. 96 97 98Bind PF UIO driver(s) 99~~~~~~~~~~~~~~~~~~~~~ 100 101Install the DPDK igb_uio driver, bind it with the PF PCI device ID and use 102``lspci`` to confirm the PF device is under use by ``igb_uio`` DPDK UIO driver. 103 104The igb_uio driver may be bound to the PF PCI device using one of two methods for ACC100 105(for ACC101 the device id ``57c4`` should be used in lieu of ``0d5c``): 106 107 1081. PCI functions (physical or virtual, depending on the use case) can be bound to 109the UIO driver by repeating this command for every function. 110 111.. code-block:: console 112 113 cd <dpdk-top-level-directory> 114 insmod ./build/kmod/igb_uio.ko 115 echo "8086 0d5c" > /sys/bus/pci/drivers/igb_uio/new_id 116 lspci -vd8086:0d5c 117 118 1192. Another way to bind PF with DPDK UIO driver is by using the ``dpdk-devbind.py`` tool 120 121.. code-block:: console 122 123 cd <dpdk-top-level-directory> 124 ./usertools/dpdk-devbind.py -b igb_uio 0000:06:00.0 125 126where the PCI device ID (example: 0000:06:00.0) is obtained using lspci -vd8086:0d5c 127 128 129In a similar way the 5G/4G FEC PF may be bound with vfio-pci as any PCIe device. 130 131 132Enable Virtual Functions 133~~~~~~~~~~~~~~~~~~~~~~~~ 134 135Now, it should be visible in the printouts that PCI PF is under igb_uio control 136"``Kernel driver in use: igb_uio``" 137 138To show the number of available VFs on the device, read ``sriov_totalvfs`` file.. 139 140.. code-block:: console 141 142 cat /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_totalvfs 143 144 where 0000\:<b>\:<d>.<f> is the PCI device ID 145 146 147To enable VFs via igb_uio, echo the number of virtual functions intended to 148enable to ``max_vfs`` file.. 149 150.. code-block:: console 151 152 echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/max_vfs 153 154 155Afterwards, all VFs must be bound to appropriate UIO drivers as required, same 156way it was done with the physical function previously. 157 158Enabling SR-IOV via vfio driver is pretty much the same, except that the file 159name is different: 160 161.. code-block:: console 162 163 echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_numvfs 164 165 166Configure the VFs through PF 167~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 168 169The PCI virtual functions must be configured before working or getting assigned 170to VMs/Containers. The configuration involves allocating the number of hardware 171queues, priorities, load balance, bandwidth and other settings necessary for the 172device to perform FEC functions. 173 174This configuration needs to be executed at least once after reboot or PCI FLR and can 175be achieved by using the functions ``rte_acc10x_configure()``, 176which sets up the parameters defined in the compatible ``acc100_conf`` structure. 177 178Test Application 179---------------- 180 181BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing 182the functionality of the device 5G/4G FEC encode and decode, depending on the device's 183capabilities. The test application is located under app->test-bbdev folder and has the 184following options: 185 186.. code-block:: console 187 188 "-p", "--testapp-path": specifies path to the bbdev test app. 189 "-e", "--eal-params" : EAL arguments which are passed to the test app. 190 "-t", "--timeout" : Timeout in seconds (default=300). 191 "-c", "--test-cases" : Defines test cases to run. Run all if not specified. 192 "-v", "--test-vector" : Test vector path (default=dpdk_path+/app/test-bbdev/test_vectors/bbdev_null.data). 193 "-n", "--num-ops" : Number of operations to process on device (default=32). 194 "-b", "--burst-size" : Operations enqueue/dequeue burst size (default=32). 195 "-s", "--snr" : SNR in dB used when generating LLRs for bler tests. 196 "-s", "--iter_max" : Number of iterations for LDPC decoder. 197 "-l", "--num-lcores" : Number of lcores to run (default=16). 198 "-i", "--init-device" : Initialise PF device with default values. 199 200 201To execute the test application tool using simple decode or encode data, 202type one of the following: 203 204.. code-block:: console 205 206 ./test-bbdev.py -c validation -n 64 -b 1 -v ./ldpc_dec_default.data 207 ./test-bbdev.py -c validation -n 64 -b 1 -v ./ldpc_enc_default.data 208 209 210The test application ``test-bbdev.py``, supports the ability to configure the PF device with 211a default set of values, if the "-i" or "- -init-device" option is included. The default values 212are defined in test_bbdev_perf.c. 213 214 215Test Vectors 216~~~~~~~~~~~~ 217 218In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides 219a range of additional tests under the test_vectors folder, which may be useful. The results 220of these tests will depend on the device 5G/4G FEC capabilities which may cause some 221testcases to be skipped, but no failure should be reported. 222 223 224Alternate Baseband Device configuration tool 225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 226 227On top of the embedded configuration feature supported in test-bbdev using "- -init-device" 228option mentioned above, there is also a tool available to perform that device configuration 229using a companion application. 230The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF 231and not only limited to the PF as captured above. 232 233See for more details: https://github.com/intel/pf-bb-config 234 235Specifically for the BBDEV ACC100 PMD, the command below can be used: 236 237.. code-block:: console 238 239 ./pf_bb_config ACC100 -c acc100/acc100_config_vf_5g.cfg 240 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 241 242Specifically for the BBDEV ACC101 PMD, the command below can be used: 243 244.. code-block:: console 245 246 ./pf_bb_config ACC101 -c acc101/acc101_config_2vf_4g5g.cfg 247 ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data 248