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