xref: /dpdk/doc/guides/bbdevs/fpga_5gnr_fec.rst (revision 9e3ffd3873fbd82ddd769301b6fd1eb64f4880bb)
1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2019 Intel Corporation
3
4Intel(R) FPGA 5GNR FEC Poll Mode Driver
5=======================================
6
7The BBDEV FPGA 5GNR FEC poll mode driver (PMD) supports an FPGA implementation of a VRAN
8LDPC Encode / Decode 5GNR wireless acceleration function, using Intel's PCI-e and FPGA
9based Vista Creek (N3000, referred to as VC_5GNR in the code)
10as well as Arrow Creek (N6000, referred to as AGX100 in the code).
11
12Features
13--------
14
15FPGA 5GNR FEC PMD supports the following BBDEV capabilities:
16
17- LDPC Encode in the DL
18- LDPC Decode in the UL
19- 8 VFs per PF (physical device)
20- Maximum of 32 UL queues per VF
21- Maximum of 32 DL queues per VF
22- PCIe Gen-3 x8 Interface
23- MSI-X
24- SR-IOV
25
26FPGA 5GNR FEC PMD supports the following BBDEV capabilities:
27
28* For the LDPC encode operation:
29   - ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` :  set to attach CRC24B to CB(s)
30   - ``RTE_BBDEV_LDPC_RATE_MATCH`` :  if set then do not do Rate Match bypass
31
32* For the LDPC decode operation:
33   - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK`` :  check CRC24B from CB(s)
34   - ``RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE`` :  disable early termination
35   - ``RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP`` :  drops CRC24B bits appended while decoding
36   - ``RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE`` :  provides an input for HARQ combining
37   - ``RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE`` :  provides an input for HARQ combining
38   - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE`` :  HARQ memory input is internal
39   - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE`` :  HARQ memory output is internal
40   - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK`` :  loopback data to/from HARQ memory
41   - ``RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS`` :  HARQ memory includes the fillers bits
42
43
44Limitations
45-----------
46
47FPGA 5GNR FEC does not support the following:
48
49- Scatter-Gather function
50
51
52Installation
53------------
54
55Section 3 of the DPDK manual provides instructions on installing and compiling DPDK.
56
57DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual.
58The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The
59hugepage configuration of a server may be examined using:
60
61.. code-block:: console
62
63   grep Huge* /proc/meminfo
64
65
66Initialization
67--------------
68
69When the device first powers up, its PCI Physical Functions (PF) can be listed through this command:
70
71Vista Creek (N3000)
72
73.. code-block:: console
74
75  sudo lspci -vd8086:0d8f
76
77Arrow Creek (N6000)
78
79.. code-block:: console
80
81  sudo lspci -vd8086:5799
82
83The physical and virtual functions are compatible with Linux UIO drivers:
84``vfio_pci`` and ``igb_uio``. However, in order to work the FPGA 5GNR FEC device firstly needs
85to be bound to one of these linux drivers through DPDK.
86
87For more details on how to bind the PF device and create VF devices, see
88:ref:`linux_gsg_binding_kernel`.
89
90
91Configure the VFs through PF
92~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
94The PCI virtual functions must be configured before working or getting assigned
95to VMs/Containers. The configuration involves allocating the number of hardware
96queues, priorities, load balance, bandwidth and other settings necessary for the
97device to perform FEC functions.
98
99This configuration needs to be executed at least once after reboot or PCI FLR and can
100be achieved by using the function ``rte_fpga_5gnr_fec_configure()``, which sets up the
101parameters defined in ``rte_fpga_5gnr_fec_conf`` structure:
102
103.. code-block:: c
104
105  struct rte_fpga_5gnr_fec_conf {
106      bool pf_mode_en;
107      uint8_t vf_ul_queues_number[FPGA_5GNR_FEC_NUM_VFS];
108      uint8_t vf_dl_queues_number[FPGA_5GNR_FEC_NUM_VFS];
109      uint8_t ul_bandwidth;
110      uint8_t dl_bandwidth;
111      uint8_t ul_load_balance;
112      uint8_t dl_load_balance;
113  };
114
115- ``pf_mode_en``: identifies whether only PF is to be used, or the VFs. PF and
116  VFs are mutually exclusive and cannot run simultaneously.
117  Set to 1 for PF mode enabled.
118  If PF mode is enabled all queues available in the device are assigned
119  exclusively to PF and 0 queues given to VFs.
120
121- ``vf_*l_queues_number``: defines the hardware queue mapping for every VF.
122
123- ``*l_bandwidth``: Only used for the Vista Creek schedule algorithm
124  in case of congestion on PCIe interface.
125  The device allocates different bandwidth to UL and DL.
126  The weight is configured by this setting.
127  The unit of weight is 3 code blocks.
128  For example, if the code block cbps (code block per second) ratio
129  between UL and DL is 12:1, then the configuration value should be set to 36:3.
130  The schedule algorithm is based on code block regardless the length of each block.
131
132- ``*l_load_balance``: hardware queues are load-balanced in a round-robin
133  fashion. Queues get filled first-in first-out until they reach a pre-defined
134  watermark level, if exceeded, they won't get assigned new code blocks..
135  This watermark is defined by this setting.
136
137  If all hardware queues exceeds the watermark, no code blocks will be
138  streamed in from UL/DL code block FIFO.
139
140
141An example configuration code calling the function ``rte_fpga_5gnr_fec_configure()`` is shown
142below:
143
144.. code-block:: c
145
146  struct rte_fpga_5gnr_fec_conf conf;
147  unsigned int i;
148
149  memset(&conf, 0, sizeof(struct rte_fpga_5gnr_fec_conf));
150  conf.pf_mode_en = 1;
151
152  for (i = 0; i < FPGA_5GNR_FEC_NUM_VFS; ++i) {
153      conf.vf_ul_queues_number[i] = 4;
154      conf.vf_dl_queues_number[i] = 4;
155  }
156  conf.ul_bandwidth = 12;
157  conf.dl_bandwidth = 5;
158  conf.dl_load_balance = 64;
159  conf.ul_load_balance = 64;
160
161  /* setup FPGA PF */
162  ret = rte_fpga_5gnr_fec_configure(info->dev_name, &conf);
163  TEST_ASSERT_SUCCESS(ret,
164      "Failed to configure 5GNR FPGA PF for bbdev %s",
165      info->dev_name);
166
167
168Test Application
169----------------
170
171BBDEV provides a test application, ``test-bbdev.py`` and range of test data for testing
172the functionality of the device, depending on the device's capabilities.
173
174.. code-block:: console
175
176   "-p", "--testapp-path": specifies path to the bbdev test app.
177   "-e", "--eal-params"	: EAL arguments which are passed to the test app.
178   "-t", "--timeout"	: Timeout in seconds (default=300).
179   "-c", "--test-cases"	: Defines test cases to run. Run all if not specified.
180   "-v", "--test-vector"	: Test vector path (default=dpdk_path+/app/test-bbdev/test_vectors/bbdev_null.data).
181   "-n", "--num-ops"	: Number of operations to process on device (default=32).
182   "-b", "--burst-size"	: Operations enqueue/dequeue burst size (default=32).
183   "-l", "--num-lcores"	: Number of lcores to run (default=16).
184   "-i", "--init-device" : Initialise PF device with default values.
185
186
187To execute the test application tool using simple decode or encode data,
188type one of the following:
189
190.. code-block:: console
191
192   ./test-bbdev.py -c validation -n 64 -b 1 -v ./ldpc_dec_default.data
193   ./test-bbdev.py -c validation -n 64 -b 1 -v ./ldpc_enc_default.data
194
195
196The test application ``test-bbdev.py`` supports the ability to configure the PF device
197with a default set of values, if the "-i" or "- -init-device" option is included.
198The default values are defined in ``test_bbdev_perf.c`` as:
199
200- VF_UL_QUEUE_VALUE 4
201- VF_DL_QUEUE_VALUE 4
202- UL_BANDWIDTH 3
203- DL_BANDWIDTH 3
204- UL_LOAD_BALANCE 128
205- DL_LOAD_BALANCE 128
206
207
208Test Vectors
209~~~~~~~~~~~~
210
211In addition to the simple LDPC decoder and LDPC encoder tests, bbdev also provides
212a range of additional tests under the test_vectors folder, which may be useful. The results
213of these tests will depend on the FPGA 5GNR FEC capabilities.
214
215
216Alternate Baseband Device configuration tool
217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
218
219On top of the embedded configuration feature supported in test-bbdev using "- -init-device"
220option, there is also a tool available to perform that device configuration using a companion
221application.
222The ``pf_bb_config`` application notably enables then to run bbdev-test from the VF
223and not only limited to the PF as captured above.
224
225See for more details: https://github.com/intel/pf-bb-config
226
227Specifically for the BBDEV FPGA 5GNR FEC PMD, the command below can be used:
228
229Vista Creek (N3000)
230
231.. code-block:: console
232
233  ./pf_bb_config FPGA_5GNR -c fpga_5gnr/fpga_5gnr_config_vf.cfg
234  ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data
235
236Arrow Creek (N6000)
237
238.. code-block:: console
239
240  ./pf_bb_config AGX100 -c agx100/agx100_config_1vf.cfg
241  ./test-bbdev.py -e="-c 0xff0 -a${VF_PCI_ADDR}" -c validation -n 64 -b 32 -l 1 -v ./ldpc_dec_default.data
242