]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2017 Intel Corporation | |
3 | ||
4 | SW Turbo Poll Mode Driver | |
5 | ========================= | |
6 | ||
f67539c2 TL |
7 | The SW Turbo PMD (**baseband_turbo_sw**) provides a software only poll mode bbdev |
8 | driver that can optionally utilize Intel optimized libraries for LTE and 5GNR | |
9 | Layer 1 workloads acceleration. | |
10 | ||
11 | Note that the driver can also be built without any dependency with reduced | |
12 | functionality for maintenance purpose. | |
13 | ||
14 | To enable linking to the SDK libraries see detailed installation section below. | |
15 | Two flags can be enabled depending on whether the target machine can support | |
16 | AVX2 and AVX512 instructions sets and the related SDK libraries for vectorized | |
17 | signal processing functions are installed : | |
18 | - CONFIG_RTE_BBDEV_SDK_AVX2 | |
19 | - CONFIG_RTE_BBDEV_SDK_AVX512 | |
20 | By default these 2 flags are disabled by default. For AVX2 machine and SDK | |
21 | library installed then the first flag can be enabled. For AVX512 machine and | |
22 | SDK library installed then both flags can be enabled for full real time capability. | |
23 | ||
24 | This PMD supports the functions: FEC, Rate Matching and CRC functions detailed | |
25 | in the Features section. | |
11fdf7f2 TL |
26 | |
27 | Features | |
28 | -------- | |
29 | ||
f67539c2 TL |
30 | SW Turbo PMD can support for the following capabilities when the SDK libraries |
31 | are used: | |
11fdf7f2 | 32 | |
f67539c2 | 33 | For the LTE encode operation: |
11fdf7f2 TL |
34 | |
35 | * ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` | |
36 | * ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` | |
37 | * ``RTE_BBDEV_TURBO_RATE_MATCH`` | |
38 | * ``RTE_BBDEV_TURBO_RV_INDEX_BYPASS`` | |
39 | ||
f67539c2 | 40 | For the LTE decode operation: |
11fdf7f2 TL |
41 | |
42 | * ``RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE`` | |
43 | * ``RTE_BBDEV_TURBO_CRC_TYPE_24B`` | |
44 | * ``RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN`` | |
45 | * ``RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN`` | |
46 | * ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` | |
47 | * ``RTE_BBDEV_TURBO_EARLY_TERMINATION`` | |
48 | ||
f67539c2 TL |
49 | For the 5G NR LDPC encode operation: |
50 | ||
51 | * ``RTE_BBDEV_LDPC_RATE_MATCH`` | |
52 | * ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` | |
53 | * ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` | |
54 | ||
55 | For the 5G NR LDPC decode operation: | |
56 | ||
57 | * ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` | |
58 | * ``RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK`` | |
59 | * ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` | |
60 | * ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` | |
61 | * ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` | |
62 | * ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` | |
11fdf7f2 TL |
63 | |
64 | Limitations | |
65 | ----------- | |
66 | ||
f67539c2 | 67 | * In-place operations for encode and decode are not supported |
11fdf7f2 TL |
68 | |
69 | Installation | |
70 | ------------ | |
71 | ||
72 | FlexRAN SDK Download | |
73 | ~~~~~~~~~~~~~~~~~~~~ | |
74 | ||
f67539c2 TL |
75 | As an option it is possible to link this driver with FleXRAN SDK libraries |
76 | which can enable real time signal processing using AVX instructions. | |
11fdf7f2 | 77 | |
f67539c2 | 78 | These libraries are available through this `link <https://software.intel.com/en-us/articles/flexran-lte-and-5g-nr-fec-software-development-kit-modules>`_. |
11fdf7f2 TL |
79 | |
80 | After download is complete, the user needs to unpack and compile on their | |
81 | system before building DPDK. | |
82 | ||
83 | The following table maps DPDK versions with past FlexRAN SDK releases: | |
84 | ||
85 | .. _table_flexran_releases: | |
86 | ||
f67539c2 | 87 | .. table:: DPDK and FlexRAN FEC SDK releases compliance |
11fdf7f2 TL |
88 | |
89 | ===================== ============================ | |
f67539c2 | 90 | DPDK version FlexRAN FEC SDK release |
11fdf7f2 | 91 | ===================== ============================ |
f67539c2 | 92 | 19.08 19.04 |
11fdf7f2 TL |
93 | ===================== ============================ |
94 | ||
95 | FlexRAN SDK Installation | |
96 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
97 | ||
f67539c2 TL |
98 | Note that the installation of these libraries is optional. |
99 | ||
11fdf7f2 | 100 | The following are pre-requisites for building FlexRAN SDK Libraries: |
f67539c2 TL |
101 | (a) An AVX2 or AVX512 supporting machine |
102 | (b) CentOS Linux release 7.2.1511 (Core) operating system is advised | |
103 | (c) Intel ICC 18.0.1 20171018 compiler or more recent and related libraries | |
104 | ICC is `available with a free community license <https://software.intel.com/en-us/system-studio/choose-download#technical>`_. | |
11fdf7f2 TL |
105 | |
106 | The following instructions should be followed in this exact order: | |
107 | ||
108 | #. Set the environment variables: | |
109 | ||
110 | .. code-block:: console | |
111 | ||
112 | source <path-to-icc-compiler-install-folder>/linux/bin/compilervars.sh intel64 -platform linux | |
113 | ||
11fdf7f2 TL |
114 | #. Run the SDK extractor script and accept the license: |
115 | ||
116 | .. code-block:: console | |
117 | ||
f67539c2 TL |
118 | cd <path-to-workspace> |
119 | ./FlexRAN-FEC-SDK-19-04.sh | |
11fdf7f2 TL |
120 | |
121 | #. Generate makefiles based on system configuration: | |
122 | ||
123 | .. code-block:: console | |
124 | ||
f67539c2 | 125 | cd <path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/ |
11fdf7f2 TL |
126 | ./create-makefiles-linux.sh |
127 | ||
128 | #. A build folder is generated in this form ``build-<ISA>-<CC>``, enter that | |
129 | folder and install: | |
130 | ||
131 | .. code-block:: console | |
132 | ||
f67539c2 | 133 | cd build-avx512-icc/ |
11fdf7f2 TL |
134 | make && make install |
135 | ||
11fdf7f2 TL |
136 | Initialization |
137 | -------------- | |
138 | ||
f67539c2 | 139 | In order to enable this virtual bbdev PMD, the user may: |
11fdf7f2 TL |
140 | |
141 | * Build the ``FLEXRAN SDK`` libraries (explained in Installation section). | |
142 | ||
143 | * Export the environmental variables ``FLEXRAN_SDK`` to the path where the | |
144 | FlexRAN SDK libraries were installed. And ``DIR_WIRELESS_SDK`` to the path | |
145 | where the libraries were extracted. | |
146 | ||
147 | Example: | |
148 | ||
149 | .. code-block:: console | |
150 | ||
f67539c2 TL |
151 | export FLEXRAN_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/install |
152 | export DIR_WIRELESS_SDK=<path-to-workspace>/FlexRAN-FEC-SDK-19-04/sdk/build-avx2-icc/ | |
11fdf7f2 | 153 | |
f67539c2 TL |
154 | * Set ``CONFIG_RTE_BBDEV_SDK_AVX2=y`` and ``CONFIG_RTE_BBDEV_SDK_AVX512=y`` |
155 | in DPDK common configuration file ``config/common_base`` to be able to use | |
156 | the SDK libraries as mentioned above. | |
157 | For AVX2 machine it is possible to only enable CONFIG_RTE_BBDEV_SDK_AVX2 | |
158 | for limited 4G functionality. | |
159 | If no flag are set the PMD driver will still build but its capabilities | |
160 | will be limited accordingly. | |
11fdf7f2 TL |
161 | |
162 | To use the PMD in an application, user must: | |
163 | ||
164 | - Call ``rte_vdev_init("baseband_turbo_sw")`` within the application. | |
165 | ||
166 | - Use ``--vdev="baseband_turbo_sw"`` in the EAL options, which will call ``rte_vdev_init()`` internally. | |
167 | ||
168 | The following parameters (all optional) can be provided in the previous two calls: | |
169 | ||
170 | * ``socket_id``: Specify the socket where the memory for the device is going to be allocated | |
171 | (by default, *socket_id* will be the socket where the core that is creating the PMD is running on). | |
172 | ||
173 | * ``max_nb_queues``: Specify the maximum number of queues in the device (default is ``RTE_MAX_LCORE``). | |
174 | ||
175 | Example: | |
176 | ~~~~~~~~ | |
177 | ||
178 | .. code-block:: console | |
179 | ||
180 | ./test-bbdev.py -e="--vdev=baseband_turbo_sw,socket_id=0,max_nb_queues=8" \ | |
181 | -c validation -v ./turbo_*_default.data |