1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation 3 4Wireless Baseband Device Library 5================================ 6 7The Wireless Baseband library provides a common programming framework that 8abstracts HW accelerators based on FPGA and/or Fixed Function Accelerators that 9assist with 3GPP Physical Layer processing. Furthermore, it decouples the 10application from the compute-intensive wireless functions by abstracting their 11optimized libraries to appear as virtual bbdev devices. 12 13The functional scope of the BBDEV library are those functions in relation to 14the 3GPP Layer 1 signal processing (channel coding, modulation, ...). 15 16The framework currently only supports FEC function. 17 18 19Design Principles 20----------------- 21 22The Wireless Baseband library follows the same ideology of DPDK's Ethernet 23Device and Crypto Device frameworks. Wireless Baseband provides a generic 24acceleration abstraction framework which supports both physical (hardware) and 25virtual (software) wireless acceleration functions. 26 27Device Management 28----------------- 29 30Device Creation 31~~~~~~~~~~~~~~~ 32 33Physical bbdev devices are discovered during the PCI probe/enumeration of the 34EAL function which is executed at DPDK initialization, based on 35their PCI device identifier, each unique PCI BDF (bus/bridge, device, 36function). 37 38Virtual devices can be created by two mechanisms, either using the EAL command 39line options or from within the application using an EAL API directly. 40 41From 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 47Or 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 53All 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 60Device Identification 61~~~~~~~~~~~~~~~~~~~~~ 62 63Each device, whether virtual or physical is uniquely designated by two 64identifiers: 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 74Device Configuration 75~~~~~~~~~~~~~~~~~~~~ 76 77From the application point of view, each instance of a bbdev device consists of 78one or more queues identified by queue IDs. While different devices may have 79different capabilities (e.g. support different operation types), all queues on 80a device support identical configuration possibilities. A queue is configured 81for only one type of operation and is configured at initialization time. 82When an operation is enqueued to a specific queue ID, the result is dequeued 83from the same queue ID. 84 85Configuration of a device has two different levels: configuration that applies 86to the whole device, and configuration that applies to a single queue. 87 88Device configuration is applied with 89``rte_bbdev_setup_queues(dev_id,num_queues,socket_id)`` 90and queue configuration is applied with 91``rte_bbdev_queue_configure(dev_id,queue_id,conf)``. Note that, although all 92queues on a device support same capabilities, they can be configured differently 93and will then behave differently. 94Devices supporting interrupts can enable them by using 95``rte_bbdev_intr_enable(dev_id)``. 96 97The 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 103The ``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 116The ``rte_bbdev_intr_enable`` API is used to enable interrupts for a bbdev 117device, 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 124Queues Configuration 125~~~~~~~~~~~~~~~~~~~~ 126 127Each bbdev devices queue is individually configured through the 128``rte_bbdev_queue_configure()`` API. 129Each 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 141Device & Queues Management 142~~~~~~~~~~~~~~~~~~~~~~~~~~ 143 144After initialization, devices are in a stopped state, so must be started by the 145application. If an application is finished using a device it can close the 146device. 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 157By default, all queues are started when the device is started, but they can be 158stopped 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 166Logical Cores, Memory and Queues Relationships 167~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 168 169The bbdev poll mode device driver library supports NUMA architecture, in which 170a processor's logical cores and interfaces utilize it's local memory. Therefore 171with baseband operations, the mbuf being operated on should be allocated from memory 172pools created in the local memory. The buffers should, if possible, remain on 173the local processor to obtain the best performance results and buffer 174descriptors should be populated with mbufs allocated from a mempool allocated 175from local memory. 176 177The run-to-completion model also performs better, especially in the case of 178virtual bbdev devices, if the baseband operation and data buffers are in local 179memory instead of a remote processor's memory. This is also true for the 180pipe-line model provided all logical cores used are located on the same processor. 181 182Multiple logical cores should never share the same queue for enqueuing 183operations or dequeuing operations on the same bbdev device since this would 184require global locks and hinder performance. It is however possible to use a 185different logical core to dequeue an operation on a queue pair from the logical 186core which it was enqueued on. This means that a baseband burst enqueue/dequeue 187APIs are a logical place to transition from one logical core to another in a 188packet processing pipeline. 189 190 191Device Operation Capabilities 192----------------------------- 193 194Capabilities (in terms of operations supported, max number of queues, etc.) 195identify what a bbdev is capable of performing that differs from one device to 196another. For the full scope of the bbdev capability see the definition of the 197structure in the *DPDK API Reference*. 198 199.. code-block:: c 200 201 struct rte_bbdev_op_cap; 202 203A device reports its capabilities when registering itself in the bbdev framework. 204With the aid of this capabilities mechanism, an application can query devices to 205discover which operations within the 3GPP physical layer they are capable of 206performing. Below is an example of the capabilities for a PMD it supports in 207relation 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 244Capabilities Discovery 245~~~~~~~~~~~~~~~~~~~~~~ 246 247Discovering the features and capabilities of a bbdev device poll mode driver 248is 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 254This allows the user to query a specific bbdev PMD and get all the device 255capabilities. The ``rte_bbdev_info`` structure provides two levels of 256information: 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.. literalinclude:: ../../../lib/bbdev/rte_bbdev.h 265 :language: c 266 :start-after: Structure rte_bbdev_driver_info 8< 267 :end-before: >8 End of structure rte_bbdev_driver_info. 268 269.. literalinclude:: ../../../lib/bbdev/rte_bbdev.h 270 :language: c 271 :start-after: Structure rte_bbdev_info 8< 272 :end-before: >8 End of structure rte_bbdev_info. 273 274Capabilities details for LDPC Decoder 275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 276 277On top of the ``RTE_BBDEV_LDPC_<*>`` capabilities 278the device also exposes the LLR numerical representation 279expected by the decoder as a fractional fixed-point representation. 280For instance, when the representation (``llr_size``, ``llr_decimals``) = (8, 2) respectively, 281this means that each input LLR in the data provided by the application must be computed 282as 8 total bits (including sign bit) 283where 2 of these are fractions bits (also referred to as S8.2 format). 284It is up to the user application during LLR generation to scale the LLR 285according to this optimal numerical representation. 286Any mis-scaled LLR would cause wireless performance degradation. 287 288The ``harq_buffer_size`` exposes the amount of dedicated DDR 289made available for the device operation. 290This is specific for accelerator non-integrated on the CPU (separate PCIe device) 291which may include separate on-card memory. 292 293Capabilities details for FFT function 294~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 295 296The total number of distinct time windows supported 297for the post-FFT point-wise multiplication is exposed as ``fft_windows_num``. 298The ``window_index`` provided for each cyclic shift 299in each ``rte_bbdev_op_fft`` operation is expected to be limited to that size. 300 301The information related to the width of each of these pre-configured window 302is also exposed using the ``fft_window_width`` array. 303This provides the number of non-null samples 304used for each window index when scaling back the size to a reference of 1024 FFT. 305The actual shape size is effectively scaled up or down 306based on the dynamic size of the FFT operation being used. 307 308This allows to distinguish different version of the flexible pointwise windowing 309applied to the FFT and exposes this platform configuration to the application. 310 311Other optional capabilities exposed during device discovery 312~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 313 314The device status can be used to expose additional information 315related to the state of the platform notably based on its configuration state 316or related to error management (correctable or non). 317 318The queue topology exposed to the device is provided on top of the capabilities. 319This provides the number of queues available 320for the exposed bbdev device (the physical device may have more) 321for each operation as well as the different level of priority available for arbitration. 322These are based on the arrays and parameters 323``num_queues``, ``queue_priority``, ``max_num_queues``, ``queue_size_lim``. 324 325 326Operation Processing 327-------------------- 328 329Scheduling of baseband operations on DPDK's application data path is 330performed using a burst oriented asynchronous API set. A queue on a bbdev 331device accepts a burst of baseband operations using enqueue burst API. On physical 332bbdev devices the enqueue burst API will place the operations to be processed 333on the device's hardware input queue, for virtual devices the processing of the 334baseband operations is usually completed during the enqueue call to the bbdev 335device. The dequeue burst API will retrieve any processed operations available 336from the queue on the bbdev device, from physical devices this is usually 337directly from the device's processed queue, and for virtual device's from a 338``rte_ring`` where processed operations are placed after being processed on the 339enqueue call. 340 341 342Enqueue / Dequeue Burst APIs 343~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 344 345The burst enqueue API uses a bbdev device identifier and a queue 346identifier to specify the bbdev device queue to schedule the processing on. 347The ``num_ops`` parameter is the number of operations to process which are 348supplied in the ``ops`` array of ``rte_bbdev_*_op`` structures. 349The enqueue function returns the number of operations it actually enqueued for 350processing, a return value equal to ``num_ops`` means that all packets have been 351enqueued. 352 353.. code-block:: c 354 355 uint16_t rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id, 356 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 357 358 uint16_t rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id, 359 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 360 361The dequeue API uses the same format as the enqueue API of processed but 362the ``num_ops`` and ``ops`` parameters are now used to specify the max processed 363operations the user wishes to retrieve and the location in which to store them. 364The API call returns the actual number of processed operations returned, this 365can never be larger than ``num_ops``. 366 367.. code-block:: c 368 369 uint16_t rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id, 370 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 371 372 uint16_t rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id, 373 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 374 375Operation Representation 376~~~~~~~~~~~~~~~~~~~~~~~~ 377 378An encode bbdev operation is represented by ``rte_bbdev_enc_op`` structure, 379and by ``rte_bbdev_dec_op`` for decode. These structures act as metadata 380containers for all necessary information required for the bbdev operation to be 381processed on a particular bbdev device poll mode driver. 382 383.. code-block:: c 384 385 struct rte_bbdev_enc_op { 386 int status; 387 struct rte_mempool *mempool; 388 void *opaque_data; 389 union { 390 struct rte_bbdev_op_turbo_enc turbo_enc; 391 struct rte_bbdev_op_ldpc_enc ldpc_enc; 392 } 393 }; 394 395 struct rte_bbdev_dec_op { 396 int status; 397 struct rte_mempool *mempool; 398 void *opaque_data; 399 union { 400 struct rte_bbdev_op_turbo_dec turbo_enc; 401 struct rte_bbdev_op_ldpc_dec ldpc_enc; 402 } 403 }; 404 405The operation structure by itself defines the operation type. It includes an 406operation status, a reference to the operation specific data, which can vary in 407size and content depending on the operation being provisioned. It also contains 408the source mempool for the operation, if it is allocated from a mempool. 409 410If bbdev operations are allocated from a bbdev operation mempool, see next 411section, there is also the ability to allocate private memory with the 412operation for applications purposes. 413 414Application software is responsible for specifying all the operation specific 415fields in the ``rte_bbdev_*_op`` structure which are then used by the bbdev PMD 416to process the requested operation. 417 418 419Operation Management and Allocation 420~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 421 422The bbdev library provides an API set for managing bbdev operations which 423utilize the Mempool Library to allocate operation buffers. Therefore, it ensures 424that the bbdev operation is interleaved optimally across the channels and 425ranks for optimal processing. 426 427.. code-block:: c 428 429 struct rte_mempool * 430 rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type, 431 unsigned int num_elements, unsigned int cache_size, 432 int socket_id) 433 434``rte_bbdev_*_op_alloc_bulk()`` and ``rte_bbdev_*_op_free_bulk()`` are used to 435allocate bbdev operations of a specific type from a given bbdev operation mempool. 436 437.. code-block:: c 438 439 int rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool, 440 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 441 442 int rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool, 443 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 444 445``rte_bbdev_*_op_free_bulk()`` is called by the application to return an 446operation to its allocating pool. 447 448.. code-block:: c 449 450 void rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, 451 unsigned int num_ops) 452 void rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, 453 unsigned int num_ops) 454 455BBDEV Inbound/Outbound Memory 456~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 457 458The bbdev operation structure contains all the mutable data relating to 459performing Turbo and LDPC coding on a referenced mbuf data buffer. It is used for either 460encode or decode operations. 461 462 463.. csv-table:: Operation I/O 464 :header: "FEC", "In", "Out" 465 :widths: 20, 30, 30 466 467 "Turbo Encode", "input", "output" 468 "Turbo Decode", "input", "hard output" 469 " ", " ", "soft output (optional)" 470 "LDPC Encode", "input", "output" 471 "LDPC Decode", "input", "hard output" 472 "", "HQ combine (optional)", "HQ combine (optional)" 473 " ", "", "soft output (optional)" 474 475 476It is expected that the application provides input and output mbuf pointers 477allocated and ready to use. 478 479The baseband framework supports FEC coding on Code Blocks (CB) and 480Transport Blocks (TB). 481 482For the output buffer(s), the application is required to provide an allocated 483and free mbuf, to which the resulting output will be written. 484 485The support of split "scattered" buffers is a driver-specific feature, so it is 486reported individually by the supporting driver as a capability. 487 488Input and output data buffers are identified by ``rte_bbdev_op_data`` structure, 489as follows: 490 491.. code-block:: c 492 493 struct rte_bbdev_op_data { 494 struct rte_mbuf *data; 495 uint32_t offset; 496 uint32_t length; 497 }; 498 499 500This structure has three elements: 501 502- ``data``: This is the mbuf data structure representing the data for BBDEV 503 operation. 504 505 This mbuf pointer can point to one Code Block (CB) data buffer or multiple CBs 506 contiguously located next to each other. A Transport Block (TB) represents a 507 whole piece of data that is divided into one or more CBs. Maximum number of 508 CBs can be contained in one TB is defined by 509 ``RTE_BBDEV_(TURBO/LDPC)MAX_CODE_BLOCKS``. 510 511 An mbuf data structure cannot represent more than one TB. The smallest piece 512 of data that can be contained in one mbuf is one CB. 513 An mbuf can include one contiguous CB, subset of contiguous CBs that are 514 belonging to one TB, or all contiguous CBs that belong to one TB. 515 516 If a BBDEV PMD supports the extended capability "Scatter-Gather", then it is 517 capable of collecting (gathering) non-contiguous (scattered) data from 518 multiple locations in the memory. 519 This capability is reported by the capability flags: 520 521 - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``, ``RTE_BBDEV_TURBO_DEC_SCATTER_GATHER``, 522 523 - ``RTE_BBDEV_LDPC_ENC_SCATTER_GATHER``, ``RTE_BBDEV_LDPC_DEC_SCATTER_GATHER``. 524 525 Chained mbuf data structures are only accepted if a BBDEV PMD supports this 526 feature. A chained mbuf can represent one non-contiguous CB or multiple non-contiguous 527 CBs. The first mbuf segment in the given chained mbuf represents the first piece 528 of the CB. Offset is only applicable to the first segment. ``length`` is the 529 total length of the CB. 530 531 BBDEV driver is responsible for identifying where the split is and enqueue 532 the split data to its internal queues. 533 534 If BBDEV PMD does not support this feature, it will assume inbound mbuf data 535 contains one segment. 536 537 The output mbuf data though is always one segment, even if the input was a 538 chained mbuf. 539 540 541- ``offset``: This is the starting point of the BBDEV (encode/decode) operation, 542 in bytes. 543 544 BBDEV starts to read data past this offset. 545 In case of chained mbuf, this offset applies only to the first mbuf segment. 546 547 548- ``length``: This is the total data length to be processed in one operation, 549 in bytes. 550 551 In case the mbuf data is representing one CB, this is the length of the CB 552 undergoing the operation. 553 If it is for multiple CBs, this is the total length of those CBs undergoing 554 the operation. 555 If it is for one TB, this is the total length of the TB under operation. 556 In case of chained mbuf, this data length includes the lengths of the 557 "scattered" data segments undergoing the operation. 558 559 560BBDEV Turbo Encode Operation 561~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 562 563.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h 564 :language: c 565 :start-after: Structure rte_bbdev_op_turbo_enc 8< 566 :end-before: >8 End of structure rte_bbdev_op_turbo_enc. 567 568The Turbo encode structure includes the ``input`` and ``output`` mbuf 569data pointers. The provided mbuf pointer of ``input`` needs to be big 570enough to stretch for extra CRC trailers. 571 572.. csv-table:: **struct rte_bbdev_op_turbo_enc** parameters 573 :header: "Parameter", "Description" 574 :widths: 10, 30 575 576 "input","input CB or TB data" 577 "output","rate matched CB or TB output buffer" 578 "op_flags","bitmask of all active operation capabilities" 579 "rv_index","redundancy version index [0..3]" 580 "code_block_mode","code block or transport block mode" 581 "cb_params", "code block specific parameters (code block mode only)" 582 "tb_params", "transport block specific parameters (transport block mode only)" 583 584 585The encode interface works on both the code block (CB) and the transport block 586(TB). An operation executes in "CB-mode" when the CB is standalone. While 587"TB-mode" executes when an operation performs on one or multiple CBs that 588belong to a TB. Therefore, a given data can be standalone CB, full-size TB or 589partial TB. Partial TB means that only a subset of CBs belonging to a bigger TB 590are being enqueued. 591 592 **NOTE:** It is assumed that all enqueued ops in one ``rte_bbdev_enqueue_enc_ops()`` 593 call belong to one mode, either CB-mode or TB-mode. 594 595In case that the TB is smaller than Z (6144 bits), then effectively the TB = CB. 596CRC24A is appended to the tail of the CB. The application is responsible for 597calculating and appending CRC24A before calling BBDEV in case that the 598underlying driver does not support CRC24A generation. 599 600In CB-mode, CRC24A/B is an optional operation. 601The CB parameter ``k`` is the size of the CB (this maps to K as described 602in 3GPP TS 36.212 section 5.1.2), this size is inclusive of CRC24A/B. 603The ``length`` is inclusive of CRC24A/B and equals to ``k`` in this case. 604 605Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags 606``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` and ``RTE_BBDEV_TURBO_CRC_24B_ATTACH`` 607informs the application with relevant capability. These flags can be set in the 608``op_flags`` parameter to indicate to BBDEV to calculate and append CRC24A/B 609to CB before going forward with Turbo encoding. 610 611Output format of the CB encode will have the encoded CB in ``e`` size output 612(this maps to E described in 3GPP TS 36.212 section 5.1.4.1.2). The output mbuf 613buffer size needs to be big enough to hold the encoded buffer of size ``e``. 614 615In TB-mode, CRC24A is assumed to be pre-calculated and appended to the inbound 616TB mbuf data buffer. 617The output mbuf data structure is expected to be allocated by the application 618with enough room for the output data. 619 620The difference between the partial and full-size TB is that we need to know the 621index of the first CB in this group and the number of CBs contained within. 622The first CB index is given by ``r`` but the number of the remaining CBs is 623calculated automatically by BBDEV before passing down to the driver. 624 625The number of remaining CBs should not be confused with ``c``. ``c`` is the 626total number of CBs that composes the whole TB (this maps to C as 627described in 3GPP TS 36.212 section 5.1.2). 628 629The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in 630case they were appended by the application. 631 632The case when one CB belongs to TB and is being enqueued individually to BBDEV, 633this case is considered as a special case of partial TB where its number of CBs 634is 1. Therefore, it requires to get processed in TB-mode. 635 636The figure below visualizes the encoding of CBs using BBDEV interface in 637TB-mode. CB-mode is a reduced version, where only one CB exists: 638 639.. _figure_turbo_tb_encode: 640 641.. figure:: img/turbo_tb_encode.* 642 643 Turbo encoding of Code Blocks in mbuf structure 644 645 646BBDEV Turbo Decode Operation 647~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 648 649.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h 650 :language: c 651 :start-after: Structure rte_bbdev_op_turbo_dec 8< 652 :end-before: >8 End of structure rte_bbdev_op_turbo_dec. 653 654The Turbo decode structure includes the ``input``, ``hard_output`` and 655optionally the ``soft_output`` mbuf data pointers. 656 657.. csv-table:: **struct rte_bbdev_op_turbo_dec** parameters 658 :header: "Parameter", "Description" 659 :widths: 10, 30 660 661 "input","virtual circular buffer, wk, size 3*Kpi for each CB" 662 "hard output","hard decisions buffer, decoded output, size K for each CB" 663 "soft output","soft LLR output buffer (optional)" 664 "op_flags","bitmask of all active operation capabilities" 665 "rv_index","redundancy version index [0..3]" 666 "iter_max","maximum number of iterations to perform in decode all CBs" 667 "iter_min","minimum number of iterations to perform in decoding all CBs" 668 "iter_count","number of iterations to performed in decoding all CBs" 669 "ext_scale","scale factor on extrinsic info (5 bits)" 670 "num_maps","number of MAP engines to use in decode" 671 "code_block_mode","code block or transport block mode" 672 "cb_params", "code block specific parameters (code block mode only)" 673 "tb_params", "transport block specific parameters (transport block mode only)" 674 675Similarly, the decode interface works on both the code block (CB) and the 676transport block (TB). An operation executes in "CB-mode" when the CB is 677standalone. While "TB-mode" executes when an operation performs on one or 678multiple CBs that belong to a TB. Therefore, a given data can be standalone CB, 679full-size TB or partial TB. Partial TB means that only a subset of CBs belonging 680to a bigger TB are being enqueued. 681 682 **NOTE:** It is assumed that all enqueued ops in one ``rte_bbdev_enqueue_dec_ops()`` 683 call belong to one mode, either CB-mode or TB-mode. 684 685 686The CB parameter ``k`` is the size of the decoded CB (this maps to K as described in 6873GPP TS 36.212 section 5.1.2), this size is inclusive of CRC24A/B. 688The ``length`` is inclusive of CRC24A/B and equals to ``k`` in this case. 689 690The input encoded CB data is the Virtual Circular Buffer data stream, wk, with 691the null padding included as described in 3GPP TS 36.212 section 5.1.4.1.2 and 692shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1. 693The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte 694aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1. 695 696Each byte in the input circular buffer is the LLR value of each bit of the 697original CB. 698 699``hard_output`` is a mandatory capability that all BBDEV PMDs support. This is 700the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB). 701Soft output is an optional capability for BBDEV PMDs. Setting flag 702``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` in ``op_flags`` directs BBDEV to retain 703CRC24B at the end of each CB. This might be useful for the application in debug 704mode. 705An LLR rate matched output is computed in the ``soft_output`` buffer structure 706for the given CB parameter ``e`` size (this maps to E described in 7073GPP TS 36.212 section 5.1.4.1.2). The output mbuf buffer size needs to be big 708enough to hold the encoded buffer of size ``e``. 709 710The first CB Virtual Circular Buffer (VCB) index is given by ``r`` but the 711number of the remaining CB VCBs is calculated automatically by BBDEV before 712passing down to the driver. 713 714The number of remaining CB VCBs should not be confused with ``c``. ``c`` is the 715total number of CBs that composes the whole TB (this maps to C as 716described in 3GPP TS 36.212 section 5.1.2). 717 718The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in 719case they were appended by the application. 720 721The case when one CB belongs to TB and is being enqueued individually to BBDEV, 722this case is considered as a special case of partial TB where its number of CBs 723is 1. Therefore, it requires to get processed in TB-mode. 724 725The output mbuf data structure is expected to be allocated by the application 726with enough room for the output data. 727 728The figure below visualizes the decoding of CBs using BBDEV interface in 729TB-mode. CB-mode is a reduced version, where only one CB exists: 730 731.. _figure_turbo_tb_decode: 732 733.. figure:: img/turbo_tb_decode.* 734 735 Turbo decoding of Code Blocks in mbuf structure 736 737BBDEV LDPC Encode Operation 738~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 739 740The operation flags that can be set for each LDPC encode operation are 741given below. 742 743 **NOTE:** The actual operation flags that may be used with a specific 744 BBDEV PMD are dependent on the driver capabilities as reported via 745 ``rte_bbdev_info_get()``, and may be a subset of those below. 746 747+--------------------------------------------------------------------+ 748|Description of LDPC encode capability flags | 749+====================================================================+ 750|RTE_BBDEV_LDPC_INTERLEAVER_BYPASS | 751| Set to bypass bit-level interleaver on output stream | 752+--------------------------------------------------------------------+ 753|RTE_BBDEV_LDPC_RATE_MATCH | 754| Set to enabling the RATE_MATCHING processing | 755+--------------------------------------------------------------------+ 756|RTE_BBDEV_LDPC_CRC_24A_ATTACH | 757| Set to attach transport block CRC-24A | 758+--------------------------------------------------------------------+ 759|RTE_BBDEV_LDPC_CRC_24B_ATTACH | 760| Set to attach code block CRC-24B | 761+--------------------------------------------------------------------+ 762|RTE_BBDEV_LDPC_CRC_16_ATTACH | 763| Set to attach code block CRC-16 | 764+--------------------------------------------------------------------+ 765|RTE_BBDEV_LDPC_ENC_INTERRUPTS | 766| Set if a device supports encoder dequeue interrupts | 767+--------------------------------------------------------------------+ 768|RTE_BBDEV_LDPC_ENC_SCATTER_GATHER | 769| Set if a device supports scatter-gather functionality | 770+--------------------------------------------------------------------+ 771|RTE_BBDEV_LDPC_ENC_CONCATENATION | 772| Set if a device supports concatenation of non byte aligned output | 773+--------------------------------------------------------------------+ 774 775The structure passed for each LDPC encode operation is given below, 776with the operation flags forming a bitmask in the ``op_flags`` field. 777 778.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h 779 :language: c 780 :start-after: Structure rte_bbdev_op_ldpc_enc 8< 781 :end-before: >8 End of structure rte_bbdev_op_ldpc_enc. 782 783The LDPC encode parameters are set out in the table below. 784 785+----------------+--------------------------------------------------------------------+ 786|Parameter |Description | 787+================+====================================================================+ 788|input |input CB or TB data | 789+----------------+--------------------------------------------------------------------+ 790|output |rate matched CB or TB output buffer | 791+----------------+--------------------------------------------------------------------+ 792|op_flags |bitmask of all active operation capabilities | 793+----------------+--------------------------------------------------------------------+ 794|rv_index |redundancy version index [0..3] | 795+----------------+--------------------------------------------------------------------+ 796|basegraph |Basegraph 1 or 2 | 797+----------------+--------------------------------------------------------------------+ 798|z_c |Zc, LDPC lifting size | 799+----------------+--------------------------------------------------------------------+ 800|n_cb |Ncb, length of the circular buffer in bits. | 801+----------------+--------------------------------------------------------------------+ 802|q_m |Qm, modulation order {2,4,6,8,10} | 803+----------------+--------------------------------------------------------------------+ 804|n_filler |number of filler bits | 805+----------------+--------------------------------------------------------------------+ 806|code_block_mode |code block or transport block mode | 807+----------------+--------------------------------------------------------------------+ 808|op_flags |bitmask of all active operation capabilities | 809+----------------+--------------------------------------------------------------------+ 810|**cb_params** |code block specific parameters (code block mode only) | 811+----------------+------------+-------------------------------------------------------+ 812| |e |E, length of the rate matched output sequence in bits | 813+----------------+------------+-------------------------------------------------------+ 814|**tb_params** | transport block specific parameters (transport block mode only) | 815+----------------+------------+-------------------------------------------------------+ 816| |c |number of CBs in the TB or partial TB | 817+----------------+------------+-------------------------------------------------------+ 818| |r |index of the first CB in the inbound mbuf data | 819+----------------+------------+-------------------------------------------------------+ 820| |c_ab |number of CBs that use Ea before switching to Eb | 821+----------------+------------+-------------------------------------------------------+ 822| |ea |Ea, length of the RM output sequence in bits, r < cab | 823+----------------+------------+-------------------------------------------------------+ 824| |eb |Eb, length of the RM output sequence in bits, r >= cab | 825+----------------+------------+-------------------------------------------------------+ 826 827The mbuf input ``input`` is mandatory for all BBDEV PMDs and is the 828incoming code block or transport block data. 829 830The mbuf output ``output`` is mandatory and is the encoded CB(s). In 831CB-mode ut contains the encoded CB of size ``e`` (E in 3GPP TS 38.212 832section 6.2.5). In TB-mode it contains multiple contiguous encoded CBs 833of size ``ea`` or ``eb``. 834The ``output`` buffer is allocated by the application with enough room 835for the output data. 836 837The encode interface works on both a code block (CB) and a transport 838block (TB) basis. 839 840 **NOTE:** All enqueued ops in one ``rte_bbdev_enqueue_enc_ops()`` 841 call belong to one mode, either CB-mode or TB-mode. 842 843The valid modes of operation are: 844 845* CB-mode: one CB (attach CRC24B if required) 846* CB-mode: one CB making up one TB (attach CRC24A if required) 847* TB-mode: one or more CB of a partial TB (attach CRC24B(s) if required) 848* TB-mode: one or more CB of a complete TB (attach CRC24AB(s) if required) 849 850In CB-mode if ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` is set then CRC24A 851is appended to the CB. If ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` is not 852set the application is responsible for calculating and appending CRC24A 853before calling BBDEV. The input data mbuf ``length`` is inclusive of 854CRC24A/B where present and is equal to the code block size ``K``. 855 856In TB-mode, CRC24A is assumed to be pre-calculated and appended to the 857inbound TB data buffer, unless the ``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` 858flag is set when it is the responsibility of BBDEV. The input data 859mbuf ``length`` is total size of the CBs inclusive of any CRC24A and 860CRC24B in the case they were appended by the application. 861 862Not all BBDEV PMDs may be capable of CRC24A/B calculation. Flags 863``RTE_BBDEV_LDPC_CRC_24A_ATTACH`` and ``RTE_BBDEV_LDPC_CRC_24B_ATTACH`` 864inform the application of the relevant capability. These flags can be set 865in the ``op_flags`` parameter to indicate BBDEV to calculate and append 866CRC24A to CB before going forward with LDPC encoding. 867 868The difference between the partial and full-size TB is that BBDEV needs 869the index of the first CB in this group and the number of CBs in the group. 870The first CB index is given by ``r`` but the number of the CBs is 871calculated by BBDEV before signalling to the driver. 872 873The number of CBs in the group should not be confused with ``c``, the 874total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) 875 876Figure :numref:`figure_turbo_tb_encode` above 877showing the Turbo encoding of CBs using BBDEV interface in TB-mode 878is also valid for LDPC encode. 879 880BBDEV LDPC Decode Operation 881~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 882 883The operation flags that can be set for each LDPC decode operation are 884given below. 885 886 **NOTE:** The actual operation flags that may be used with a specific 887 BBDEV PMD are dependent on the driver capabilities as reported via 888 ``rte_bbdev_info_get()``, and may be a subset of those below. 889 890+--------------------------------------------------------------------+ 891|Description of LDPC decode capability flags | 892+====================================================================+ 893|RTE_BBDEV_LDPC_CRC_TYPE_24A_CHECK | 894| Set for transport block CRC-24A checking | 895+--------------------------------------------------------------------+ 896|RTE_BBDEV_LDPC_CRC_TYPE_24B_CHECK | 897| Set for code block CRC-24B checking | 898+--------------------------------------------------------------------+ 899|RTE_BBDEV_LDPC_CRC_TYPE_24B_DROP | 900| Set to drop the last CRC bits decoding output | 901+--------------------------------------------------------------------+ 902|RTE_BBDEV_LDPC_CRC_TYPE_16_CHECK | 903| Set for code block CRC-16 checking | 904+--------------------------------------------------------------------+ 905|RTE_BBDEV_LDPC_DEINTERLEAVER_BYPASS | 906| Set for bit-level de-interleaver bypass on input stream | 907+--------------------------------------------------------------------+ 908|RTE_BBDEV_LDPC_HQ_COMBINE_IN_ENABLE | 909| Set for HARQ combined input stream enable | 910+--------------------------------------------------------------------+ 911|RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE | 912| Set for HARQ combined output stream enable | 913+--------------------------------------------------------------------+ 914|RTE_BBDEV_LDPC_DECODE_BYPASS | 915| Set for LDPC decoder bypass | 916| | 917| RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE must be set | 918+--------------------------------------------------------------------+ 919|RTE_BBDEV_LDPC_DECODE_SOFT_OUT | 920| Set for soft-output stream enable | 921+--------------------------------------------------------------------+ 922|RTE_BBDEV_LDPC_SOFT_OUT_RM_BYPASS | 923| Set for Rate-Matching bypass on soft-out stream | 924+--------------------------------------------------------------------+ 925|RTE_BBDEV_LDPC_SOFT_OUT_DEINTERLEAVER_BYPASS | 926| Set for bit-level de-interleaver bypass on soft-output stream | 927+--------------------------------------------------------------------+ 928|RTE_BBDEV_LDPC_ITERATION_STOP_ENABLE | 929| Set for iteration stopping on successful decode condition enable | 930| | 931| Where a successful decode is a successful syndrome check | 932+--------------------------------------------------------------------+ 933|RTE_BBDEV_LDPC_DEC_INTERRUPTS | 934| Set if a device supports decoder dequeue interrupts | 935+--------------------------------------------------------------------+ 936|RTE_BBDEV_LDPC_DEC_SCATTER_GATHER | 937| Set if a device supports scatter-gather functionality | 938+--------------------------------------------------------------------+ 939|RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION | 940| Set if a device supports input/output HARQ compression | 941| Data is packed as 6 bits by dropping and saturating the MSBs | 942+--------------------------------------------------------------------+ 943|RTE_BBDEV_LDPC_LLR_COMPRESSION | 944| Set if a device supports input LLR compression | 945| Data is packed as 6 bits by dropping and saturating the MSBs | 946+--------------------------------------------------------------------+ 947|RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE | 948| Set if a device supports HARQ input to device's internal memory | 949+--------------------------------------------------------------------+ 950|RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE | 951| Set if a device supports HARQ output to device's internal memory | 952+--------------------------------------------------------------------+ 953|RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_LOOPBACK | 954| Set if a device supports loopback access to HARQ internal memory | 955+--------------------------------------------------------------------+ 956|RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_FILLERS | 957| Set if a device includes LLR filler bits in HARQ circular buffer | 958+--------------------------------------------------------------------+ 959|RTE_BBDEV_LDPC_HARQ_4BIT_COMPRESSION | 960|Set if a device supports input/output 4 bits HARQ compression | 961+--------------------------------------------------------------------+ 962 963The structure passed for each LDPC decode operation is given below, 964with the operation flags forming a bitmask in the ``op_flags`` field. 965 966.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h 967 :language: c 968 :start-after: Structure rte_bbdev_op_ldpc_dec 8< 969 :end-before: >8 End of structure rte_bbdev_op_ldpc_dec. 970 971The LDPC decode parameters are set out in the table below. 972 973+----------------+--------------------------------------------------------------------+ 974|Parameter |Description | 975+================+====================================================================+ 976|input |input CB or TB data | 977+----------------+--------------------------------------------------------------------+ 978|hard_output |hard decisions buffer, decoded output | 979+----------------+--------------------------------------------------------------------+ 980|soft_output |soft LLR output buffer (optional) | 981+----------------+--------------------------------------------------------------------+ 982|harq_comb_input |HARQ combined input buffer (optional) | 983+----------------+--------------------------------------------------------------------+ 984|harq_comb_output|HARQ combined output buffer (optional) | 985+----------------+--------------------------------------------------------------------+ 986|op_flags |bitmask of all active operation capabilities | 987+----------------+--------------------------------------------------------------------+ 988|rv_index |redundancy version index [0..3] | 989+----------------+--------------------------------------------------------------------+ 990|basegraph |Basegraph 1 or 2 | 991+----------------+--------------------------------------------------------------------+ 992|z_c |Zc, LDPC lifting size | 993+----------------+--------------------------------------------------------------------+ 994|n_cb |Ncb, length of the circular buffer in bits. | 995+----------------+--------------------------------------------------------------------+ 996|q_m |Qm, modulation order {1,2,4,6,8} from pi/2-BPSK to 256QAM | 997+----------------+--------------------------------------------------------------------+ 998|n_filler |number of filler bits | 999+----------------+--------------------------------------------------------------------+ 1000|iter_max |maximum number of iterations to perform in decode all CBs | 1001+----------------+--------------------------------------------------------------------+ 1002|iter_count |number of iterations performed in decoding all CBs | 1003+----------------+--------------------------------------------------------------------+ 1004|code_block_mode |code block or transport block mode | 1005+----------------+--------------------------------------------------------------------+ 1006|op_flags |bitmask of all active operation capabilities | 1007+----------------+--------------------------------------------------------------------+ 1008|**cb_params** |code block specific parameters (code block mode only) | 1009+----------------+------------+-------------------------------------------------------+ 1010| |e |E, length of the rate matched output sequence in bits | 1011+----------------+------------+-------------------------------------------------------+ 1012|**tb_params** | transport block specific parameters (transport block mode only) | 1013+----------------+------------+-------------------------------------------------------+ 1014| |c |number of CBs in the TB or partial TB | 1015+----------------+------------+-------------------------------------------------------+ 1016| |r |index of the first CB in the inbound mbuf data | 1017+----------------+------------+-------------------------------------------------------+ 1018| |c_ab |number of CBs that use Ea before switching to Eb | 1019+----------------+------------+-------------------------------------------------------+ 1020| |ea |Ea, length of the RM output sequence in bits, r < cab | 1021+----------------+------------+-------------------------------------------------------+ 1022| |eb |Eb, length of the RM output sequence in bits r >= cab | 1023+----------------+------------+-------------------------------------------------------+ 1024 1025The mbuf input ``input`` encoded CB data is mandatory for all BBDEV PMDs 1026and is the Virtual Circular Buffer data stream with null padding. 1027Each byte in the input circular buffer is the LLR value of each bit of 1028the original CB. 1029 1030The mbuf output ``hard_output`` is mandatory and is the decoded CBs size 1031K (CRC24A/B is the last 24-bit in each decoded CB). 1032 1033The mbuf output ``soft_output`` is optional and is an LLR rate matched 1034output of size ``e`` (this is ``E`` as per 3GPP TS 38.212 section 6.2.5). 1035 1036The mbuf input ``harq_combine_input`` is optional and is a buffer with 1037the input to the HARQ combination function of the device. If the 1038capability RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_IN_ENABLE is set 1039then the HARQ is stored in memory internal to the device and not visible 1040to BBDEV. 1041 1042The mbuf output ``harq_combine_output`` is optional and is a buffer for 1043the output of the HARQ combination function of the device. If the 1044capability RTE_BBDEV_LDPC_INTERNAL_HARQ_MEMORY_OUT_ENABLE is set 1045then the HARQ is stored in memory internal to the device and not visible 1046to BBDEV. 1047 1048.. note:: 1049 1050 More explicitly for a typical usage of HARQ retransmission 1051 in a VRAN application using a HW PMD, there will be 2 cases. 1052 1053 For 1st transmission, only the HARQ output is enabled: 1054 1055 - the harq_combined_output.offset is provided to a given address. 1056 ie. typically an integer index * 32K, 1057 where the index is tracked by the application based on code block index 1058 for a given UE and HARQ process. 1059 1060 - the related operation flag would notably include 1061 RTE_BBDEV_LDPC_HQ_COMBINE_OUT_ENABLE and RTE_BBDEV_LDPC_HARQ_6BIT_COMPRESSION. 1062 1063 - note that no explicit flush or reset of the memory is required. 1064 1065 For 2nd transmission, an input is also required to benefit from HARQ combination gain: 1066 1067 - the changes mentioned above are the same (note that rvIndex may be adjusted). 1068 1069 - the operation flag would additionally include the LDPC_HQ_COMBINE_IN_ENABLE flag. 1070 1071 - the harq_combined_input.offset must be set to the address of the related code block 1072 (ie. same as the harq_combine_output index above for the same code block, HARQ process, UE). 1073 1074 - the harq_combined_input.length must be set to the length 1075 which was provided back in the related harq_combined_output.length 1076 when it has processed and dequeued (previous HARQ iteration). 1077 1078 1079The output mbuf data structures are expected to be allocated by the 1080application with enough room for the output data. 1081 1082As with the LDPC encode, the decode interface works on both a code block 1083(CB) and a transport block (TB) basis. 1084 1085 **NOTE:** All enqueued ops in one ``rte_bbdev_enqueue_dec_ops()`` 1086 call belong to one mode, either CB-mode or TB-mode. 1087 1088The valid modes of operation are: 1089 1090* CB-mode: one CB (check CRC24B if required) 1091* CB-mode: one CB making up one TB (check CRC24A if required) 1092* TB-mode: one or more CB making up a partial TB (check CRC24B(s) if required) 1093* TB-mode: one or more CB making up a complete TB (check CRC24B(s) if required) 1094 1095The mbuf ``length`` is inclusive of CRC24A/B where present and is equal 1096the code block size ``K``. 1097 1098The first CB Virtual Circular Buffer (VCB) index is given by ``r`` but the 1099number of the remaining CB VCBs is calculated automatically by BBDEV 1100and passed down to the driver. 1101 1102The number of remaining CB VCBs should not be confused with ``c``, the 1103total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2) 1104 1105The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in 1106case they were appended by the application. 1107 1108Figure :numref:`figure_turbo_tb_decode` above 1109showing the Turbo decoding of CBs using BBDEV interface in TB-mode 1110is also valid for LDPC decode. 1111 1112BBDEV FFT Operation 1113~~~~~~~~~~~~~~~~~~~ 1114 1115This operation allows to run a combination of DFT and/or IDFT and/or time-domain windowing. 1116These can be used in a modular fashion (using bypass modes) or as a processing pipeline 1117which can be used for FFT-based baseband signal processing. 1118 1119In more details it allows : 1120 1121* to process the data first through an IDFT of adjustable size and padding; 1122* to perform the windowing as a programmable cyclic shift offset of the data 1123 followed by a pointwise multiplication by a time domain window; 1124* to process the related data through a DFT of adjustable size and 1125 de-padding for each such cyclic shift output. 1126 1127A flexible number of Rx antennas are being processed in parallel with the same configuration. 1128The API allows more generally for flexibility in what the PMD may support (capability flags) and 1129flexibility to adjust some of the parameters of the processing. 1130 1131The structure passed for each FFT operation is given below, 1132with the operation flags forming a bitmask in the ``op_flags`` field. 1133 1134 **NOTE:** The actual operation flags that may be used with a specific 1135 bbdev PMD are dependent on the driver capabilities as reported via 1136 ``rte_bbdev_info_get()``, and may be a subset of those below. 1137 1138.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h 1139 :language: c 1140 :start-after: Structure rte_bbdev_op_fft 8< 1141 :end-before: >8 End of structure rte_bbdev_op_fft. 1142 1143+--------------------------------------------------------------------+ 1144|Description of FFT capability flags | 1145+====================================================================+ 1146|RTE_BBDEV_FFT_WINDOWING | 1147| Set to enable/support windowing in time domain | 1148+--------------------------------------------------------------------+ 1149|RTE_BBDEV_FFT_CS_ADJUSTMENT | 1150| Set to enable/support the cyclic shift time offset adjustment | 1151+--------------------------------------------------------------------+ 1152|RTE_BBDEV_FFT_DFT_BYPASS | 1153| Set to bypass the DFT and use directly the IDFT as an option | 1154+--------------------------------------------------------------------+ 1155|RTE_BBDEV_FFT_IDFT_BYPASS | 1156| Set to bypass the IDFT and use directly the DFT as an option | 1157+--------------------------------------------------------------------+ 1158|RTE_BBDEV_FFT_WINDOWING_BYPASS | 1159| Set to bypass the time domain windowing as an option | 1160+--------------------------------------------------------------------+ 1161|RTE_BBDEV_FFT_POWER_MEAS | 1162| Set to provide an optional power measurement of the DFT output | 1163+--------------------------------------------------------------------+ 1164|RTE_BBDEV_FFT_FP16_INPUT | 1165| Set if the input data shall use FP16 format instead of INT16 | 1166+--------------------------------------------------------------------+ 1167|RTE_BBDEV_FFT_FP16_OUTPUT | 1168| Set if the output data shall use FP16 format instead of INT16 | 1169+--------------------------------------------------------------------+ 1170|RTE_BBDEV_FFT_TIMING_OFFSET_PER_CS | 1171| Set if device supports adjusting time offset per CS | 1172+--------------------------------------------------------------------+ 1173|RTE_BBDEV_FFT_TIMING_ERROR | 1174| Set if device supports correcting for timing error | 1175+--------------------------------------------------------------------+ 1176|RTE_BBDEV_FFT_DEWINDOWING | 1177| Set if enabling the option FFT Dewindowing in Frequency domain | 1178+--------------------------------------------------------------------+ 1179|RTE_BBDEV_FFT_FREQ_RESAMPLING | 1180| Set if device supports the optional frequency resampling | 1181+--------------------------------------------------------------------+ 1182 1183The FFT parameters are set out in the table below. 1184 1185+-------------------------+--------------------------------------------------------------+ 1186|Parameter |Description | 1187+=========================+==============================================================+ 1188|base_input |input data | 1189+-------------------------+--------------------------------------------------------------+ 1190|base_output |output data | 1191+-------------------------+--------------------------------------------------------------+ 1192|dewindowing_input |optional frequency domain dewindowing input data | 1193+-------------------------+--------------------------------------------------------------+ 1194|power_meas_output |optional output data with power measurement on DFT output | 1195+-------------------------+--------------------------------------------------------------+ 1196|op_flags |bitmask of all active operation capabilities | 1197+-------------------------+--------------------------------------------------------------+ 1198|input_sequence_size |size of the input sequence in 32-bits points per antenna | 1199+-------------------------+--------------------------------------------------------------+ 1200|input_leading_padding |number of points padded at the start of input data | 1201+-------------------------+--------------------------------------------------------------+ 1202|output_sequence_size |size of the output sequence per antenna and cyclic shift | 1203+-------------------------+--------------------------------------------------------------+ 1204|output_leading_depadding |number of points de-padded at the start of output data | 1205+-------------------------+--------------------------------------------------------------+ 1206|window_index |optional windowing profile index used for each cyclic shift | 1207+-------------------------+--------------------------------------------------------------+ 1208|cs_bitmap |bitmap of the cyclic shift output requested (LSB for index 0) | 1209+-------------------------+--------------------------------------------------------------+ 1210|num_antennas_log2 |number of antennas as a log2 (10 maps to 1024...) | 1211+-------------------------+--------------------------------------------------------------+ 1212|idft_log2 |IDFT size as a log2 | 1213+-------------------------+--------------------------------------------------------------+ 1214|dft_log2 |DFT size as a log2 | 1215+-------------------------+--------------------------------------------------------------+ 1216|cs_time_adjustment |adjustment of time position of all the cyclic shift output | 1217+-------------------------+--------------------------------------------------------------+ 1218|idft_shift |shift down of signal level post iDFT | 1219+-------------------------+--------------------------------------------------------------+ 1220|dft_shift |shift down of signal level post DFT | 1221+-------------------------+--------------------------------------------------------------+ 1222|ncs_reciprocal |inverse of max number of CS normalized to 15b (ie. 231 for 12)| 1223+-------------------------+--------------------------------------------------------------+ 1224|power_shift |shift down of level of power measurement when enabled | 1225+-------------------------+--------------------------------------------------------------+ 1226|fp16_exp_adjust |value added to FP16 exponent at conversion from INT16 | 1227+-------------------------+--------------------------------------------------------------+ 1228|freq_resample_mode |frequency ressampling mode (0:transparent, 1-2: resample) | 1229+-------------------------+--------------------------------------------------------------+ 1230| output_depadded_size |output depadded size prior to frequency resampling | 1231+-------------------------+--------------------------------------------------------------+ 1232|cs_theta_0 |timing error correction initial phase | 1233+-------------------------+--------------------------------------------------------------+ 1234|cs_theta_d |timing error correction phase increment | 1235+-------------------------+--------------------------------------------------------------+ 1236|time_offset |time offset per CS of time domain samples | 1237+-------------------------+--------------------------------------------------------------+ 1238 1239The mbuf input ``base_input`` is mandatory for all bbdev PMDs and 1240is the incoming data for the processing. Its size may not fit into an actual mbuf, 1241but the structure is used to pass iova address. 1242The mbuf output ``output`` is mandatory and is output of the FFT processing chain. 1243Each point is a complex number of 32bits : 1244either as 2 INT16 or as 2 FP16 based when the option supported. 1245The data layout is based on contiguous concatenation of output data 1246first by cyclic shift then by antenna. 1247 1248BBDEV MLD-TS Operation 1249~~~~~~~~~~~~~~~~~~~~~~ 1250 1251This operation allows to run the Tree Search (TS) portion of a Maximum Likelihood processing (MLD). 1252 1253This alternate equalization option accelerates the exploration of the best combination of 1254transmitted symbols across layers minimizing the Euclidean distance between the received and 1255reconstructed signal, then generates the LLRs to be used by the LDPC Decoder. 1256The input is the results of the Q R decomposition: Q^Hy signal and R matrix. 1257 1258The structure passed for each MLD-TS operation is given below, 1259with the operation flags forming a bitmask in the ``op_flags`` field. 1260 1261 **NOTE:** The actual operation flags that may be used with a specific 1262 bbdev PMD are dependent on the driver capabilities as reported via 1263 ``rte_bbdev_info_get()``, and may be a subset of those below. 1264 1265.. literalinclude:: ../../../lib/bbdev/rte_bbdev_op.h 1266 :language: c 1267 :start-after: Structure rte_bbdev_op_mldts 8< 1268 :end-before: >8 End of structure rte_bbdev_op_mldts. 1269 1270+--------------------------------------------------------------------+ 1271|Description of MLD-TS capability flags | 1272+====================================================================+ 1273|RTE_BBDEV_MLDTS_REP | 1274| Set if the option to use repeated data from R channel is supported | 1275+--------------------------------------------------------------------+ 1276 1277The MLD-TS parameters are set out in the table below. 1278 1279+-------------------------+--------------------------------------------------------------+ 1280|Parameter |Description | 1281+=========================+==============================================================+ 1282|qhy_input |input data qHy | 1283+-------------------------+--------------------------------------------------------------+ 1284|r_input |input data R triangular matrix | 1285+-------------------------+--------------------------------------------------------------+ 1286|output |output data (LLRs) | 1287+-------------------------+--------------------------------------------------------------+ 1288|op_flags |bitmask of all active operation capabilities | 1289+-------------------------+--------------------------------------------------------------+ 1290|num_rbs |number of Resource Blocks | 1291+-------------------------+--------------------------------------------------------------+ 1292|num_layers |number of overlapping layers | 1293+-------------------------+--------------------------------------------------------------+ 1294|q_m |array of modulation order for each layer | 1295+-------------------------+--------------------------------------------------------------+ 1296|r_rep |optional row repetition for the R matrix (subcarriers) | 1297+-------------------------+--------------------------------------------------------------+ 1298|c_rep |optional column repetition for the R matrix (symbols) | 1299+-------------------------+--------------------------------------------------------------+ 1300 1301Sample code 1302----------- 1303 1304The baseband device sample application gives an introduction on how to use the 1305bbdev framework, by giving a sample code performing a loop-back operation with a 1306baseband processor capable of transceiving data packets. 1307 1308The following sample C-like pseudo-code shows the basic steps to encode several 1309buffers using (**sw_turbo**) bbdev PMD. 1310 1311.. code-block:: c 1312 1313 /* EAL Init */ 1314 ret = rte_eal_init(argc, argv); 1315 if (ret < 0) 1316 rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n"); 1317 1318 /* Get number of available bbdev devices */ 1319 nb_bbdevs = rte_bbdev_count(); 1320 if (nb_bbdevs == 0) 1321 rte_exit(EXIT_FAILURE, "No bbdevs detected!\n"); 1322 1323 /* Create bbdev op pools */ 1324 bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC] = 1325 rte_bbdev_op_pool_create("bbdev_op_pool_enc", 1326 RTE_BBDEV_OP_TURBO_ENC, NB_MBUF, 128, rte_socket_id()); 1327 1328 /* Get information for this device */ 1329 rte_bbdev_info_get(dev_id, &info); 1330 1331 /* Setup BBDEV device queues */ 1332 ret = rte_bbdev_setup_queues(dev_id, qs_nb, info.socket_id); 1333 if (ret < 0) 1334 rte_exit(EXIT_FAILURE, 1335 "ERROR(%d): BBDEV %u not configured properly\n", 1336 ret, dev_id); 1337 1338 /* setup device queues */ 1339 qconf.socket = info.socket_id; 1340 qconf.queue_size = info.drv.queue_size_lim; 1341 qconf.op_type = RTE_BBDEV_OP_TURBO_ENC; 1342 1343 for (q_id = 0; q_id < qs_nb; q_id++) { 1344 /* Configure all queues belonging to this bbdev device */ 1345 ret = rte_bbdev_queue_configure(dev_id, q_id, &qconf); 1346 if (ret < 0) 1347 rte_exit(EXIT_FAILURE, 1348 "ERROR(%d): BBDEV %u queue %u not configured properly\n", 1349 ret, dev_id, q_id); 1350 } 1351 1352 /* Start bbdev device */ 1353 ret = rte_bbdev_start(dev_id); 1354 1355 /* Create the mbuf mempool for pkts */ 1356 mbuf_pool = rte_pktmbuf_pool_create("bbdev_mbuf_pool", 1357 NB_MBUF, MEMPOOL_CACHE_SIZE, 0, 1358 RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id()); 1359 if (mbuf_pool == NULL) 1360 rte_exit(EXIT_FAILURE, 1361 "Unable to create '%s' pool\n", pool_name); 1362 1363 while (!global_exit_flag) { 1364 1365 /* Allocate burst of op structures in preparation for enqueue */ 1366 if (rte_bbdev_enc_op_alloc_bulk(bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC], 1367 ops_burst, op_num) != 0) 1368 continue; 1369 1370 /* Allocate input mbuf pkts */ 1371 ret = rte_pktmbuf_alloc_bulk(mbuf_pool, input_pkts_burst, MAX_PKT_BURST); 1372 if (ret < 0) 1373 continue; 1374 1375 /* Allocate output mbuf pkts */ 1376 ret = rte_pktmbuf_alloc_bulk(mbuf_pool, output_pkts_burst, MAX_PKT_BURST); 1377 if (ret < 0) 1378 continue; 1379 1380 for (j = 0; j < op_num; j++) { 1381 /* Append the size of the ethernet header */ 1382 rte_pktmbuf_append(input_pkts_burst[j], 1383 sizeof(struct rte_ether_hdr)); 1384 1385 /* set op */ 1386 1387 ops_burst[j]->turbo_enc.input.offset = 1388 sizeof(struct rte_ether_hdr); 1389 1390 ops_burst[j]->turbo_enc->input.length = 1391 rte_pktmbuf_pkt_len(bbdev_pkts[j]); 1392 1393 ops_burst[j]->turbo_enc->input.data = 1394 input_pkts_burst[j]; 1395 1396 ops_burst[j]->turbo_enc->output.offset = 1397 sizeof(struct rte_ether_hdr); 1398 1399 ops_burst[j]->turbo_enc->output.data = 1400 output_pkts_burst[j]; 1401 } 1402 1403 /* Enqueue packets on BBDEV device */ 1404 op_num = rte_bbdev_enqueue_enc_ops(qconf->bbdev_id, 1405 qconf->bbdev_qs[q], ops_burst, 1406 MAX_PKT_BURST); 1407 1408 /* Dequeue packets from BBDEV device*/ 1409 op_num = rte_bbdev_dequeue_enc_ops(qconf->bbdev_id, 1410 qconf->bbdev_qs[q], ops_burst, 1411 MAX_PKT_BURST); 1412 } 1413 1414 1415BBDEV Device API 1416~~~~~~~~~~~~~~~~ 1417 1418The bbdev Library API is described in the *DPDK API Reference* document. 1419