ceph/src/spdk/dpdk/doc/guides/prog_guide/bbdev.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation
   3
   4 Wireless Baseband Device Library
   5 ================================
   6
   7 The Wireless Baseband library provides a common programming framework that
   8 abstracts HW accelerators based on FPGA and/or Fixed Function Accelerators that
   9 assist with 3GPP Physical Layer processing. Furthermore, it decouples the
  10 application from the compute-intensive wireless functions by abstracting their
  11 optimized libraries to appear as virtual bbdev devices.
  12
  13 The functional scope of the BBDEV library are those functions in relation to
  14 the 3GPP Layer 1 signal processing (channel coding, modulation, ...).
  15
  16 The framework currently only supports Turbo Code FEC function.
  17
  18
  19 Design Principles
  20 -----------------
  21
  22 The Wireless Baseband library follows the same ideology of DPDK's Ethernet
  23 Device and Crypto Device frameworks. Wireless Baseband provides a generic
  24 acceleration abstraction framework which supports both physical (hardware) and
  25 virtual (software) wireless acceleration functions.
  26
  27 Device Management
  28 -----------------
  29
  30 Device Creation
  31 ~~~~~~~~~~~~~~~
  32
  33 Physical bbdev devices are discovered during the PCI probe/enumeration of the
  34 EAL function which is executed at DPDK initialization, based on
  35 their PCI device identifier, each unique PCI BDF (bus/bridge, device,
  36 function).
  37
  38 Virtual devices can be created by two mechanisms, either using the EAL command
  39 line options or from within the application using an EAL API directly.
  40
  41 From the command line using the --vdev EAL option
  42
  43 .. code-block:: console
  44
  45    --vdev 'baseband_turbo_sw,max_nb_queues=8,socket_id=0'
  46
  47 Or using the rte_vdev_init API within the application code.
  48
  49 .. code-block:: c
  50
  51     rte_vdev_init("baseband_turbo_sw", "max_nb_queues=2,socket_id=0")
  52
  53 All virtual bbdev devices support the following initialization parameters:
  54
  55 - ``max_nb_queues`` - maximum number of queues supported by the device.
  56
  57 - ``socket_id`` - socket on which to allocate the device resources on.
  58
  59
  60 Device Identification
  61 ~~~~~~~~~~~~~~~~~~~~~
  62
  63 Each device, whether virtual or physical is uniquely designated by two
  64 identifiers:
  65
  66 - A unique device index used to designate the bbdev device in all functions
  67   exported by the bbdev API.
  68
  69 - A device name used to designate the bbdev device in console messages, for
  70   administration or debugging purposes. For ease of use, the port name includes
  71   the port index.
  72
  73
  74 Device Configuration
  75 ~~~~~~~~~~~~~~~~~~~~
  76
  77 From the application point of view, each instance of a bbdev device consists of
  78 one or more queues identified by queue IDs. While different devices may have
  79 different capabilities (e.g. support different operation types), all queues on
  80 a device support identical configuration possibilities. A queue is configured
  81 for only one type of operation and is configured at initialization time.
  82 When an operation is enqueued to a specific queue ID, the result is dequeued
  83 from the same queue ID.
  84
  85 Configuration of a device has two different levels: configuration that applies
  86 to the whole device, and configuration that applies to a single queue.
  87
  88 Device configuration is applied with
  89 ``rte_bbdev_setup_queues(dev_id,num_queues,socket_id)``
  90 and queue configuration is applied with
  91 ``rte_bbdev_queue_configure(dev_id,queue_id,conf)``. Note that, although all
  92 queues on a device support same capabilities, they can be configured differently
  93 and will then behave differently.
  94 Devices supporting interrupts can enable them by using
  95 ``rte_bbdev_intr_enable(dev_id)``.
  96
  97 The configuration of each bbdev device includes the following operations:
  98
  99 - Allocation of resources, including hardware resources if a physical device.
 100 - Resetting the device into a well-known default state.
 101 - Initialization of statistics counters.
 102
 103 The ``rte_bbdev_setup_queues`` API is used to setup queues for a bbdev device.
 104
 105 .. code-block:: c
 106
 107    int rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues,
 108             int socket_id);
 109
 110 - ``num_queues`` argument identifies the total number of queues to setup for
 111   this device.
 112
 113 - ``socket_id`` specifies which socket will be used to allocate the memory.
 114
 115
 116 The ``rte_bbdev_intr_enable`` API is used to enable interrupts for a bbdev
 117 device, if supported by the driver. Should be called before starting the device.
 118
 119 .. code-block:: c
 120
 121    int rte_bbdev_intr_enable(uint16_t dev_id);
 122
 123
 124 Queues Configuration
 125 ~~~~~~~~~~~~~~~~~~~~
 126
 127 Each bbdev devices queue is individually configured through the
 128 ``rte_bbdev_queue_configure()`` API.
 129 Each queue resources may be allocated on a specified socket.
 130
 131 .. code-block:: c
 132
 133     struct rte_bbdev_queue_conf {
 134         int socket;
 135         uint32_t queue_size;
 136         uint8_t priority;
 137         bool deferred_start;
 138         enum rte_bbdev_op_type op_type;
 139     };
 140
 141 Device & Queues Management
 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 143
 144 After initialization, devices are in a stopped state, so must be started by the
 145 application. If an application is finished using a device it can close the
 146 device. Once closed, it cannot be restarted.
 147
 148 .. code-block:: c
 149
 150     int rte_bbdev_start(uint16_t dev_id)
 151     int rte_bbdev_stop(uint16_t dev_id)
 152     int rte_bbdev_close(uint16_t dev_id)
 153     int rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id)
 154     int rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id)
 155
 156
 157 By default, all queues are started when the device is started, but they can be
 158 stopped individually.
 159
 160 .. code-block:: c
 161
 162     int rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id)
 163     int rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id)
 164
 165
 166 Logical Cores, Memory and Queues Relationships
 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168
 169 The bbdev poll mode device driver library supports NUMA architecture, in which
 170 a processor's logical cores and interfaces utilize it's local memory. Therefore
 171 with baseband operations, the mbuf being operated on should be allocated from memory
 172 pools created in the local memory. The buffers should, if possible, remain on
 173 the local processor to obtain the best performance results and buffer
 174 descriptors should be populated with mbufs allocated from a mempool allocated
 175 from local memory.
 176
 177 The run-to-completion model also performs better, especially in the case of
 178 virtual bbdev devices, if the baseband operation and data buffers are in local
 179 memory instead of a remote processor's memory. This is also true for the
 180 pipe-line model provided all logical cores used are located on the same processor.
 181
 182 Multiple logical cores should never share the same queue for enqueuing
 183 operations or dequeuing operations on the same bbdev device since this would
 184 require global locks and hinder performance. It is however possible to use a
 185 different logical core to dequeue an operation on a queue pair from the logical
 186 core which it was enqueued on. This means that a baseband burst enqueue/dequeue
 187 APIs are a logical place to transition from one logical core to another in a
 188 packet processing pipeline.
 189
 190
 191 Device Operation Capabilities
 192 -----------------------------
 193
 194 Capabilities (in terms of operations supported, max number of queues, etc.)
 195 identify what a bbdev is capable of performing that differs from one device to
 196 another. For the full scope of the bbdev capability see the definition of the
 197 structure in the *DPDK API Reference*.
 198
 199 .. code-block:: c
 200
 201    struct rte_bbdev_op_cap;
 202
 203 A device reports its capabilities when registering itself in the bbdev framework.
 204 With the aid of this capabilities mechanism, an application can query devices to
 205 discover which operations within the 3GPP physical layer they are capable of
 206 performing. Below is an example of the capabilities for a PMD it supports in
 207 relation to Turbo Encoding and Decoding operations.
 208
 209 .. code-block:: c
 210
 211     static const struct rte_bbdev_op_cap bbdev_capabilities[] = {
 212         {
 213             .type = RTE_BBDEV_OP_TURBO_DEC,
 214             .cap.turbo_dec = {
 215                 .capability_flags =
 216                     RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE |
 217                     RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN |
 218                     RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN |
 219                     RTE_BBDEV_TURBO_CRC_TYPE_24B |
 220                     RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP |
 221                     RTE_BBDEV_TURBO_EARLY_TERMINATION,
 222                 .max_llr_modulus = 16,
 223                 .num_buffers_src = RTE_BBDEV_TURBO_MAX_CODE_BLOCKS,
 224                 .num_buffers_hard_out =
 225                         RTE_BBDEV_TURBO_MAX_CODE_BLOCKS,
 226                 .num_buffers_soft_out = 0,
 227             }
 228         },
 229         {
 230             .type   = RTE_BBDEV_OP_TURBO_ENC,
 231             .cap.turbo_enc = {
 232                 .capability_flags =
 233                         RTE_BBDEV_TURBO_CRC_24B_ATTACH |
 234                         RTE_BBDEV_TURBO_CRC_24A_ATTACH |
 235                         RTE_BBDEV_TURBO_RATE_MATCH |
 236                         RTE_BBDEV_TURBO_RV_INDEX_BYPASS,
 237                 .num_buffers_src = RTE_BBDEV_TURBO_MAX_CODE_BLOCKS,
 238                 .num_buffers_dst = RTE_BBDEV_TURBO_MAX_CODE_BLOCKS,
 239             }
 240         },
 241         RTE_BBDEV_END_OF_CAPABILITIES_LIST()
 242     };
 243
 244 Capabilities Discovery
 245 ~~~~~~~~~~~~~~~~~~~~~~
 246
 247 Discovering the features and capabilities of a bbdev device poll mode driver
 248 is achieved through the ``rte_bbdev_info_get()`` function.
 249
 250 .. code-block:: c
 251
 252    int rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info)
 253
 254 This allows the user to query a specific bbdev PMD and get all the device
 255 capabilities. The ``rte_bbdev_info`` structure provides two levels of
 256 information:
 257
 258 - Device relevant information, like: name and related rte_bus.
 259
 260 - Driver specific information, as defined by the ``struct rte_bbdev_driver_info``
 261   structure, this is where capabilities reside along with other specifics like:
 262   maximum queue sizes and priority level.
 263
 264 .. code-block:: c
 265
 266     struct rte_bbdev_info {
 267         int socket_id;
 268         const char *dev_name;
 269         const struct rte_device *device;
 270         uint16_t num_queues;
 271         bool started;
 272         struct rte_bbdev_driver_info drv;
 273     };
 274
 275
 276 Operation Processing
 277 --------------------
 278
 279 Scheduling of baseband operations on DPDK's application data path is
 280 performed using a burst oriented asynchronous API set. A queue on a bbdev
 281 device accepts a burst of baseband operations using enqueue burst API. On physical
 282 bbdev devices the enqueue burst API will place the operations to be processed
 283 on the device's hardware input queue, for virtual devices the processing of the
 284 baseband operations is usually completed during the enqueue call to the bbdev
 285 device. The dequeue burst API will retrieve any processed operations available
 286 from the queue on the bbdev device, from physical devices this is usually
 287 directly from the device's processed queue, and for virtual device's from a
 288 ``rte_ring`` where processed operations are placed after being processed on the
 289 enqueue call.
 290
 291
 292 Enqueue / Dequeue Burst APIs
 293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 294
 295 The burst enqueue API uses a bbdev device identifier and a queue
 296 identifier to specify the bbdev device queue to schedule the processing on.
 297 The ``num_ops`` parameter is the number of operations to process which are
 298 supplied in the ``ops`` array of ``rte_bbdev_*_op`` structures.
 299 The enqueue function returns the number of operations it actually enqueued for
 300 processing, a return value equal to ``num_ops`` means that all packets have been
 301 enqueued.
 302
 303 .. code-block:: c
 304
 305     uint16_t rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
 306             struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 307
 308     uint16_t rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
 309             struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 310
 311 The dequeue API uses the same format as the enqueue API of processed but
 312 the ``num_ops`` and ``ops`` parameters are now used to specify the max processed
 313 operations the user wishes to retrieve and the location in which to store them.
 314 The API call returns the actual number of processed operations returned, this
 315 can never be larger than ``num_ops``.
 316
 317 .. code-block:: c
 318
 319     uint16_t rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
 320             struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 321
 322     uint16_t rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
 323             struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 324
 325 Operation Representation
 326 ~~~~~~~~~~~~~~~~~~~~~~~~
 327
 328 An encode bbdev operation is represented by ``rte_bbdev_enc_op`` structure,
 329 and by ``rte_bbdev_dec_op`` for decode. These structures act as metadata
 330 containers for all necessary information required for the bbdev operation to be
 331 processed on a particular bbdev device poll mode driver.
 332
 333 .. code-block:: c
 334
 335     struct rte_bbdev_enc_op {
 336         int status;
 337         struct rte_mempool *mempool;
 338         void *opaque_data;
 339         union {
 340             struct rte_bbdev_op_turbo_enc turbo_enc;
 341             struct rte_bbdev_op_ldpc_enc ldpc_enc;
 342         }
 343     };
 344
 345     struct rte_bbdev_dec_op {
 346         int status;
 347         struct rte_mempool *mempool;
 348         void *opaque_data;
 349         union {
 350             struct rte_bbdev_op_turbo_dec turbo_enc;
 351             struct rte_bbdev_op_ldpc_dec ldpc_enc;
 352         }
 353     };
 354
 355 The operation structure by itself defines the operation type. It includes an
 356 operation status, a reference to the operation specific data, which can vary in
 357 size and content depending on the operation being provisioned. It also contains
 358 the source mempool for the operation, if it is allocated from a mempool.
 359
 360 If bbdev operations are allocated from a bbdev operation mempool, see next
 361 section, there is also the ability to allocate private memory with the
 362 operation for applications purposes.
 363
 364 Application software is responsible for specifying all the operation specific
 365 fields in the ``rte_bbdev_*_op`` structure which are then used by the bbdev PMD
 366 to process the requested operation.
 367
 368
 369 Operation Management and Allocation
 370 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 371
 372 The bbdev library provides an API set for managing bbdev operations which
 373 utilize the Mempool Library to allocate operation buffers. Therefore, it ensures
 374 that the bbdev operation is interleaved optimally across the channels and
 375 ranks for optimal processing.
 376
 377 .. code-block:: c
 378
 379     struct rte_mempool *
 380     rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
 381             unsigned int num_elements, unsigned int cache_size,
 382             int socket_id)
 383
 384 ``rte_bbdev_*_op_alloc_bulk()`` and ``rte_bbdev_*_op_free_bulk()`` are used to
 385 allocate bbdev operations of a specific type from a given bbdev operation mempool.
 386
 387 .. code-block:: c
 388
 389     int rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
 390             struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 391
 392     int rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
 393             struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 394
 395 ``rte_bbdev_*_op_free_bulk()`` is called by the application to return an
 396 operation to its allocating pool.
 397
 398 .. code-block:: c
 399
 400     void rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops,
 401             unsigned int num_ops)
 402     void rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops,
 403             unsigned int num_ops)
 404
 405 BBDEV Inbound/Outbound Memory
 406 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 407
 408 The bbdev operation structure contains all the mutable data relating to
 409 performing Turbo and LDPC coding on a referenced mbuf data buffer. It is used for either
 410 encode or decode operations.
 411
 412
 413 .. csv-table:: Operation I/O
 414    :header: "FEC", "In", "Out"
 415    :widths: 20, 30, 30
 416
 417    "Turbo Encode", "input", "output"
 418    "Turbo Decode", "input", "hard output"
 419    " ", " ", "soft output (optional)"
 420    "LDPC Encode", "input", "output"
 421    "LDPC Decode", "input", "hard output"
 422    "", "HQ combine (optional)", "HQ combine (optional)"
 423    " ", "", "soft output (optional)"
 424
 425
 426 It is expected that the application provides input and output mbuf pointers
 427 allocated and ready to use.
 428
 429 The baseband framework supports FEC coding on Code Blocks (CB) and
 430 Transport Blocks (TB).
 431
 432 For the output buffer(s), the application is required to provide an allocated
 433 and free mbuf, to which the resulting output will be written.
 434
 435 The support of split "scattered" buffers is a driver-specific feature, so it is
 436 reported individually by the supporting driver as a capability.
 437
 438 Input and output data buffers are identified by ``rte_bbdev_op_data`` structure,
 439 as follows:
 440
 441 .. code-block:: c
 442
 443     struct rte_bbdev_op_data {
 444         struct rte_mbuf *data;
 445         uint32_t offset;
 446         uint32_t length;
 447     };
 448
 449
 450 This structure has three elements:
 451
 452 - ``data``: This is the mbuf data structure representing the data for BBDEV
 453   operation.
 454
 455   This mbuf pointer can point to one Code Block (CB) data buffer or multiple CBs
 456   contiguously located next to each other. A Transport Block (TB) represents a
 457   whole piece of data that is divided into one or more CBs. Maximum number of
 458   CBs can be contained in one TB is defined by
 459   ``RTE_BBDEV_(TURBO/LDPC)MAX_CODE_BLOCKS``.
 460
 461   An mbuf data structure cannot represent more than one TB. The smallest piece
 462   of data that can be contained in one mbuf is one CB.
 463   An mbuf can include one contiguous CB, subset of contiguous CBs that are
 464   belonging to one TB, or all contiguous CBs that belong to one TB.
 465
 466   If a BBDEV PMD supports the extended capability "Scatter-Gather", then it is
 467   capable of collecting (gathering) non-contiguous (scattered) data from
 468   multiple locations in the memory.
 469   This capability is reported by the capability flags:
 470
 471   - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``, ``RTE_BBDEV_TURBO_DEC_SCATTER_GATHER``,
 472
 473   - ``RTE_BBDEV_LDPC_ENC_SCATTER_GATHER``, ``RTE_BBDEV_LDPC_DEC_SCATTER_GATHER``.
 474
 475   Chained mbuf data structures are only accepted if a BBDEV PMD supports this
 476   feature. A chained mbuf can represent one non-contiguous CB or multiple non-contiguous
 477   CBs. The first mbuf segment in the given chained mbuf represents the first piece
 478   of the CB. Offset is only applicable to the first segment. ``length`` is the
 479   total length of the CB.
 480
 481   BBDEV driver is responsible for identifying where the split is and enqueue
 482   the split data to its internal queues.
 483
 484   If BBDEV PMD does not support this feature, it will assume inbound mbuf data
 485   contains one segment.
 486
 487   The output mbuf data though is always one segment, even if the input was a
 488   chained mbuf.
 489
 490
 491 - ``offset``: This is the starting point of the BBDEV (encode/decode) operation,
 492   in bytes.
 493
 494   BBDEV starts to read data past this offset.
 495   In case of chained mbuf, this offset applies only to the first mbuf segment.
 496
 497
 498 - ``length``: This is the total data length to be processed in one operation,
 499   in bytes.
 500
 501   In case the mbuf data is representing one CB, this is the length of the CB
 502   undergoing the operation.
 503   If it is for multiple CBs, this is the total length of those CBs undergoing
 504   the operation.
 505   If it is for one TB, this is the total length of the TB under operation.
 506   In case of chained mbuf, this data length includes the lengths of the
 507   "scattered" data segments undergoing the operation.
 508
 509
 510 BBDEV Turbo Encode Operation
 511 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 512
 513 .. code-block:: c
 514
 515     struct rte_bbdev_op_turbo_enc {
 516         struct rte_bbdev_op_data input;
 517         struct rte_bbdev_op_data output;
 518
 519         uint32_t op_flags;
 520         uint8_t rv_index;
 521         uint8_t code_block_mode;
 522         union {
 523             struct rte_bbdev_op_enc_cb_params cb_params;
 524             struct rte_bbdev_op_enc_tb_params tb_params;
 525         };
 526     };
 527
 528 The Turbo encode structure includes the ``input`` and ``output`` mbuf
 529 data pointers. The provided mbuf pointer of ``input`` needs to be big
 530 enough to stretch for extra CRC trailers.
 531
 532 .. csv-table:: **struct rte_bbdev_op_turbo_enc** parameters
 533    :header: "Parameter", "Description"
 534    :widths: 10, 30
 535
 536    "input","input CB or TB data"
 537    "output","rate matched CB or TB output buffer"
 538    "op_flags","bitmask of all active operation capabilities"
 539    "rv_index","redundancy version index [0..3]"
 540    "code_block_mode","code block or transport block mode"
 541    "cb_params", "code block specific parameters (code block mode only)"
 542    "tb_params", "transport block specific parameters (transport block mode only)"
 543
 544
 545 The encode interface works on both the code block (CB) and the transport block
 546 (TB). An operation executes in "CB-mode" when the CB is standalone. While
 547 "TB-mode" executes when an operation performs on one or multiple CBs that
 548 belong to a TB. Therefore, a given data can be standalone CB, full-size TB or
 549 partial TB. Partial TB means that only a subset of CBs belonging to a bigger TB
 550 are being enqueued.
 551
 552   **NOTE:** It is assumed that all enqueued ops in one ``rte_bbdev_enqueue_enc_ops()``
 553   call belong to one mode, either CB-mode or TB-mode.
 554
 555 In case that the TB is smaller than Z (6144 bits), then effectively the TB = CB.
 556 CRC24A is appended to the tail of the CB. The application is responsible for
 557 calculating and appending CRC24A before calling BBDEV in case that the
 558 underlying driver does not support CRC24A generation.
 559
 560 In CB-mode, CRC24A/B is an optional operation.
 561 The CB parameter ``k`` is the size of the CB (this maps to K as described
 562 in 3GPP TS 36.212 section 5.1.2), this size is inclusive of CRC24A/B.
 563 The ``length`` is inclusive of CRC24A/B and equals to ``k`` in this case.
 564
 565 Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags
 566 ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` and ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
 567 informs the application with relevant capability. These flags can be set in the
 568 ``op_flags`` parameter to indicate to BBDEV to calculate and append CRC24A/B
 569 to CB before going forward with Turbo encoding.
 570
 571 Output format of the CB encode will have the encoded CB in ``e`` size output
 572 (this maps to E described in 3GPP TS 36.212 section 5.1.4.1.2). The output mbuf
 573 buffer size needs to be big enough to hold the encoded buffer of size ``e``.
 574
 575 In TB-mode, CRC24A is assumed to be pre-calculated and appended to the inbound
 576 TB mbuf data buffer.
 577 The output mbuf data structure is expected to be allocated by the application
 578 with enough room for the output data.
 579
 580 The difference between the partial and full-size TB is that we need to know the
 581 index of the first CB in this group and the number of CBs contained within.
 582 The first CB index is given by ``r`` but the number of the remaining CBs is
 583 calculated automatically by BBDEV before passing down to the driver.
 584
 585 The number of remaining CBs should not be confused with ``c``. ``c`` is the
 586 total number of CBs that composes the whole TB (this maps to C as
 587 described in 3GPP TS 36.212 section 5.1.2).
 588
 589 The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in
 590 case they were appended by the application.
 591
 592 The case when one CB belongs to TB and is being enqueued individually to BBDEV,
 593 this case is considered as a special case of partial TB where its number of CBs
 594 is 1. Therefore, it requires to get processed in TB-mode.
 595
 596 The figure below visualizes the encoding of CBs using BBDEV interface in
 597 TB-mode. CB-mode is a reduced version, where only one CB exists:
 598
 599 .. _figure_turbo_tb_encode:
 600
 601 .. figure:: img/turbo_tb_encode.*
 602
 603     Turbo encoding of Code Blocks in mbuf structure
 604
 605
 606 BBDEV Turbo Decode Operation
 607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 608
 609 .. code-block:: c
 610
 611     struct rte_bbdev_op_turbo_dec {
 612         struct rte_bbdev_op_data input;
 613         struct rte_bbdev_op_data hard_output;
 614         struct rte_bbdev_op_data soft_output;
 615
 616         uint32_t op_flags;
 617         uint8_t rv_index;
 618         uint8_t iter_min:4;
 619         uint8_t iter_max:4;
 620         uint8_t iter_count;
 621         uint8_t ext_scale;
 622         uint8_t num_maps;
 623         uint8_t code_block_mode;
 624         union {
 625             struct rte_bbdev_op_dec_cb_params cb_params;
 626             struct rte_bbdev_op_dec_tb_params tb_params;
 627         };
 628     };
 629
 630 The Turbo decode structure includes the ``input``, ``hard_output`` and
 631 optionally the ``soft_output`` mbuf data pointers.
 632
 633 .. csv-table:: **struct rte_bbdev_op_turbo_dec** parameters
 634    :header: "Parameter", "Description"
 635    :widths: 10, 30
 636
 637    "input","virtual circular buffer, wk, size 3*Kpi for each CB"
 638    "hard output","hard decisions buffer, decoded output, size K for each CB"
 639    "soft output","soft LLR output buffer (optional)"
 640    "op_flags","bitmask of all active operation capabilities"
 641    "rv_index","redundancy version index [0..3]"
 642    "iter_max","maximum number of iterations to perofrm in decode all CBs"
 643    "iter_min","minimum number of iterations to perform in decoding all CBs"
 644    "iter_count","number of iterations to performed in decoding all CBs"
 645    "ext_scale","scale factor on extrinsic info (5 bits)"
 646    "num_maps","number of MAP engines to use in decode"
 647    "code_block_mode","code block or transport block mode"
 648    "cb_params", "code block specific parameters (code block mode only)"
 649    "tb_params", "transport block specific parameters (transport block mode only)"
 650
 651 Similarly, the decode interface works on both the code block (CB) and the
 652 transport block (TB). An operation executes in "CB-mode" when the CB is
 653 standalone. While "TB-mode" executes when an operation performs on one or
 654 multiple CBs that belong to a TB. Therefore, a given data can be standalone CB,
 655 full-size TB or partial TB. Partial TB means that only a subset of CBs belonging
 656 to a bigger TB are being enqueued.
 657
 658   **NOTE:** It is assumed that all enqueued ops in one ``rte_bbdev_enqueue_dec_ops()``
 659   call belong to one mode, either CB-mode or TB-mode.
 660
 661
 662 The CB parameter ``k`` is the size of the decoded CB (this maps to K as described in
 663 3GPP TS 36.212 section 5.1.2), this size is inclusive of CRC24A/B.
 664 The ``length`` is inclusive of CRC24A/B and equals to ``k`` in this case.
 665
 666 The input encoded CB data is the Virtual Circular Buffer data stream, wk, with
 667 the null padding included as described in 3GPP TS 36.212 section 5.1.4.1.2 and
 668 shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1.
 669 The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte
 670 aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1.
 671
 672 Each byte in the input circular buffer is the LLR value of each bit of the
 673 original CB.
 674
 675 ``hard_output`` is a mandatory capability that all BBDEV PMDs support. This is
 676 the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB).
 677 Soft output is an optional capability for BBDEV PMDs. Setting flag
 678 ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` in ``op_flags`` directs BBDEV to retain
 679 CRC24B at the end of each CB. This might be useful for the application in debug
 680 mode.
 681 An LLR rate matched output is computed in the ``soft_output`` buffer structure
 682 for the given CB parameter ``e`` size (this maps to E described in
 683 3GPP TS 36.212 section 5.1.4.1.2). The output mbuf buffer size needs to be big
 684 enough to hold the encoded buffer of size ``e``.
 685
 686 The first CB Virtual Circular Buffer (VCB) index is given by ``r`` but the
 687 number of the remaining CB VCBs is calculated automatically by BBDEV before
 688 passing down to the driver.
 689
 690 The number of remaining CB VCBs should not be confused with ``c``. ``c`` is the
 691 total number of CBs that composes the whole TB (this maps to C as
 692 described in 3GPP TS 36.212 section 5.1.2).
 693
 694 The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in
 695 case they were appended by the application.
 696
 697 The case when one CB belongs to TB and is being enqueued individually to BBDEV,
 698 this case is considered as a special case of partial TB where its number of CBs
 699 is 1. Therefore, it requires to get processed in TB-mode.
 700
 701 The output mbuf data structure is expected to be allocated by the application
 702 with enough room for the output data.
 703
 704 The figure below visualizes the decoding of CBs using BBDEV interface in
 705 TB-mode. CB-mode is a reduced version, where only one CB exists:
 706
 707 .. _figure_turbo_tb_decode:
 708
 709 .. figure:: img/turbo_tb_decode.*
 710
 711     Turbo decoding of Code Blocks in mbuf structure
 712
 713 BBDEV LDPC Encode Operation
 714 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 715
 716 The operation flags that can be set for each LDPC encode operation are
 717 given below.
 718
 719   **NOTE:** The actual operation flags that may be used with a specific
 720   BBDEV PMD are dependent on the driver capabilities as reported via
 721   ``rte_bbdev_info_get()``, and may be a subset of those below.
 722
 723 +--------------------------------------------------------------------+
 724 |Description of LDPC encode capability flags                         |
 725 +====================================================================+
 726 |RTE_BBDEV_LDPC_INTERLEAVER_BYPASS                                   |
 727 | Set to bypass bit-level interleaver on output stream               |
 728 +--------------------------------------------------------------------+
 729 |RTE_BBDEV_LDPC_RATE_MATCH                                           |
 730 | Set to enabling the RATE_MATCHING processing                       |
 731 +--------------------------------------------------------------------+
 732 |RTE_BBDEV_LDPC_CRC_24A_ATTACH                                       |
 733 | Set to attach transport block CRC-24A                              |
 734 +--------------------------------------------------------------------+
 735 |RTE_BBDEV_LDPC_CRC_24B_ATTACH                                       |
 736 | Set to attach code block CRC-24B                                   |
 737 +--------------------------------------------------------------------+
 738 |RTE_BBDEV_LDPC_CRC_16_ATTACH                                        |
 739 | Set to attach code block CRC-16                                    |
 740 +--------------------------------------------------------------------+
 741 |RTE_BBDEV_LDPC_ENC_INTERRUPTS                                       |
 742 | Set if a device supports encoder dequeue interrupts                |
 743 +--------------------------------------------------------------------+
 744 |RTE_BBDEV_LDPC_ENC_SCATTER_GATHER                                   |
 745 | Set if a device supports scatter-gather functionality              |
 746 +--------------------------------------------------------------------+
 747 |RTE_BBDEV_LDPC_ENC_CONCATENATION                                    |
 748 | Set if a device supports concatenation of non byte aligned output  |
 749 +--------------------------------------------------------------------+
 750
 751 The structure passed for each LDPC encode operation is given below,
 752 with the operation flags forming a bitmask in the ``op_flags`` field.
 753
 754 .. code-block:: c
 755
 756     struct rte_bbdev_op_ldpc_enc {
 757
 758         struct rte_bbdev_op_data input;
 759         struct rte_bbdev_op_data output;
 760
 761         uint32_t op_flags;
 762         uint8_t rv_index;
 763         uint8_t basegraph;
 764         uint16_t z_c;
 765         uint16_t n_cb;
 766         uint8_t q_m;
 767         uint16_t n_filler;
 768         uint8_t code_block_mode;
 769         union {
 770             struct rte_bbdev_op_enc_ldpc_cb_params cb_params;
 771             struct rte_bbdev_op_enc_ldpc_tb_params tb_params;
 772         };
 773     };
 774
 775 The LDPC encode parameters are set out in the table below.
 776
 777 +----------------+--------------------------------------------------------------------+
 778 |Parameter       |Description                                                         |
 779 +================+====================================================================+
 780 |input           |input CB or TB data                                                 |
 781 +----------------+--------------------------------------------------------------------+
 782 |output          |rate matched CB or TB output buffer                                 |
 783 +----------------+--------------------------------------------------------------------+
 784 |op_flags        |bitmask of all active operation capabilities                        |
 785 +----------------+--------------------------------------------------------------------+
 786 |rv_index        |redundancy version index [0..3]                                     |
 787 +----------------+--------------------------------------------------------------------+
 788 |basegraph       |Basegraph 1 or 2                                                    |
 789 +----------------+--------------------------------------------------------------------+
 790 |z_c             |Zc, LDPC lifting size                                               |
 791 +----------------+--------------------------------------------------------------------+
 792 |n_cb            |Ncb, length of the circular buffer in bits.                         |
 793 +----------------+--------------------------------------------------------------------+
 794 |q_m             |Qm, modulation order {2,4,6,8,10}                                   |
 795 +----------------+--------------------------------------------------------------------+
 796 |n_filler        |number of filler bits                                               |
 797 +----------------+--------------------------------------------------------------------+
 798 |code_block_mode |code block or transport block mode                                  |
 799 +----------------+--------------------------------------------------------------------+
 800 |op_flags        |bitmask of all active operation capabilities                        |
 801 +----------------+--------------------------------------------------------------------+
 802 |**cb_params**   |code block specific parameters (code block mode only)               |
 803 +----------------+------------+-------------------------------------------------------+
 804 |                |e           |E, length of the rate matched output sequence in bits  |
 805 +----------------+------------+-------------------------------------------------------+
 806 |**tb_params**   | transport block specific parameters (transport block mode only)    |
 807 +----------------+------------+-------------------------------------------------------+
 808 |                |c           |number of CBs in the TB or partial TB                  |
 809 +----------------+------------+-------------------------------------------------------+
 810 |                |r           |index of the first CB in the inbound mbuf data         |
 811 +----------------+------------+-------------------------------------------------------+
 812 |                |c_ab        |number of CBs that use Ea before switching to Eb       |
 813 +----------------+------------+-------------------------------------------------------+
 814 |                |ea          |Ea, length of the RM output sequence in bits, r < cab  |
 815 +----------------+------------+-------------------------------------------------------+
 816 |                |eb          |Eb, length of the RM output sequence in bits, r >= cab |
 817 +----------------+------------+-------------------------------------------------------+
 818
 819 The mbuf input ``input`` is mandatory for all BBDEV PMDs and is the
 820 incoming code block or transport block data.
 821
 822 The mbuf output ``output`` is mandatory and is the encoded CB(s). In
 823 CB-mode ut contains the encoded CB of size ``e`` (E  in 3GPP TS 38.212
 824 section 6.2.5). In TB-mode it contains multiple contiguous encoded CBs
 825 of size ``ea`` or ``eb``.
 826 The ``output`` buffer is allocated by the application with enough room
 827 for the output data.
 828
 829 The encode interface works on both a code block (CB) and a transport
 830 block (TB) basis.
 831
 832   **NOTE:** All enqueued ops in one ``rte_bbdev_enqueue_enc_ops()``
 833   call belong to one mode, either CB-mode or TB-mode.
 834
 835 The valid modes of operation are:
 836
 837 * CB-mode: one CB (attach CRC24B if required)
 838 * CB-mode: one CB making up one TB (attach CRC24A if required)
 839 * TB-mode: one or more CB of a partial TB (attach CRC24B(s) if required)
 840 * TB-mode: one or more CB of a complete TB (attach CRC24AB(s) if required)
 841
 842 In CB-mode if ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` is set then CRC24A
 843 is appended to the CB. If ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` is not
 844 set the application is responsible for calculating and appending CRC24A
 845 before calling BBDEV. The input data mbuf ``length`` is inclusive of
 846 CRC24A/B where present and is equal to the code block size ``K``.
 847
 848 In TB-mode, CRC24A is assumed to be pre-calculated and appended to the
 849 inbound TB data buffer, unless the ``RTE_BBDEV_LDPC_CRC_24A_ATTACH``
 850 flag is set when it is the  responsibility of BBDEV. The input data
 851 mbuf ``length`` is total size of the CBs inclusive of any CRC24A and
 852 CRC24B in the case they were appended by the application.
 853
 854 Not all BBDEV PMDs may be capable of CRC24A/B calculation. Flags
 855 ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` and ``RTE_BBDEV_LDPC_CRC_24B_ATTACH``
 856 inform the application of the relevant capability. These flags can be set
 857 in the ``op_flags`` parameter to indicate BBDEV to calculate and append
 858 CRC24A to CB before going forward with LDPC encoding.
 859
 860 The difference between the partial and full-size TB is that BBDEV needs
 861 the index of the first CB in this group and the number of CBs in the group.
 862 The first CB index is given by ``r`` but the number of the CBs is
 863 calculated by BBDEV before signalling to the driver.
 864
 865 The number of CBs in the group should not be confused with ``c``, the
 866 total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2)
 867
 868 Figure :numref:`figure_turbo_tb_encode` above
 869 showing the Turbo encoding of CBs using BBDEV interface in TB-mode
 870 is also valid for LDPC encode.
 871
 872 BBDEV LDPC Decode Operation
 873 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 874
 875 The operation flags that can be set for each LDPC decode operation are
 876 given below.
 877
 878   **NOTE:** The actual operation flags that may be used with a specific
 879   BBDEV PMD are dependent on the driver capabilities as reported via
 880   ``rte_bbdev_info_get()``, and may be a subset of those below.
 881
 882 +--------------------------------------------------------------------+
 883 |Description of LDPC decode capability flags                         |
 884 +====================================================================+
 885 |RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK                                   |
 886 | Set for transport block CRC-24A checking                           |
 887 +--------------------------------------------------------------------+
 888 |RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK                                   |
 889 | Set for code block CRC-24B checking                                |
 890 +--------------------------------------------------------------------+
 891 |RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP                                    |
 892 | Set to drop the last CRC bits decoding output                      |
 893 +--------------------------------------------------------------------+
 894 |RTE_BBDEV_LDPC_DEINTERLEAVER_BYPASS                                 |
 895 | Set for bit-level de-interleaver bypass on input stream            |
 896 +--------------------------------------------------------------------+
 897 |RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE                                 |
 898 | Set for HARQ combined input stream enable                          |
 899 +--------------------------------------------------------------------+
 900 |RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE                                |
 901 | Set for HARQ combined output stream enable                         |
 902 +--------------------------------------------------------------------+
 903 |RTE_BBDEV_LDPC_DECODE_BYPASS                                        |
 904 | Set for LDPC decoder bypass                                        |
 905 |                                                                    |
 906 | RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE must be set                   |
 907 +--------------------------------------------------------------------+
 908 |RTE_BBDEV_LDPC_DECODE_SOFT_OUT                                      |
 909 | Set for soft-output stream  enable                                 |
 910 +--------------------------------------------------------------------+
 911 |RTE_BBDEV_LDPC_SOFT_OUT_RM_BYPASS                                   |
 912 | Set for Rate-Matching bypass on soft-out stream                    |
 913 +--------------------------------------------------------------------+
 914 |RTE_BBDEV_LDPC_SOFT_OUT_DEINTERLEAVER_BYPASS                        |
 915 | Set for bit-level de-interleaver bypass on soft-output stream      |
 916 +--------------------------------------------------------------------+
 917 |RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE                                |
 918 | Set for iteration stopping on successful decode condition enable   |
 919 |                                                                    |
 920 | Where a successful decode is a successful syndrome check           |
 921 +--------------------------------------------------------------------+
 922 |RTE_BBDEV_LDPC_DEC_INTERRUPTS                                       |
 923 | Set if a device supports decoder dequeue interrupts                |
 924 +--------------------------------------------------------------------+
 925 |RTE_BBDEV_LDPC_DEC_SCATTER_GATHER                                   |
 926 | Set if a device supports scatter-gather functionality              |
 927 +--------------------------------------------------------------------+
 928 |RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION                                |
 929 | Set if a device supports input/output HARQ compression             |
 930 +--------------------------------------------------------------------+
 931 |RTE_BBDEV_LDPC_LLR_COMPRESSION                                      |
 932 | Set if a device supports input LLR compression                     |
 933 +--------------------------------------------------------------------+
 934 |RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE                       |
 935 | Set if a device supports HARQ input to device's internal memory    |
 936 +--------------------------------------------------------------------+
 937 |RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE                      |
 938 | Set if a device supports HARQ output to device's internal memory   |
 939 +--------------------------------------------------------------------+
 940 |RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK                        |
 941 | Set if a device supports loopback access to HARQ internal memory   |
 942 +--------------------------------------------------------------------+
 943
 944 The structure passed for each LDPC decode operation is given below,
 945 with the operation flags forming a bitmask in the ``op_flags`` field.
 946
 947 .. code-block:: c
 948
 949
 950     struct rte_bbdev_op_ldpc_dec {
 951
 952         struct rte_bbdev_op_data input;
 953         struct rte_bbdev_op_data hard_output;
 954         struct rte_bbdev_op_data soft_output;
 955         struct rte_bbdev_op_data harq_combined_input;
 956         struct rte_bbdev_op_data harq_combined_output;
 957
 958         uint32_t op_flags;
 959         uint8_t rv_index;
 960         uint8_t basegraph;
 961         uint16_t z_c;
 962         uint16_t n_cb;
 963         uint8_t q_m;
 964         uint16_t n_filler;
 965         uint8_t iter_max;
 966         uint8_t iter_count;
 967         uint8_t code_block_mode;
 968         union {
 969             struct rte_bbdev_op_dec_ldpc_cb_params cb_params;
 970             struct rte_bbdev_op_dec_ldpc_tb_params tb_params;
 971         };
 972     };
 973
 974
 975 The LDPC decode parameters are set out in the table below.
 976
 977 +----------------+--------------------------------------------------------------------+
 978 |Parameter       |Description                                                         |
 979 +================+====================================================================+
 980 |input           |input CB or TB data                                                 |
 981 +----------------+--------------------------------------------------------------------+
 982 |hard_output     |hard decisions buffer, decoded output                               |
 983 +----------------+--------------------------------------------------------------------+
 984 |soft_output     |soft LLR output buffer (optional)                                   |
 985 +----------------+--------------------------------------------------------------------+
 986 |harq_comb_input |HARQ combined input buffer (optional)                               |
 987 +----------------+--------------------------------------------------------------------+
 988 |harq_comb_output|HARQ combined output buffer (optional)                              |
 989 +----------------+--------------------------------------------------------------------+
 990 |op_flags        |bitmask of all active operation capabilities                        |
 991 +----------------+--------------------------------------------------------------------+
 992 |rv_index        |redundancy version index [0..3]                                     |
 993 +----------------+--------------------------------------------------------------------+
 994 |basegraph       |Basegraph 1 or 2                                                    |
 995 +----------------+--------------------------------------------------------------------+
 996 |z_c             |Zc, LDPC lifting size                                               |
 997 +----------------+--------------------------------------------------------------------+
 998 |n_cb            |Ncb, length of the circular buffer in bits.                         |
 999 +----------------+--------------------------------------------------------------------+
1000 |q_m             |Qm, modulation order {1,2,4,6,8} from pi/2-BPSK to 256QAM           |
1001 +----------------+--------------------------------------------------------------------+
1002 |n_filler        |number of filler bits                                               |
1003 +----------------+--------------------------------------------------------------------+
1004 |iter_max        |maximum number of iterations to perform in decode all CBs           |
1005 +----------------+--------------------------------------------------------------------+
1006 |iter_count      |number of iterations performed in decoding all CBs                  |
1007 +----------------+--------------------------------------------------------------------+
1008 |code_block_mode |code block or transport block mode                                  |
1009 +----------------+--------------------------------------------------------------------+
1010 |op_flags        |bitmask of all active operation capabilities                        |
1011 +----------------+--------------------------------------------------------------------+
1012 |**cb_params**   |code block specific parameters (code block mode only)               |
1013 +----------------+------------+-------------------------------------------------------+
1014 |                |e           |E, length of the rate matched output sequence in bits  |
1015 +----------------+------------+-------------------------------------------------------+
1016 |**tb_params**   | transport block specific parameters (transport block mode only)    |
1017 +----------------+------------+-------------------------------------------------------+
1018 |                |c           |number of CBs in the TB or partial TB                  |
1019 +----------------+------------+-------------------------------------------------------+
1020 |                |r           |index of the first CB in the inbound mbuf data         |
1021 +----------------+------------+-------------------------------------------------------+
1022 |                |c_ab        |number of CBs that use Ea before switching to Eb       |
1023 +----------------+------------+-------------------------------------------------------+
1024 |                |ea          |Ea, length of the RM output sequence in bits, r < cab  |
1025 +----------------+------------+-------------------------------------------------------+
1026 |                |eb          |Eb, length of the RM output sequence in bits  r >= cab |
1027 +----------------+------------+-------------------------------------------------------+
1028
1029 The mbuf input ``input`` encoded CB data is mandatory for all BBDEV PMDs
1030 and is the Virtual Circular Buffer data stream with null padding.
1031 Each byte in the input circular buffer is the LLR value of each bit of
1032 the original CB.
1033
1034 The mbuf output ``hard_output`` is mandatory and is the decoded CBs size
1035 K (CRC24A/B is the last 24-bit in each decoded CB).
1036
1037 The mbuf output ``soft_output`` is optional and is an LLR rate matched
1038 output of size ``e`` (this is ``E`` as per 3GPP TS 38.212 section 6.2.5).
1039
1040 The mbuf input ``harq_combine_input`` is optional and is a buffer with
1041 the input to the HARQ combination function of the device. If the
1042 capability RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE is set
1043 then the HARQ is stored in memory internal to the device and not visible
1044 to BBDEV.
1045
1046 The mbuf output ``harq_combine_output`` is optional and is a buffer for
1047 the output of the HARQ combination function of the device. If the
1048 capability RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE is set
1049 then the HARQ is stored in memory internal to the device and not visible
1050 to BBDEV.
1051
1052 The output mbuf data structures are expected to be allocated by the
1053 application with enough room for the output data.
1054
1055 As with the LDPC encode, the decode interface works on both a code block
1056 (CB) and a transport block (TB) basis.
1057
1058   **NOTE:** All enqueued ops in one ``rte_bbdev_enqueue_dec_ops()``
1059   call belong to one mode, either CB-mode or TB-mode.
1060
1061 The valid modes of operation are:
1062
1063 * CB-mode: one CB (check CRC24B if required)
1064 * CB-mode: one CB making up one TB (check CRC24A if required)
1065 * TB-mode: one or more CB making up a partial TB (check CRC24B(s) if required)
1066 * TB-mode: one or more CB making up a complete TB (check CRC24B(s) if required)
1067
1068 The mbuf ``length`` is inclusive of CRC24A/B where present and is equal
1069 the code block size ``K``.
1070
1071 The first CB Virtual Circular Buffer (VCB) index is given by ``r`` but the
1072 number of the remaining CB VCBs is calculated automatically by BBDEV
1073 and passed down to the driver.
1074
1075 The number of remaining CB VCBs should not be confused with ``c``, the
1076 total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2)
1077
1078 The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in
1079 case they were appended by the application.
1080
1081 Figure :numref:`figure_turbo_tb_decode` above
1082 showing the Turbo decoding of CBs using BBDEV interface in TB-mode
1083 is also valid for LDPC decode.
1084
1085
1086 Sample code
1087 -----------
1088
1089 The baseband device sample application gives an introduction on how to use the
1090 bbdev framework, by giving a sample code performing a loop-back operation with a
1091 baseband processor capable of transceiving data packets.
1092
1093 The following sample C-like pseudo-code shows the basic steps to encode several
1094 buffers using (**sw_turbo**) bbdev PMD.
1095
1096 .. code-block:: c
1097
1098     /* EAL Init */
1099     ret = rte_eal_init(argc, argv);
1100     if (ret < 0)
1101         rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n");
1102
1103     /* Get number of available bbdev devices */
1104     nb_bbdevs = rte_bbdev_count();
1105     if (nb_bbdevs == 0)
1106         rte_exit(EXIT_FAILURE, "No bbdevs detected!\n");
1107
1108     /* Create bbdev op pools */
1109     bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC] =
1110             rte_bbdev_op_pool_create("bbdev_op_pool_enc",
1111             RTE_BBDEV_OP_TURBO_ENC, NB_MBUF, 128, rte_socket_id());
1112
1113     /* Get information for this device */
1114     rte_bbdev_info_get(dev_id, &info);
1115
1116     /* Setup BBDEV device queues */
1117     ret = rte_bbdev_setup_queues(dev_id, qs_nb, info.socket_id);
1118     if (ret < 0)
1119         rte_exit(EXIT_FAILURE,
1120                 "ERROR(%d): BBDEV %u not configured properly\n",
1121                 ret, dev_id);
1122
1123     /* setup device queues */
1124     qconf.socket = info.socket_id;
1125     qconf.queue_size = info.drv.queue_size_lim;
1126     qconf.op_type = RTE_BBDEV_OP_TURBO_ENC;
1127
1128     for (q_id = 0; q_id < qs_nb; q_id++) {
1129         /* Configure all queues belonging to this bbdev device */
1130         ret = rte_bbdev_queue_configure(dev_id, q_id, &qconf);
1131         if (ret < 0)
1132             rte_exit(EXIT_FAILURE,
1133                     "ERROR(%d): BBDEV %u queue %u not configured properly\n",
1134                     ret, dev_id, q_id);
1135     }
1136
1137     /* Start bbdev device */
1138     ret = rte_bbdev_start(dev_id);
1139
1140     /* Create the mbuf mempool for pkts */
1141     mbuf_pool = rte_pktmbuf_pool_create("bbdev_mbuf_pool",
1142             NB_MBUF, MEMPOOL_CACHE_SIZE, 0,
1143             RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id());
1144     if (mbuf_pool == NULL)
1145         rte_exit(EXIT_FAILURE,
1146                 "Unable to create '%s' pool\n", pool_name);
1147
1148     while (!global_exit_flag) {
1149
1150         /* Allocate burst of op structures in preparation for enqueue */
1151         if (rte_bbdev_enc_op_alloc_bulk(bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC],
1152             ops_burst, op_num) != 0)
1153             continue;
1154
1155         /* Allocate input mbuf pkts */
1156         ret = rte_pktmbuf_alloc_bulk(mbuf_pool, input_pkts_burst, MAX_PKT_BURST);
1157         if (ret < 0)
1158             continue;
1159
1160         /* Allocate output mbuf pkts */
1161         ret = rte_pktmbuf_alloc_bulk(mbuf_pool, output_pkts_burst, MAX_PKT_BURST);
1162         if (ret < 0)
1163             continue;
1164
1165         for (j = 0; j < op_num; j++) {
1166             /* Append the size of the ethernet header */
1167             rte_pktmbuf_append(input_pkts_burst[j],
1168                     sizeof(struct rte_ether_hdr));
1169
1170             /* set op */
1171
1172             ops_burst[j]->turbo_enc.input.offset =
1173                 sizeof(struct rte_ether_hdr);
1174
1175             ops_burst[j]->turbo_enc->input.length =
1176                 rte_pktmbuf_pkt_len(bbdev_pkts[j]);
1177
1178             ops_burst[j]->turbo_enc->input.data =
1179                 input_pkts_burst[j];
1180
1181             ops_burst[j]->turbo_enc->output.offset =
1182                 sizeof(struct rte_ether_hdr);
1183
1184             ops_burst[j]->turbo_enc->output.data =
1185                     output_pkts_burst[j];
1186         }
1187
1188         /* Enqueue packets on BBDEV device */
1189         op_num = rte_bbdev_enqueue_enc_ops(qconf->bbdev_id,
1190                 qconf->bbdev_qs[q], ops_burst,
1191                 MAX_PKT_BURST);
1192
1193         /* Dequeue packets from BBDEV device*/
1194         op_num = rte_bbdev_dequeue_enc_ops(qconf->bbdev_id,
1195                 qconf->bbdev_qs[q], ops_burst,
1196                 MAX_PKT_BURST);
1197     }
1198
1199
1200 BBDEV Device API
1201 ~~~~~~~~~~~~~~~~
1202
1203 The bbdev Library API is described in the *DPDK API Reference* document.