1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation
3 */
4
5 #ifndef _RTE_BBDEV_OP_H_
6 #define _RTE_BBDEV_OP_H_
7
8 /**
9 * @file rte_bbdev_op.h
10 *
11 * Defines wireless base band layer 1 operations and capabilities
12 *
13 * @warning
14 * @b EXPERIMENTAL: this API may change without prior notice
15 */
16
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20
21 #include <stdint.h>
22
23 #include <rte_common.h>
24 #include <rte_mbuf.h>
25 #include <rte_memory.h>
26 #include <rte_mempool.h>
27
28 /* Number of columns in sub-block interleaver (36.212, section 5.1.4.1.1) */
29 #define RTE_BBDEV_TURBO_C_SUBBLOCK (32)
30 /* Maximum size of Transport Block (36.213, Table, Table 7.1.7.2.5-1) */
31 #define RTE_BBDEV_TURBO_MAX_TB_SIZE (391656)
32 /* Maximum size of Code Block (36.212, Table 5.1.3-3) */
33 #define RTE_BBDEV_TURBO_MAX_CB_SIZE (6144)
34 /* Maximum size of Code Block */
35 #define RTE_BBDEV_LDPC_MAX_CB_SIZE (8448)
36 /* Minimum size of Code Block */
37 #define RTE_BBDEV_LDPC_MIN_CB_SIZE (40)
38 /* Maximum E size we can manage with default mbuf */
39 #define RTE_BBDEV_LDPC_E_MAX_MBUF (64000)
40 /* Minimum size of Code Block (36.212, Table 5.1.3-3) */
41 #define RTE_BBDEV_TURBO_MIN_CB_SIZE (40)
42 /* Maximum size of circular buffer */
43 #define RTE_BBDEV_TURBO_MAX_KW (18528)
44 /*
45 * Turbo: Maximum number of Code Blocks in Transport Block. It is calculated
46 * based on maximum size of one Code Block and one Transport Block
47 * (considering CRC24A and CRC24B):
48 * (391656 + 24) / (6144 - 24) = 64
49 */
50 #define RTE_BBDEV_TURBO_MAX_CODE_BLOCKS (64)
51 /* LDPC: Maximum number of Code Blocks in Transport Block.*/
52 #define RTE_BBDEV_LDPC_MAX_CODE_BLOCKS (256)
53
54 /** Flags for turbo decoder operation and capability structure */
55 enum rte_bbdev_op_td_flag_bitmasks {
56 /** If sub block de-interleaving is to be performed. */
57 RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE = (1ULL << 0),
58 /** To use CRC Type 24B (otherwise use CRC Type 24A). */
59 RTE_BBDEV_TURBO_CRC_TYPE_24B = (1ULL << 1),
60 /** If turbo equalization is to be performed. */
61 RTE_BBDEV_TURBO_EQUALIZER = (1ULL << 2),
62 /** If set, saturate soft output to +/-127 */
63 RTE_BBDEV_TURBO_SOFT_OUT_SATURATE = (1ULL << 3),
64 /** Set to 1 to start iteration from even, else odd; one iteration =
65 * max_iteration + 0.5
66 */
67 RTE_BBDEV_TURBO_HALF_ITERATION_EVEN = (1ULL << 4),
68 /** If 0, TD stops after CRC matches; else if 1, runs to end of next
69 * odd iteration after CRC matches
70 */
71 RTE_BBDEV_TURBO_CONTINUE_CRC_MATCH = (1ULL << 5),
72 /** Set if soft output is required to be output */
73 RTE_BBDEV_TURBO_SOFT_OUTPUT = (1ULL << 6),
74 /** Set to enable early termination mode */
75 RTE_BBDEV_TURBO_EARLY_TERMINATION = (1ULL << 7),
76 /** Set if a device supports decoder dequeue interrupts */
77 RTE_BBDEV_TURBO_DEC_INTERRUPTS = (1ULL << 9),
78 /** Set if positive LLR encoded input is supported. Positive LLR value
79 * represents the level of confidence for bit '1', and vice versa for
80 * bit '0'.
81 * This is mutually exclusive with RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN
82 * when used to formalize the input data format.
83 */
84 RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN = (1ULL << 10),
85 /** Set if negative LLR encoded input is supported. Negative LLR value
86 * represents the level of confidence for bit '1', and vice versa for
87 * bit '0'.
88 * This is mutually exclusive with RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN
89 * when used to formalize the input data format.
90 */
91 RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN = (1ULL << 11),
92 /** Set if positive LLR soft output is supported. Positive LLR value
93 * represents the level of confidence for bit '1', and vice versa for
94 * bit '0'.
95 * This is mutually exclusive with
96 * RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT when used to formalize
97 * the input data format.
98 */
99 RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT = (1ULL << 12),
100 /** Set if negative LLR soft output is supported. Negative LLR value
101 * represents the level of confidence for bit '1', and vice versa for
102 * bit '0'.
103 * This is mutually exclusive with
104 * RTE_BBDEV_TURBO_POS_LLR_1_BIT_SOFT_OUT when used to formalize the
105 * input data format.
106 */
107 RTE_BBDEV_TURBO_NEG_LLR_1_BIT_SOFT_OUT = (1ULL << 13),
108 /** Set if driver supports flexible parallel MAP engine decoding. If
109 * not supported, num_maps (number of MAP engines) argument is unusable.
110 */
111 RTE_BBDEV_TURBO_MAP_DEC = (1ULL << 14),
112 /** Set if a device supports scatter-gather functionality */
113 RTE_BBDEV_TURBO_DEC_SCATTER_GATHER = (1ULL << 15),
114 /** Set to keep CRC24B bits appended while decoding. Only usable when
115 * decoding Transport Blocks (code_block_mode = 0).
116 */
117 RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP = (1ULL << 16)
118 };
119
120
121 /** Flags for turbo encoder operation and capability structure */
122 enum rte_bbdev_op_te_flag_bitmasks {
123 /** Ignore rv_index and set K0 = 0 */
124 RTE_BBDEV_TURBO_RV_INDEX_BYPASS = (1ULL << 0),
125 /** If rate matching is to be performed */
126 RTE_BBDEV_TURBO_RATE_MATCH = (1ULL << 1),
127 /** This bit must be set to enable CRC-24B generation */
128 RTE_BBDEV_TURBO_CRC_24B_ATTACH = (1ULL << 2),
129 /** This bit must be set to enable CRC-24A generation */
130 RTE_BBDEV_TURBO_CRC_24A_ATTACH = (1ULL << 3),
131 /** Set if a device supports encoder dequeue interrupts */
132 RTE_BBDEV_TURBO_ENC_INTERRUPTS = (1ULL << 4),
133 /** Set if a device supports scatter-gather functionality */
134 RTE_BBDEV_TURBO_ENC_SCATTER_GATHER = (1ULL << 5)
135 };
136
137 /** Flags for LDPC decoder operation and capability structure */
138 enum rte_bbdev_op_ldpcdec_flag_bitmasks {
139 /** Set for transport block CRC-24A checking */
140 RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK = (1ULL << 0),
141 /** Set for code block CRC-24B checking */
142 RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK = (1ULL << 1),
143 /** Set to drop the last CRC bits decoding output */
144 RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP = (1ULL << 2),
145 /** Set for bit-level de-interleaver bypass on Rx stream. */
146 RTE_BBDEV_LDPC_DEINTERLEAVER_BYPASS = (1ULL << 3),
147 /** Set for HARQ combined input stream enable. */
148 RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE = (1ULL << 4),
149 /** Set for HARQ combined output stream enable. */
150 RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE = (1ULL << 5),
151 /** Set for LDPC decoder bypass.
152 * RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE must be set.
153 */
154 RTE_BBDEV_LDPC_DECODE_BYPASS = (1ULL << 6),
155 /** Set for soft-output stream enable */
156 RTE_BBDEV_LDPC_SOFT_OUT_ENABLE = (1ULL << 7),
157 /** Set for Rate-Matching bypass on soft-out stream. */
158 RTE_BBDEV_LDPC_SOFT_OUT_RM_BYPASS = (1ULL << 8),
159 /** Set for bit-level de-interleaver bypass on soft-output stream. */
160 RTE_BBDEV_LDPC_SOFT_OUT_DEINTERLEAVER_BYPASS = (1ULL << 9),
161 /** Set for iteration stopping on successful decode condition
162 * i.e. a successful syndrome check.
163 */
164 RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE = (1ULL << 10),
165 /** Set if a device supports decoder dequeue interrupts. */
166 RTE_BBDEV_LDPC_DEC_INTERRUPTS = (1ULL << 11),
167 /** Set if a device supports scatter-gather functionality. */
168 RTE_BBDEV_LDPC_DEC_SCATTER_GATHER = (1ULL << 12),
169 /** Set if a device supports input/output HARQ compression. */
170 RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION = (1ULL << 13),
171 /** Set if a device supports input LLR compression. */
172 RTE_BBDEV_LDPC_LLR_COMPRESSION = (1ULL << 14),
173 /** Set if a device supports HARQ input from
174 * device's internal memory.
175 */
176 RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE = (1ULL << 15),
177 /** Set if a device supports HARQ output to
178 * device's internal memory.
179 */
180 RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE = (1ULL << 16),
181 /** Set if a device supports loop-back access to
182 * HARQ internal memory. Intended for troubleshooting.
183 */
184 RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK = (1ULL << 17),
185 /** Set if a device includes LLR filler bits in the circular buffer
186 * for HARQ memory. If not set, it is assumed the filler bits are not
187 * in HARQ memory and handled directly by the LDPC decoder.
188 */
189 RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS = (1ULL << 18)
190 };
191
192 /** Flags for LDPC encoder operation and capability structure */
193 enum rte_bbdev_op_ldpcenc_flag_bitmasks {
194 /** Set for bit-level interleaver bypass on output stream. */
195 RTE_BBDEV_LDPC_INTERLEAVER_BYPASS = (1ULL << 0),
196 /** If rate matching is to be performed */
197 RTE_BBDEV_LDPC_RATE_MATCH = (1ULL << 1),
198 /** Set for transport block CRC-24A attach */
199 RTE_BBDEV_LDPC_CRC_24A_ATTACH = (1ULL << 2),
200 /** Set for code block CRC-24B attach */
201 RTE_BBDEV_LDPC_CRC_24B_ATTACH = (1ULL << 3),
202 /** Set for code block CRC-16 attach */
203 RTE_BBDEV_LDPC_CRC_16_ATTACH = (1ULL << 4),
204 /** Set if a device supports encoder dequeue interrupts. */
205 RTE_BBDEV_LDPC_ENC_INTERRUPTS = (1ULL << 5),
206 /** Set if a device supports scatter-gather functionality. */
207 RTE_BBDEV_LDPC_ENC_SCATTER_GATHER = (1ULL << 6),
208 /** Set if a device supports concatenation of non byte aligned output */
209 RTE_BBDEV_LDPC_ENC_CONCATENATION = (1ULL << 7)
210 };
211
212 /** Data input and output buffer for BBDEV operations */
213 struct rte_bbdev_op_data {
214 /** The mbuf data structure representing the data for BBDEV operation.
215 *
216 * This mbuf pointer can point to one Code Block (CB) data buffer or
217 * multiple CBs contiguously located next to each other.
218 * A Transport Block (TB) represents a whole piece of data that is
219 * divided into one or more CBs. Maximum number of CBs can be contained
220 * in one TB is defined by RTE_BBDEV_(TURBO/LDPC)_MAX_CODE_BLOCKS.
221 *
222 * An mbuf data structure cannot represent more than one TB. The
223 * smallest piece of data that can be contained in one mbuf is one CB.
224 * An mbuf can include one contiguous CB, subset of contiguous CBs that
225 * are belonging to one TB, or all contiguous CBs that are belonging to
226 * one TB.
227 *
228 * If a BBDEV PMD supports the extended capability "Scatter-Gather",
229 * then it is capable of collecting (gathering) non-contiguous
230 * (scattered) data from multiple locations in the memory.
231 * This capability is reported by the capability flags:
232 * - RTE_BBDEV_(TURBO/LDPC)_ENC_SCATTER_GATHER and
233 * - RTE_BBDEV_(TURBO/LDPC)_DEC_SCATTER_GATHER.
234 * Only if a BBDEV PMD supports this feature, chained mbuf data
235 * structures are accepted. A chained mbuf can represent one
236 * non-contiguous CB or multiple non-contiguous CBs.
237 * If BBDEV PMD does not support this feature, it will assume inbound
238 * mbuf data contains one segment.
239 *
240 * The output mbuf data though is always one segment, even if the input
241 * was a chained mbuf.
242 */
243 struct rte_mbuf *data;
244 /** The starting point of the BBDEV (encode/decode) operation,
245 * in bytes.
246 *
247 * BBDEV starts to read data past this offset.
248 * In case of chained mbuf, this offset applies only to the first mbuf
249 * segment.
250 */
251 uint32_t offset;
252 /** The total data length to be processed in one operation, in bytes.
253 *
254 * In case the mbuf data is representing one CB, this is the length of
255 * the CB undergoing the operation.
256 * If it's for multiple CBs, this is the total length of those CBs
257 * undergoing the operation.
258 * If it is for one TB, this is the total length of the TB under
259 * operation.
260 *
261 * In case of chained mbuf, this data length includes the lengths of the
262 * "scattered" data segments undergoing the operation.
263 */
264 uint32_t length;
265 };
266
267 /** Turbo decode code block parameters */
268 struct rte_bbdev_op_dec_turbo_cb_params {
269 /** The K size of the input CB, in bits [40:6144], as specified in
270 * 3GPP TS 36.212.
271 * This size is inclusive of CRC bits, regardless whether it was
272 * pre-calculated by the application or not.
273 */
274 uint16_t k;
275 /** The E length of the CB rate matched LLR output, in bytes, as in
276 * 3GPP TS 36.212.
277 */
278 uint32_t e;
279 };
280
281 /** LDPC decode code block parameters */
282 struct rte_bbdev_op_dec_ldpc_cb_params {
283 /** Rate matching output sequence length in bits or LLRs.
284 * [3GPP TS38.212, section 5.4.2.1]
285 */
286 uint32_t e;
287 };
288
289 /** Turbo decode transport block parameters */
290 struct rte_bbdev_op_dec_turbo_tb_params {
291 /** The K- size of the input CB, in bits [40:6144], that is in the
292 * Turbo operation when r < C-, as in 3GPP TS 36.212.
293 */
294 uint16_t k_neg;
295 /** The K+ size of the input CB, in bits [40:6144], that is in the
296 * Turbo operation when r >= C-, as in 3GPP TS 36.212.
297 */
298 uint16_t k_pos;
299 /** The number of CBs that have K- size, [0:63] */
300 uint8_t c_neg;
301 /** The total number of CBs in the TB,
302 * [1:RTE_BBDEV_TURBO_MAX_CODE_BLOCKS]
303 */
304 uint8_t c;
305 /** The number of CBs that uses Ea before switching to Eb, [0:63] */
306 uint8_t cab;
307 /** The E size of the CB rate matched output to use in the Turbo
308 * operation when r < cab
309 */
310 uint32_t ea;
311 /** The E size of the CB rate matched output to use in the Turbo
312 * operation when r >= cab
313 */
314 uint32_t eb;
315 /** The index of the first CB in the inbound mbuf data, default is 0 */
316 uint8_t r;
317 };
318
319 /** LDPC decode transport block parameters */
320 struct rte_bbdev_op_dec_ldpc_tb_params {
321 /** Ea, length after rate matching in bits, r < cab.
322 * [3GPP TS38.212, section 5.4.2.1]
323 */
324 uint32_t ea;
325 /** Eb, length after rate matching in bits, r >= cab.
326 * [3GPP TS38.212, section 5.4.2.1]
327 */
328 uint32_t eb;
329 /** The total number of CBs in the TB or partial TB
330 * [1:RTE_BBDEV_LDPC_MAX_CODE_BLOCKS]
331 */
332 uint8_t c;
333 /** The index of the first CB in the inbound mbuf data, default is 0 */
334 uint8_t r;
335 /** The number of CBs that use Ea before switching to Eb, [0:63] */
336 uint8_t cab;
337 };
338
339 /** Operation structure for Turbo decode.
340 * An operation can be performed on one CB at a time "CB-mode".
341 * An operation can be performed on one or multiple CBs that logically
342 * belong to one TB "TB-mode".
343 * The provided K size parameter of the CB is its size coming from the
344 * decode operation.
345 * CRC24A/B check is requested by the application by setting the flag
346 * RTE_BBDEV_TURBO_CRC_TYPE_24B for CRC24B check or CRC24A otherwise.
347 * In TB-mode, BBDEV concatenates the decoded CBs one next to the other with
348 * relevant CRC24B in between.
349 *
350 * The input encoded CB data is the Virtual Circular Buffer data stream, wk,
351 * with the null padding included as described in 3GPP TS 36.212
352 * section 5.1.4.1.2 and shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1.
353 * The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte
354 * aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1.
355 *
356 * Each byte in the input circular buffer is the LLR value of each bit of the
357 * original CB.
358 *
359 * Hard output is a mandatory capability that all BBDEV PMDs support. This is
360 * the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB).
361 * Soft output is an optional capability for BBDEV PMDs. If supported, an LLR
362 * rate matched output is computed in the soft_output buffer structure.
363 *
364 * The output mbuf data structure is expected to be allocated by the
365 * application with enough room for the output data.
366 */
367 struct rte_bbdev_op_turbo_dec {
368 /** The Virtual Circular Buffer, wk, size 3*Kpi for each CB */
369 struct rte_bbdev_op_data input;
370 /** The hard decisions buffer for the decoded output,
371 * size K for each CB
372 */
373 struct rte_bbdev_op_data hard_output;
374 /** The soft LLR output buffer - optional */
375 struct rte_bbdev_op_data soft_output;
376
377 /** Flags from rte_bbdev_op_td_flag_bitmasks */
378 uint32_t op_flags;
379
380 /** Rv index for rate matching [0:3] */
381 uint8_t rv_index;
382 /** The minimum number of iterations to perform in decoding all CBs in
383 * this operation - input
384 */
385 uint8_t iter_min:4;
386 /** The maximum number of iterations to perform in decoding all CBs in
387 * this operation - input
388 */
389 uint8_t iter_max:4;
390 /** The maximum number of iterations that were performed in decoding
391 * all CBs in this decode operation - output
392 */
393 uint8_t iter_count;
394 /** 5 bit extrinsic scale (scale factor on extrinsic info) */
395 uint8_t ext_scale;
396 /** Number of MAP engines to use in decode,
397 * must be power of 2 (or 0 to auto-select)
398 */
399 uint8_t num_maps;
400
401 /** [0 - TB : 1 - CB] */
402 uint8_t code_block_mode;
403 union {
404 /** Struct which stores Code Block specific parameters */
405 struct rte_bbdev_op_dec_turbo_cb_params cb_params;
406 /** Struct which stores Transport Block specific parameters */
407 struct rte_bbdev_op_dec_turbo_tb_params tb_params;
408 };
409 };
410
411 /** Operation structure for LDPC decode.
412 *
413 * An operation can be performed on one CB at a time "CB-mode".
414 * An operation can also be performed on one or multiple CBs that logically
415 * belong to a TB "TB-mode" (Currently not supported).
416 *
417 * The input encoded CB data is the Virtual Circular Buffer data stream.
418 *
419 * Each byte in the input circular buffer is the LLR value of each bit of the
420 * original CB.
421 *
422 * Hard output is a mandatory capability that all BBDEV PMDs support. This is
423 * the decoded CBs (CRC24A/B is the last 24-bit in each decoded CB).
424 *
425 * Soft output is an optional capability for BBDEV PMDs. If supported, an LLR
426 * rate matched output is computed in the soft_output buffer structure.
427 * These are A Posteriori Probabilities (APP) LLR samples for coded bits.
428 *
429 * HARQ combined output is an optional capability for BBDEV PMDs.
430 * If supported, a LLR output is streamed to the harq_combined_output
431 * buffer.
432 *
433 * HARQ combined input is an optional capability for BBDEV PMDs.
434 * If supported, a LLR input is streamed from the harq_combined_input
435 * buffer.
436 *
437 * The output mbuf data structure is expected to be allocated by the
438 * application with enough room for the output data.
439 */
440 struct rte_bbdev_op_ldpc_dec {
441 /** The Virtual Circular Buffer for this code block, one LLR
442 * per bit of the original CB.
443 */
444 struct rte_bbdev_op_data input;
445 /** The hard decisions buffer for the decoded output,
446 * size K for each CB
447 */
448 struct rte_bbdev_op_data hard_output;
449 /** The soft LLR output LLR stream buffer - optional */
450 struct rte_bbdev_op_data soft_output;
451 /** The HARQ combined LLR stream input buffer - optional */
452 struct rte_bbdev_op_data harq_combined_input;
453 /** The HARQ combined LLR stream output buffer - optional */
454 struct rte_bbdev_op_data harq_combined_output;
455
456 /** Flags from rte_bbdev_op_ldpcdec_flag_bitmasks */
457 uint32_t op_flags;
458
459 /** Rate matching redundancy version
460 * [3GPP TS38.212, section 5.4.2.1]
461 */
462 uint8_t rv_index;
463 /** The maximum number of iterations to perform in decoding CB in
464 * this operation - input
465 */
466 uint8_t iter_max;
467 /** The number of iterations that were performed in decoding
468 * CB in this decode operation - output
469 */
470 uint8_t iter_count;
471 /** 1: LDPC Base graph 1, 2: LDPC Base graph 2.
472 * [3GPP TS38.212, section 5.2.2]
473 */
474 uint8_t basegraph;
475 /** Zc, LDPC lifting size.
476 * [3GPP TS38.212, section 5.2.2]
477 */
478 uint16_t z_c;
479 /** Ncb, length of the circular buffer in bits.
480 * [3GPP TS38.212, section 5.4.2.1]
481 */
482 uint16_t n_cb;
483 /** Qm, modulation order {1,2,4,6,8}.
484 * [3GPP TS38.212, section 5.4.2.2]
485 */
486 uint8_t q_m;
487 /** Number of Filler bits, n_filler = K – K’
488 * [3GPP TS38.212 section 5.2.2]
489 */
490 uint16_t n_filler;
491 /** [0 - TB : 1 - CB] */
492 uint8_t code_block_mode;
493 union {
494 /** Struct which stores Code Block specific parameters */
495 struct rte_bbdev_op_dec_ldpc_cb_params cb_params;
496 /** Struct which stores Transport Block specific parameters */
497 struct rte_bbdev_op_dec_ldpc_tb_params tb_params;
498 };
499 };
500
501 /** Turbo encode code block parameters */
502 struct rte_bbdev_op_enc_turbo_cb_params {
503 /** The K size of the input CB, in bits [40:6144], as specified in
504 * 3GPP TS 36.212.
505 * This size is inclusive of CRC24A, regardless whether it was
506 * pre-calculated by the application or not.
507 */
508 uint16_t k;
509 /** The E length of the CB rate matched output, in bits, as in
510 * 3GPP TS 36.212.
511 */
512 uint32_t e;
513 /** The Ncb soft buffer size of the CB rate matched output [K:3*Kpi],
514 * in bits, as specified in 3GPP TS 36.212.
515 */
516 uint16_t ncb;
517 };
518
519 /** Turbo encode transport block parameters */
520 struct rte_bbdev_op_enc_turbo_tb_params {
521 /** The K- size of the input CB, in bits [40:6144], that is in the
522 * Turbo operation when r < C-, as in 3GPP TS 36.212.
523 * This size is inclusive of CRC24B, regardless whether it was
524 * pre-calculated and appended by the application or not.
525 */
526 uint16_t k_neg;
527 /** The K+ size of the input CB, in bits [40:6144], that is in the
528 * Turbo operation when r >= C-, as in 3GPP TS 36.212.
529 * This size is inclusive of CRC24B, regardless whether it was
530 * pre-calculated and appended by the application or not.
531 */
532 uint16_t k_pos;
533 /** The number of CBs that have K- size, [0:63] */
534 uint8_t c_neg;
535 /** The total number of CBs in the TB,
536 * [1:RTE_BBDEV_TURBO_MAX_CODE_BLOCKS]
537 */
538 uint8_t c;
539 /** The number of CBs that uses Ea before switching to Eb, [0:63] */
540 uint8_t cab;
541 /** The E size of the CB rate matched output to use in the Turbo
542 * operation when r < cab
543 */
544 uint32_t ea;
545 /** The E size of the CB rate matched output to use in the Turbo
546 * operation when r >= cab
547 */
548 uint32_t eb;
549 /** The Ncb soft buffer size for the rate matched CB that is used in
550 * the Turbo operation when r < C-, [K:3*Kpi]
551 */
552 uint16_t ncb_neg;
553 /** The Ncb soft buffer size for the rate matched CB that is used in
554 * the Turbo operation when r >= C-, [K:3*Kpi]
555 */
556 uint16_t ncb_pos;
557 /** The index of the first CB in the inbound mbuf data, default is 0 */
558 uint8_t r;
559 };
560
561 /** LDPC encode code block parameters */
562 struct rte_bbdev_op_enc_ldpc_cb_params {
563 /** E, length after rate matching in bits.
564 * [3GPP TS38.212, section 5.4.2.1]
565 */
566 uint32_t e;
567 };
568
569 /** LDPC encode transport block parameters */
570 struct rte_bbdev_op_enc_ldpc_tb_params {
571 /** Ea, length after rate matching in bits, r < cab.
572 * [3GPP TS38.212, section 5.4.2.1]
573 */
574 uint32_t ea;
575 /** Eb, length after rate matching in bits, r >= cab.
576 * [3GPP TS38.212, section 5.4.2.1]
577 */
578 uint32_t eb;
579 /** The total number of CBs in the TB or partial TB
580 * [1:RTE_BBDEV_LDPC_MAX_CODE_BLOCKS]
581 */
582 uint8_t c;
583 /** The index of the first CB in the inbound mbuf data, default is 0 */
584 uint8_t r;
585 /** The number of CBs that use Ea before switching to Eb, [0:63] */
586 uint8_t cab;
587 };
588
589 /** Operation structure for Turbo encode.
590 * An operation can be performed on one CB at a time "CB-mode".
591 * An operation can pbe erformd on one or multiple CBs that logically
592 * belong to one TB "TB-mode".
593 *
594 * In CB-mode, CRC24A/B is an optional operation. K size parameter is not
595 * affected by CRC24A/B inclusion, this only affects the inbound mbuf data
596 * length. Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags
597 * RTE_BBDEV_TURBO_CRC_24A_ATTACH and RTE_BBDEV_TURBO_CRC_24B_ATTACH informs
598 * the application with relevant capability. These flags can be set in the
599 * op_flags parameter to indicate BBDEV to calculate and append CRC24A to CB
600 * before going forward with Turbo encoding.
601 *
602 * In TB-mode, CRC24A is assumed to be pre-calculated and appended to the
603 * inbound TB mbuf data buffer.
604 *
605 * The output mbuf data structure is expected to be allocated by the
606 * application with enough room for the output data.
607 */
608 struct rte_bbdev_op_turbo_enc {
609 /** The input CB or TB data */
610 struct rte_bbdev_op_data input;
611 /** The rate matched CB or TB output buffer */
612 struct rte_bbdev_op_data output;
613 /** Flags from rte_bbdev_op_te_flag_bitmasks */
614 uint32_t op_flags;
615
616 /** Rv index for rate matching [0:3] */
617 uint8_t rv_index;
618 /** [0 - TB : 1 - CB] */
619 uint8_t code_block_mode;
620 union {
621 /** Struct which stores Code Block specific parameters */
622 struct rte_bbdev_op_enc_turbo_cb_params cb_params;
623 /** Struct which stores Transport Block specific parameters */
624 struct rte_bbdev_op_enc_turbo_tb_params tb_params;
625 };
626 };
627
628 /** Operation structure for LDPC encode.
629 * An operation can be performed on one CB at a time "CB-mode".
630 * An operation can be performed on one or multiple CBs that logically
631 * belong to a TB "TB-mode".
632 *
633 * The input data is the CB or TB input to the decoder.
634 *
635 * The output data is the ratematched CB or TB data, or the output after
636 * bit-selection if RTE_BBDEV_LDPC_INTERLEAVER_BYPASS is set.
637 *
638 * The output mbuf data structure is expected to be allocated by the
639 * application with enough room for the output data.
640 */
641 struct rte_bbdev_op_ldpc_enc {
642 /** The input TB or CB data */
643 struct rte_bbdev_op_data input;
644 /** The rate matched TB or CB output buffer */
645 struct rte_bbdev_op_data output;
646
647 /** Flags from rte_bbdev_op_ldpcenc_flag_bitmasks */
648 uint32_t op_flags;
649
650 /** Rate matching redundancy version */
651 uint8_t rv_index;
652 /** 1: LDPC Base graph 1, 2: LDPC Base graph 2.
653 * [3GPP TS38.212, section 5.2.2]
654 */
655 uint8_t basegraph;
656 /** Zc, LDPC lifting size.
657 * [3GPP TS38.212, section 5.2.2]
658 */
659 uint16_t z_c;
660 /** Ncb, length of the circular buffer in bits.
661 * [3GPP TS38.212, section 5.4.2.1]
662 */
663 uint16_t n_cb;
664 /** Qm, modulation order {2,4,6,8,10}.
665 * [3GPP TS38.212, section 5.4.2.2]
666 */
667 uint8_t q_m;
668 /** Number of Filler bits, n_filler = K – K’
669 * [3GPP TS38.212 section 5.2.2]
670 */
671 uint16_t n_filler;
672 /** [0 - TB : 1 - CB] */
673 uint8_t code_block_mode;
674 union {
675 /** Struct which stores Code Block specific parameters */
676 struct rte_bbdev_op_enc_ldpc_cb_params cb_params;
677 /** Struct which stores Transport Block specific parameters */
678 struct rte_bbdev_op_enc_ldpc_tb_params tb_params;
679 };
680 };
681
682 /** List of the capabilities for the Turbo Decoder */
683 struct rte_bbdev_op_cap_turbo_dec {
684 /** Flags from rte_bbdev_op_td_flag_bitmasks */
685 uint32_t capability_flags;
686 /** Maximal LLR absolute value. Acceptable LLR values lie in range
687 * [-max_llr_modulus, max_llr_modulus].
688 */
689 int8_t max_llr_modulus;
690 /** Num input code block buffers */
691 uint8_t num_buffers_src; /**< Num input code block buffers */
692 /** Num hard output code block buffers */
693 uint8_t num_buffers_hard_out;
694 /** Num soft output code block buffers if supported by the driver */
695 uint8_t num_buffers_soft_out;
696 };
697
698 /** List of the capabilities for the Turbo Encoder */
699 struct rte_bbdev_op_cap_turbo_enc {
700 /** Flags from rte_bbdev_op_te_flag_bitmasks */
701 uint32_t capability_flags;
702 /** Num input code block buffers */
703 uint8_t num_buffers_src;
704 /** Num output code block buffers */
705 uint8_t num_buffers_dst;
706 };
707
708 /** List of the capabilities for the LDPC Decoder */
709 struct rte_bbdev_op_cap_ldpc_dec {
710 /** Flags from rte_bbdev_op_ldpcdec_flag_bitmasks */
711 uint32_t capability_flags;
712 /** LLR size in bits. LLR is a two’s complement number. */
713 int8_t llr_size;
714 /** LLR numbers of decimals bit for arithmetic representation */
715 int8_t llr_decimals;
716 /** Num input code block buffers */
717 uint16_t num_buffers_src;
718 /** Num hard output code block buffers */
719 uint16_t num_buffers_hard_out;
720 /** Num soft output code block buffers if supported by the driver */
721 uint16_t num_buffers_soft_out;
722 };
723
724 /** List of the capabilities for the LDPC Encoder */
725 struct rte_bbdev_op_cap_ldpc_enc {
726 /** Flags from rte_bbdev_op_ldpcenc_flag_bitmasks */
727 uint32_t capability_flags;
728 /** Num input code block buffers */
729 uint16_t num_buffers_src;
730 /** Num output code block buffers */
731 uint16_t num_buffers_dst;
732 };
733
734 /** Different operation types supported by the device */
735 enum rte_bbdev_op_type {
736 RTE_BBDEV_OP_NONE, /**< Dummy operation that does nothing */
737 RTE_BBDEV_OP_TURBO_DEC, /**< Turbo decode */
738 RTE_BBDEV_OP_TURBO_ENC, /**< Turbo encode */
739 RTE_BBDEV_OP_LDPC_DEC, /**< LDPC decode */
740 RTE_BBDEV_OP_LDPC_ENC, /**< LDPC encode */
741 RTE_BBDEV_OP_TYPE_COUNT, /**< Count of different op types */
742 };
743
744 /** Bit indexes of possible errors reported through status field */
745 enum {
746 RTE_BBDEV_DRV_ERROR,
747 RTE_BBDEV_DATA_ERROR,
748 RTE_BBDEV_CRC_ERROR,
749 RTE_BBDEV_SYNDROME_ERROR
750 };
751
752 /** Structure specifying a single encode operation */
753 struct rte_bbdev_enc_op {
754 /** Status of operation that was performed */
755 int status;
756 /** Mempool which op instance is in */
757 struct rte_mempool *mempool;
758 /** Opaque pointer for user data */
759 void *opaque_data;
760 union {
761 /** Contains turbo decoder specific parameters */
762 struct rte_bbdev_op_turbo_enc turbo_enc;
763 /** Contains LDPC decoder specific parameters */
764 struct rte_bbdev_op_ldpc_enc ldpc_enc;
765 };
766 };
767
768 /** Structure specifying a single decode operation */
769 struct rte_bbdev_dec_op {
770 /** Status of operation that was performed */
771 int status;
772 /** Mempool which op instance is in */
773 struct rte_mempool *mempool;
774 /** Opaque pointer for user data */
775 void *opaque_data;
776 union {
777 /** Contains turbo decoder specific parameters */
778 struct rte_bbdev_op_turbo_dec turbo_dec;
779 /** Contains LDPC decoder specific parameters */
780 struct rte_bbdev_op_ldpc_dec ldpc_dec;
781 };
782 };
783
784 /** Operation capabilities supported by a device */
785 struct rte_bbdev_op_cap {
786 enum rte_bbdev_op_type type; /**< Type of operation */
787 union {
788 struct rte_bbdev_op_cap_turbo_dec turbo_dec;
789 struct rte_bbdev_op_cap_turbo_enc turbo_enc;
790 struct rte_bbdev_op_cap_ldpc_dec ldpc_dec;
791 struct rte_bbdev_op_cap_ldpc_enc ldpc_enc;
792 } cap; /**< Operation-type specific capabilities */
793 };
794
795 /** @internal Private data structure stored with operation pool. */
796 struct rte_bbdev_op_pool_private {
797 enum rte_bbdev_op_type type; /**< Type of operations in a pool */
798 };
799
800 /**
801 * Converts queue operation type from enum to string
802 *
803 * @param op_type
804 * Operation type as enum
805 *
806 * @returns
807 * Operation type as string or NULL if op_type is invalid
808 *
809 */
810 __rte_experimental
811 const char*
812 rte_bbdev_op_type_str(enum rte_bbdev_op_type op_type);
813
814 /**
815 * Creates a bbdev operation mempool
816 *
817 * @param name
818 * Pool name.
819 * @param type
820 * Operation type, use RTE_BBDEV_OP_NONE for a pool which supports all
821 * operation types.
822 * @param num_elements
823 * Number of elements in the pool.
824 * @param cache_size
825 * Number of elements to cache on an lcore, see rte_mempool_create() for
826 * further details about cache size.
827 * @param socket_id
828 * Socket to allocate memory on.
829 *
830 * @return
831 * - Pointer to a mempool on success,
832 * - NULL pointer on failure.
833 */
834 __rte_experimental
835 struct rte_mempool *
836 rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
837 unsigned int num_elements, unsigned int cache_size,
838 int socket_id);
839
840 /**
841 * Bulk allocate encode operations from a mempool with parameter defaults reset.
842 *
843 * @param mempool
844 * Operation mempool, created by rte_bbdev_op_pool_create().
845 * @param ops
846 * Output array to place allocated operations
847 * @param num_ops
848 * Number of operations to allocate
849 *
850 * @returns
851 * - 0 on success
852 * - EINVAL if invalid mempool is provided
853 */
854 __rte_experimental
855 static inline int
rte_bbdev_enc_op_alloc_bulk(struct rte_mempool * mempool,struct rte_bbdev_enc_op ** ops,uint16_t num_ops)856 rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
857 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
858 {
859 struct rte_bbdev_op_pool_private *priv;
860 int ret;
861
862 /* Check type */
863 priv = (struct rte_bbdev_op_pool_private *)
864 rte_mempool_get_priv(mempool);
865 if (unlikely((priv->type != RTE_BBDEV_OP_TURBO_ENC) &&
866 (priv->type != RTE_BBDEV_OP_LDPC_ENC)))
867 return -EINVAL;
868
869 /* Get elements */
870 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
871 if (unlikely(ret < 0))
872 return ret;
873
874 return 0;
875 }
876
877 /**
878 * Bulk allocate decode operations from a mempool with parameter defaults reset.
879 *
880 * @param mempool
881 * Operation mempool, created by rte_bbdev_op_pool_create().
882 * @param ops
883 * Output array to place allocated operations
884 * @param num_ops
885 * Number of operations to allocate
886 *
887 * @returns
888 * - 0 on success
889 * - EINVAL if invalid mempool is provided
890 */
891 __rte_experimental
892 static inline int
rte_bbdev_dec_op_alloc_bulk(struct rte_mempool * mempool,struct rte_bbdev_dec_op ** ops,uint16_t num_ops)893 rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
894 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
895 {
896 struct rte_bbdev_op_pool_private *priv;
897 int ret;
898
899 /* Check type */
900 priv = (struct rte_bbdev_op_pool_private *)
901 rte_mempool_get_priv(mempool);
902 if (unlikely((priv->type != RTE_BBDEV_OP_TURBO_DEC) &&
903 (priv->type != RTE_BBDEV_OP_LDPC_DEC)))
904 return -EINVAL;
905
906 /* Get elements */
907 ret = rte_mempool_get_bulk(mempool, (void **)ops, num_ops);
908 if (unlikely(ret < 0))
909 return ret;
910
911 return 0;
912 }
913
914 /**
915 * Free decode operation structures that were allocated by
916 * rte_bbdev_dec_op_alloc_bulk().
917 * All structures must belong to the same mempool.
918 *
919 * @param ops
920 * Operation structures
921 * @param num_ops
922 * Number of structures
923 */
924 __rte_experimental
925 static inline void
rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op ** ops,unsigned int num_ops)926 rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, unsigned int num_ops)
927 {
928 if (num_ops > 0)
929 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
930 }
931
932 /**
933 * Free encode operation structures that were allocated by
934 * rte_bbdev_enc_op_alloc_bulk().
935 * All structures must belong to the same mempool.
936 *
937 * @param ops
938 * Operation structures
939 * @param num_ops
940 * Number of structures
941 */
942 __rte_experimental
943 static inline void
rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op ** ops,unsigned int num_ops)944 rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, unsigned int num_ops)
945 {
946 if (num_ops > 0)
947 rte_mempool_put_bulk(ops[0]->mempool, (void **)ops, num_ops);
948 }
949
950 #ifdef __cplusplus
951 }
952 #endif
953
954 #endif /* _RTE_BBDEV_OP_H_ */
955