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