1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation 3 4SW Turbo Poll Mode Driver 5========================= 6 7The SW Turbo PMD (**baseband_turbo_sw**) provides a software only poll mode bbdev 8driver that can optionally utilize Intel optimized libraries for LTE and 5GNR 9Layer 1 workloads acceleration. 10 11Note that the driver can also be built without any dependency with reduced 12functionality for maintenance purpose. 13 14To enable linking to the SDK libraries see detailed installation section below. 15 16This PMD supports the functions: FEC, Rate Matching and CRC functions detailed 17in the Features section. 18 19Features 20-------- 21 22SW Turbo PMD can support for the following capabilities when the SDK libraries 23are used: 24 25For the LTE encode operation: 26 27* ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` 28* ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` 29* ``RTE_BBDEV_TURBO_RATE_MATCH`` 30* ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` 31 32For the LTE decode operation: 33 34* ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` 35* ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` 36* ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` 37* ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` 38* ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` 39* ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` 40 41For the 5G NR LDPC encode operation: 42 43* ``RTE_BBDEV_LDPC_RATE_MATCH`` 44* ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` 45* ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` 46 47For the 5G NR LDPC decode operation: 48 49* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` 50* ``RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK`` 51* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` 52* ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` 53* ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` 54* ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` 55 56Limitations 57----------- 58 59* In-place operations for encode and decode are not supported 60 61Installation 62------------ 63 64FlexRAN SDK Download 65~~~~~~~~~~~~~~~~~~~~ 66 67As an option it is possible to link this driver with FleXRAN SDK libraries 68which can enable real time signal processing using AVX instructions. 69 70These libraries are available through this `link 71<https://github.com/intel/FlexRAN-FEC-SDK-Modules/tree/Branch_FEC_SDK_23.07>`_. 72 73After download is complete, the user needs to unpack and compile on their 74system before building DPDK. 75 76To get the FlexRAN FEC SDK user manual, extract this `doxygen 77<https://github.com/intel/FlexRAN-FEC-SDK-Modules/blob/Branch_FEC_SDK_23.07/doc/doxygen/html.zip>`_. 78 79The following table maps DPDK versions with past FlexRAN SDK releases: 80 81.. _table_flexran_releases: 82 83.. table:: DPDK and FlexRAN FEC SDK releases compliance 84 85 ===================== ============================ 86 DPDK version FlexRAN FEC SDK release 87 ===================== ============================ 88 19.08 to 22.07 19.04 89 22.11+ 22.11 90 23.11+ FEC_SDK_23.07 91 ===================== ============================ 92 93FlexRAN SDK Installation 94~~~~~~~~~~~~~~~~~~~~~~~~ 95 96Note that the installation of these libraries is optional. 97 98The following are pre-requisites for building FlexRAN SDK Libraries: 99 (a) An AVX512 supporting machine. 100 (b) Ubuntu Linux release 22.04 operating system is advised. 101 (c) Intel ICX 2023.0.0 compiler or more recent and related libraries. 102 ICX is available `here <https://docs.o-ran-sc.org/projects/o-ran-sc-o-du-phy/en/latest/build_prerequisite.html#download-and-install-oneapi>`_. 103 (d) `FlexRAN SDK Modules <https://github.com/intel/FlexRAN-FEC-SDK-Modules/tree/Branch_FEC_SDK_23.07>`_. 104 (e) CMake 3.9.2 (Minimum 2.8.12) 105 (f) Google Test 1.7.0 (Required to run the verification and compute performance tests) 106 (g) Math Kernel Library 18.0 (Required by some functions in SDK) 107 108The following instructions should be followed in this exact order: 109 110#. Clone the SDK (folder name needs to end in 'sdk') 111 112 .. code-block:: console 113 114 git clone -b Branch_FEC_SDK_23.07 https://github.com/intel/FlexRAN-FEC-SDK-Modules.git flexran_sdk 115 116#. Set the environment variables: 117 118 .. code-block:: console 119 120 source <path-to-workspace>/export_settings.sh -o -avx512 121 122#. Generate makefiles based on system configuration: 123 124 .. code-block:: console 125 126 cd <path-to-workspace> 127 ./create-makefiles-linux.sh 128 129#. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that 130 folder and install: 131 132 .. code-block:: console 133 134 cd <path-to-workspace>/build-${WIRELESS_SDK_TARGET_ISA}-${WIRELESS_SDK_TOOLCHAIN}/ 135 make -j$(nproc) && make install 136 137DPDK Initialization 138~~~~~~~~~~~~~~~~~~~ 139 140In order to enable this virtual bbdev PMD, the user may: 141 142* Build the ``FLEXRAN SDK`` libraries (explained in Installation section). 143 144* Export the environmental variables ``FLEXRAN_SDK`` to the path where the 145 FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path 146 where the libraries were extracted. 147 148* Point pkgconfig towards these libraries so that they can be automatically found by meson. 149 If not, DPDK will still compile but the related functionality would be stubbed out. 150 151Example: 152 153.. code-block:: console 154 155 export FLEXRAN_SDK=<path-to-workspace>/build-${WIRELESS_SDK_TARGET_ISA}-${WIRELESS_SDK_TOOLCHAIN}/install 156 export DIR_WIRELESS_SDK=<path-to-workspace>/build-${WIRELESS_SDK_TARGET_ISA}-${WIRELESS_SDK_TOOLCHAIN} 157 export PKG_CONFIG_PATH=${DIR_WIRELESS_SDK}/pkgcfg:${PKG_CONFIG_PATH} 158 cd build 159 meson configure 160 161* For AVX512 machines with SDK libraries installed then both 4G and 5G can be enabled for full real time FEC capability. 162 For AVX2 machines it is possible to only enable the 4G libraries and the PMD capabilities will be limited to 4G FEC. 163 If no library is present then the PMD will still build but its capabilities will be limited accordingly. 164 165SW Turbo PMD Usage 166~~~~~~~~~~~~~~~~~~ 167 168To use the PMD in an application, user must: 169 170- Call ``rte_vdev_init("baseband_turbo_sw")`` within the application. 171 172- Use ``--vdev="baseband_turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally. 173 174The following parameters (all optional) can be provided in the previous two calls: 175 176* ``socket_id``: Specify the socket where the memory for the device is going to be allocated 177 (by default, *socket_id* will be the socket where the core that is creating the PMD is running on). 178 179* ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``). 180 181Example: 182 183.. code-block:: console 184 185 ./test-bbdev.py -e="--vdev=baseband_turbo_sw,socket_id=0,max_nb_queues=8" \ 186 -c validation -v ./turbo_*_default.data 187