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