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 <https://software.intel.com/en-us/articles/flexran-lte-and-5g-nr-fec-software-development-kit-modules>`_. 71 72After download is complete, the user needs to unpack and compile on their 73system before building DPDK. 74 75The following table maps DPDK versions with past FlexRAN SDK releases: 76 77.. _table_flexran_releases: 78 79.. table:: DPDK and FlexRAN FEC SDK releases compliance 80 81 ===================== ============================ 82 DPDK version FlexRAN FEC SDK release 83 ===================== ============================ 84 19.08 19.04 85 ===================== ============================ 86 87FlexRAN SDK Installation 88~~~~~~~~~~~~~~~~~~~~~~~~ 89 90Note that the installation of these libraries is optional. 91 92The following are pre-requisites for building FlexRAN SDK Libraries: 93 (a) An AVX2 or AVX512 supporting machine 94 (b) CentOS Linux release 7.2.1511 (Core) operating system is advised 95 (c) Intel ICC 18.0.1 20171018 compiler or more recent and related libraries 96 ICC is `available with a free community license <https://software.intel.com/en-us/system-studio/choose-download#technical>`_. 97 98The following instructions should be followed in this exact order: 99 100#. Set the environment variables: 101 102 .. code-block:: console 103 104 source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux 105 106#. Run the SDK extractor script and accept the license: 107 108 .. code-block:: console 109 110 cd <path-to-workspace> 111 ./FlexRAN-FEC-SDK-19-04.sh 112 113#. Generate makefiles based on system configuration: 114 115 .. code-block:: console 116 117 cd <path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/ 118 ./create-makefiles-linux.sh 119 120#. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that 121 folder and install: 122 123 .. code-block:: console 124 125 cd build-avx512-icc/ 126 make && make install 127 128Initialization 129-------------- 130 131In order to enable this virtual bbdev PMD, the user may: 132 133* Build the ``FLEXRAN SDK`` libraries (explained in Installation section). 134 135* Export the environmental variables ``FLEXRAN_SDK`` to the path where the 136 FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path 137 where the libraries were extracted. 138 139* Tune the meson build option pointing the location of the FlexRAN SDK libraries ``flexran_sdk`` 140 141Example: 142 143.. code-block:: console 144 145 export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/install 146 export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/ 147 cd build 148 meson configure -Dflexran_sdk=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx512-icc/install 149 150* For AVX512 machines with SDK libraries installed then both 4G and 5G can be enabled for full real time FEC capability. 151 For AVX2 machines it is possible to only enable the 4G libraries and the PMD capabilities will be limited to 4G FEC. 152 If no library is present then the PMD driver will still build but its capabilities will be limited accordingly. 153 154 155To use the PMD in an application, user must: 156 157- Call ``rte_vdev_init("baseband_turbo_sw")`` within the application. 158 159- Use ``--vdev="baseband_turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally. 160 161The following parameters (all optional) can be provided in the previous two calls: 162 163* ``socket_id``: Specify the socket where the memory for the device is going to be allocated 164 (by default, *socket_id* will be the socket where the core that is creating the PMD is running on). 165 166* ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``). 167 168Example: 169~~~~~~~~ 170 171.. code-block:: console 172 173 ./test-bbdev.py -e="--vdev=baseband_turbo_sw,socket_id=0,max_nb_queues=8" \ 174 -c validation -v ./turbo_*_default.data 175