X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fbbdevs%2Fturbo_sw.rst;h=20620c2e20936d0f9e0d57d72b442279365530ea;hb=f772cc424c455e123c649b130964fffacd6d3a5e;hp=b3fed163c7438d7cc8f54085cf3fccda5882e5ca;hpb=b8cfe2c9aed2e7c0aef7d426daf96a08fea2c012;p=dpdk.git diff --git a/doc/guides/bbdevs/turbo_sw.rst b/doc/guides/bbdevs/turbo_sw.rst index b3fed163c7..20620c2e20 100644 --- a/doc/guides/bbdevs/turbo_sw.rst +++ b/doc/guides/bbdevs/turbo_sw.rst @@ -4,34 +4,67 @@ SW Turbo Poll Mode Driver ========================= -The SW Turbo PMD (**turbo_sw**) provides a poll mode bbdev driver that utilizes -Intel optimized libraries for LTE Layer 1 workloads acceleration. This PMD -supports the functions: Turbo FEC, Rate Matching and CRC functions. +The SW Turbo PMD (**baseband_turbo_sw**) provides a software only poll mode bbdev +driver that can optionally utilize Intel optimized libraries for LTE and 5GNR +Layer 1 workloads acceleration. + +Note that the driver can also be built without any dependency with reduced +functionality for maintenance purpose. + +To enable linking to the SDK libraries see detailed installation section below. +Two flags can be enabled depending on whether the target machine can support +AVX2 and AVX512 instructions sets and the related SDK libraries for vectorized +signal processing functions are installed : +- CONFIG_RTE_BBDEV_SDK_AVX2 +- CONFIG_RTE_BBDEV_SDK_AVX512 +By default these 2 flags are disabled by default. For AVX2 machine and SDK +library installed then the first flag can be enabled. For AVX512 machine and +SDK library installed then both flags can be enabled for full real time capability. + +This PMD supports the functions: FEC, Rate Matching and CRC functions detailed +in the Features section. Features -------- -SW Turbo PMD has support for the following capabilities: +SW Turbo PMD can support for the following capabilities when the SDK libraries +are used: -For the encode operation: +For the LTE encode operation: * ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` * ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` * ``RTE_BBDEV_TURBO_RATE_MATCH`` * ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` -For the decode operation: +For the LTE decode operation: * ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` * ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` * ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` * ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` +* ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` +* ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` +For the 5G NR LDPC encode operation: + +* ``RTE_BBDEV_LDPC_RATE_MATCH`` +* ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` +* ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` + +For the 5G NR LDPC decode operation: + +* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` +* ``RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK`` +* ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` +* ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` +* ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` +* ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` Limitations ----------- -* In-place operations for Turbo encode and decode are not supported +* In-place operations for encode and decode are not supported Installation ------------ @@ -39,25 +72,36 @@ Installation FlexRAN SDK Download ~~~~~~~~~~~~~~~~~~~~ -To build DPDK with the *turbo_sw* PMD the user is required to download -the export controlled ``FlexRAN SDK`` Libraries. An account at Intel Resource -Design Center needs to be registered from -``_. +As an option it is possible to link this driver with FleXRAN SDK libraries +which can enable real time signal processing using AVX instructions. -Once registered, the user needs to log in, and look for -*Intel SWA_SW_FlexRAN_Release_Package R1_3_0* and click for download. Or use -this direct download link ``_. +These libraries are available through this `link `_. After download is complete, the user needs to unpack and compile on their system before building DPDK. +The following table maps DPDK versions with past FlexRAN SDK releases: + +.. _table_flexran_releases: + +.. table:: DPDK and FlexRAN FEC SDK releases compliance + + ===================== ============================ + DPDK version FlexRAN FEC SDK release + ===================== ============================ + 19.08 19.04 + ===================== ============================ + FlexRAN SDK Installation ~~~~~~~~~~~~~~~~~~~~~~~~ +Note that the installation of these libraries is optional. + The following are pre-requisites for building FlexRAN SDK Libraries: - (a) An AVX2 supporting machine - (b) Windriver TS 2 or CentOS 7 operating systems - (c) Intel ICC compiler installed + (a) An AVX2 or AVX512 supporting machine + (b) CentOS Linux release 7.2.1511 (Core) operating system is advised + (c) Intel ICC 18.0.1 20171018 compiler or more recent and related libraries + ICC is `available with a free community license `_. The following instructions should be followed in this exact order: @@ -67,31 +111,18 @@ The following instructions should be followed in this exact order: source /linux/bin/compilervars.sh intel64 -platform linux - -#. Extract the ``FlexRAN-1.3.0.tar.gz.zip`` package, then run the SDK extractor - script and accept the license: +#. Run the SDK extractor script and accept the license: .. code-block:: console - cd /FlexRAN-1.3.0/ - ./SDK-R1.3.0.sh - -#. To allow ``FlexRAN SDK R1.3.0`` to work with bbdev properly, the following - hotfix is required. Change the return of function ``rate_matching_turbo_lte_avx2()`` - located in file - ``/FlexRAN-1.3.0/SDK-R1.3.0/sdk/source/phy/lib_rate_matching/phy_rate_match_avx2.cpp`` - to return 0 instead of 1. - - .. code-block:: c - - - return 1; - + return 0; + cd + ./FlexRAN-FEC-SDK-19-04.sh #. Generate makefiles based on system configuration: .. code-block:: console - cd /FlexRAN-1.3.0/SDK-R1.3.0/sdk/ + cd /FlexRAN-FEC-SDK-19-04/sdk/ ./create-makefiles-linux.sh #. A build folder is generated in this form ``build--``, enter that @@ -99,14 +130,13 @@ The following instructions should be followed in this exact order: .. code-block:: console - cd build-avx2-icc/ - make install - + cd build-avx512-icc/ + make && make install Initialization -------------- -In order to enable this virtual bbdev PMD, the user must: +In order to enable this virtual bbdev PMD, the user may: * Build the ``FLEXRAN SDK`` libraries (explained in Installation section). @@ -118,18 +148,22 @@ Example: .. code-block:: console - export FLEXRAN_SDK=/FlexRAN-1.3.0/SDK-R1.3.0/sdk/build-avx2-icc/install - export DIR_WIRELESS_SDK=/FlexRAN-1.3.0/SDK-R1.3.0/sdk/ - + export FLEXRAN_SDK=/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/install + export DIR_WIRELESS_SDK=/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/ -* Set ``CONFIG_RTE_LIBRTE_PMD_BBDEV_TURBO_SW=y`` in DPDK common configuration - file ``config/common_base``. +* Set ``CONFIG_RTE_BBDEV_SDK_AVX2=y`` and ``CONFIG_RTE_BBDEV_SDK_AVX512=y`` + in DPDK common configuration file ``config/common_base`` to be able to use + the SDK libraries as mentioned above. + For AVX2 machine it is possible to only enable CONFIG_RTE_BBDEV_SDK_AVX2 + for limited 4G functionality. + If no flag are set the PMD driver will still build but its capabilities + will be limited accordingly. To use the PMD in an application, user must: -- Call ``rte_vdev_init("turbo_sw")`` within the application. +- Call ``rte_vdev_init("baseband_turbo_sw")`` within the application. -- Use ``--vdev="turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally. +- Use ``--vdev="baseband_turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally. The following parameters (all optional) can be provided in the previous two calls: @@ -143,5 +177,5 @@ Example: .. code-block:: console - ./test-bbdev.py -e="--vdev=turbo_sw,socket_id=0,max_nb_queues=8" \ - -c validation -v ./test_vectors/bbdev_vector_t?_default.data + ./test-bbdev.py -e="--vdev=baseband_turbo_sw,socket_id=0,max_nb_queues=8" \ + -c validation -v ./turbo_*_default.data