doc: add graphics to bbdev guide
[dpdk.git] / 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 Our 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 initializations 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 device Library as the Poll Mode Driver library support NUMA for when
170 a processor's logical cores and interfaces utilize its local memory. Therefore
171 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_MAX_CODE_BLOCKS,
224                 .num_buffers_hard_out =
225                         RTE_BBDEV_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_MAX_CODE_BLOCKS,
238                 .num_buffers_dst = RTE_BBDEV_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_bus *bus;
270         uint16_t num_queues;
271         bool started;
272         struct rte_bbdev_driver_info drv;
273     };
274
275 Operation Processing
276 --------------------
277
278 Scheduling of baseband operations on DPDK's application data path is
279 performed using a burst oriented asynchronous API set. A queue on a bbdev
280 device accepts a burst of baseband operations using enqueue burst API. On physical
281 bbdev devices the enqueue burst API will place the operations to be processed
282 on the device's hardware input queue, for virtual devices the processing of the
283 baseband operations is usually completed during the enqueue call to the bbdev
284 device. The dequeue burst API will retrieve any processed operations available
285 from the queue on the bbdev device, from physical devices this is usually
286 directly from the device's processed queue, and for virtual device's from a
287 ``rte_ring`` where processed operations are place after being processed on the
288 enqueue call.
289
290
291 Enqueue / Dequeue Burst APIs
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293
294 The burst enqueue API uses a bbdev device identifier and a queue
295 identifier to specify the bbdev device queue to schedule the processing on.
296 The ``num_ops`` parameter is the number of operations to process which are
297 supplied in the ``ops`` array of ``rte_bbdev_*_op`` structures.
298 The enqueue function returns the number of operations it actually enqueued for
299 processing, a return value equal to ``num_ops`` means that all packets have been
300 enqueued.
301
302 .. code-block:: c
303
304     uint16_t rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
305             struct rte_bbdev_enc_op **ops, uint16_t num_ops)
306
307     uint16_t rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
308             struct rte_bbdev_dec_op **ops, uint16_t num_ops)
309
310 The dequeue API uses the same format as the enqueue API of processed but
311 the ``num_ops`` and ``ops`` parameters are now used to specify the max processed
312 operations the user wishes to retrieve and the location in which to store them.
313 The API call returns the actual number of processed operations returned, this
314 can never be larger than ``num_ops``.
315
316 .. code-block:: c
317
318     uint16_t rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
319             struct rte_bbdev_enc_op **ops, uint16_t num_ops)
320
321     uint16_t rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
322             struct rte_bbdev_dec_op **ops, uint16_t num_ops)
323
324 Operation Representation
325 ~~~~~~~~~~~~~~~~~~~~~~~~
326
327 An encode bbdev operation is represented by ``rte_bbdev_enc_op`` structure,
328 and by ``rte_bbdev_dec_op`` for decode. These structures act as metadata
329 containers for all necessary information required for the bbdev operation to be
330 processed on a particular bbdev device poll mode driver.
331
332 .. code-block:: c
333
334     struct rte_bbdev_enc_op {
335         int status;
336         struct rte_mempool *mempool;
337         void *opaque_data;
338         struct rte_bbdev_op_turbo_enc turbo_enc;
339     };
340
341     struct rte_bbdev_dec_op {
342         int status;
343         struct rte_mempool *mempool;
344         void *opaque_data;
345         struct rte_bbdev_op_turbo_dec turbo_dec;
346     };
347
348 The operation structure by itself defines the operation type. It includes an
349 operation status, a reference to the operation specific data, which can vary in
350 size and content depending on the operation being provisioned. It also contains
351 the source mempool for the operation, if it is allocated from a mempool.
352
353 If bbdev operations are allocated from a bbdev operation mempool, see next
354 section, there is also the ability to allocate private memory with the
355 operation for applications purposes.
356
357 Application software is responsible for specifying all the operation specific
358 fields in the ``rte_bbdev_*_op`` structure which are then used by the bbdev PMD
359 to process the requested operation.
360
361
362 Operation Management and Allocation
363 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
364
365 The bbdev library provides an API set for managing bbdev operations which
366 utilize the Mempool Library to allocate operation buffers. Therefore, it ensures
367 that the bbdev operation is interleaved optimally across the channels and
368 ranks for optimal processing.
369
370 .. code-block:: c
371
372     struct rte_mempool *
373     rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
374             unsigned int num_elements, unsigned int cache_size,
375             int socket_id)
376
377 ``rte_bbdev_*_op_alloc_bulk()`` and ``rte_bbdev_*_op_free_bulk()`` are used to
378 allocate bbdev operations of a specific type from a given bbdev operation mempool.
379
380 .. code-block:: c
381
382     int rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
383             struct rte_bbdev_enc_op **ops, uint16_t num_ops)
384
385     int rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
386             struct rte_bbdev_dec_op **ops, uint16_t num_ops)
387
388 ``rte_bbdev_*_op_free_bulk()`` is called by the application to return an
389 operation to its allocating pool.
390
391 .. code-block:: c
392
393     void rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops,
394             unsigned int num_ops)
395     void rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops,
396             unsigned int num_ops)
397
398 BBDEV Inbound/Outbound Memory
399 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
400
401 The bbdev operation structure contains all the mutable data relating to
402 performing Turbo coding on a referenced mbuf data buffer. It is used for either
403 encode or decode operations.
404
405 Turbo Encode operation accepts one input and one output.
406 Turbo Decode operation accepts one input and two outputs, called *hard-decision*
407 and *soft-decision* outputs. *Soft-decision* output is optional.
408
409 It is expected that the application provides input and output mbuf pointers
410 allocated and ready to use. The baseband framework supports turbo coding on
411 Code Blocks (CB) and Transport Blocks (TB).
412
413 For the output buffer(s), the application is required to provide an allocated
414 and free mbuf, so that bbdev write back the resulting output.
415
416 The support of split "scattered" buffers is a driver-specific feature, so it is
417 reported individually by the supporting driver as a capability.
418
419 Input and output data buffers are identified by ``rte_bbdev_op_data`` structure,
420 as follows:
421
422 .. code-block:: c
423
424     struct rte_bbdev_op_data {
425         struct rte_mbuf *data;
426         uint32_t offset;
427         uint32_t length;
428     };
429
430
431 This structure has three elements:
432
433 - ``data``: This is the mbuf data structure representing the data for BBDEV
434   operation.
435
436   This mbuf pointer can point to one Code Block (CB) data buffer or multiple CBs
437   contiguously located next to each other. A Transport Block (TB) represents a
438   whole piece of data that is divided into one or more CBs. Maximum number of
439   CBs can be contained in one TB is defined by ``RTE_BBDEV_MAX_CODE_BLOCKS``.
440
441   An mbuf data structure cannot represent more than one TB. The smallest piece
442   of data that can be contained in one mbuf is one CB.
443   An mbuf can include one contiguous CB, subset of contiguous CBs that are
444   belonging to one TB, or all contiguous CBs that are belonging to one TB.
445
446   If a BBDEV PMD supports the extended capability "Scatter-Gather", then it is
447   capable of collecting (gathering) non-contiguous (scattered) data from
448   multiple locations in the memory.
449   This capability is reported by the capability flags:
450
451   - ``RTE_BBDEV_TURBO_ENC_SCATTER_GATHER``, and
452
453   - ``RTE_BBDEV_TURBO_DEC_SCATTER_GATHER``.
454
455   Only if a BBDEV PMD supports this feature, chained mbuf data structures are
456   accepted. A chained mbuf can represent one non-contiguous CB or multiple
457   non-contiguous CBs.
458   The first mbuf segment in the given chained mbuf represents the first piece
459   of the CB. Offset is only applicable to the first segment. ``length`` is the
460   total length of the CB.
461
462   BBDEV driver is responsible for identifying where the split is and enqueue
463   the split data to its internal queues.
464
465   If BBDEV PMD does not support this feature, it will assume inbound mbuf data
466   contains one segment.
467
468   The output mbuf data though is always one segment, even if the input was a
469   chained mbuf.
470
471
472 - ``offset``: This is the starting point of the BBDEV (encode/decode) operation,
473   in bytes.
474
475   BBDEV starts to read data past this offset.
476   In case of chained mbuf, this offset applies only to the first mbuf segment.
477
478
479 - ``length``: This is the total data length to be processed in one operation,
480   in bytes.
481
482   In case the mbuf data is representing one CB, this is the length of the CB
483   undergoing the operation.
484   If it is for multiple CBs, this is the total length of those CBs undergoing
485   the operation.
486   If it is for one TB, this is the total length of the TB under operation.
487   In case of chained mbuf, this data length includes the lengths of the
488   "scattered" data segments undergoing the operation.
489
490
491 BBDEV Turbo Encode Operation
492 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
493
494 .. code-block:: c
495
496     struct rte_bbdev_op_turbo_enc {
497         struct rte_bbdev_op_data input;
498         struct rte_bbdev_op_data output;
499
500         uint32_t op_flags;
501         uint8_t rv_index;
502         uint8_t code_block_mode;
503         union {
504             struct rte_bbdev_op_enc_cb_params cb_params;
505             struct rte_bbdev_op_enc_tb_params tb_params;
506         };
507     };
508
509 The Turbo encode structure is composed of the ``input`` and ``output`` mbuf
510 data pointers. The provided mbuf pointer of ``input`` needs to be big enough to
511 stretch for extra CRC trailers.
512
513 ``op_flags`` parameter holds all operation related flags, like whether CRC24A is
514 included by the application or not.
515
516 ``code_block_mode`` flag identifies the mode in which bbdev is operating in.
517
518 The encode interface works on both the code block (CB) and the transport block
519 (TB). An operation executes in "CB-mode" when the CB is standalone. While
520 "TB-mode" executes when an operation performs on one or multiple CBs that
521 belong to a TB. Therefore, a given data can be standalone CB, full-size TB or
522 partial TB. Partial TB means that only a subset of CBs belonging to a bigger TB
523 are being enqueued.
524
525   **NOTE:** It is assumed that all enqueued ops in one ``rte_bbdev_enqueue_enc_ops()``
526   call belong to one mode, either CB-mode or TB-mode.
527
528 In case that the CB is smaller than Z (6144 bits), then effectively the TB = CB.
529 CRC24A is appended to the tail of the CB. The application is responsible for
530 calculating and appending CRC24A before calling BBDEV in case that the
531 underlying driver does not support CRC24A generation.
532
533 In CB-mode, CRC24A/B is an optional operation.
534 The input ``k`` is the size of the CB (this maps to K as described in 3GPP TS
535 36.212 section 5.1.2), this size is inclusive of CRC24A/B.
536 The ``length`` is inclusive of CRC24A/B and equals to ``k`` in this case.
537
538 Not all BBDEV PMDs are capable of CRC24A/B calculation. Flags
539 ``RTE_BBDEV_TURBO_CRC_24A_ATTACH`` and ``RTE_BBDEV_TURBO_CRC_24B_ATTACH``
540 informs the application with relevant capability. These flags can be set in the
541 ``op_flags`` parameter to indicate BBDEV to calculate and append CRC24A to CB
542 before going forward with Turbo encoding.
543
544 Output format of the CB encode will have the encoded CB in ``e`` size output
545 (this maps to E described in 3GPP TS 36.212 section 5.1.4.1.2). The output mbuf
546 buffer size needs to be big enough to hold the encoded buffer of size ``e``.
547
548 In TB-mode, CRC24A is assumed to be pre-calculated and appended to the inbound
549 TB mbuf data buffer.
550 The output mbuf data structure is expected to be allocated by the application
551 with enough room for the output data.
552
553 The difference between the partial and full-size TB is that we need to know the
554 index of the first CB in this group and the number of CBs contained within.
555 The first CB index is given by ``r`` but the number of the remaining CBs is
556 calculated automatically by BBDEV before passing down to the driver.
557
558 The number of remaining CBs should not be confused with ``c``. ``c`` is the
559 total number of CBs that composes the whole TB (this maps to C as
560 described in 3GPP TS 36.212 section 5.1.2).
561
562 The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in
563 case they were appended by the application.
564
565 The case when one CB belongs to TB and is being enqueued individually to BBDEV,
566 this case is considered as a special case of partial TB where its number of CBs
567 is 1. Therefore, it requires to get processed in TB-mode.
568
569 The figure below visualizes the encoding of CBs using BBDEV interface in
570 TB-mode. CB-mode is a reduced version, where only one CB exists:
571
572 .. _figure_turbo_tb_encode:
573
574 .. figure:: img/turbo_tb_encode.svg
575
576     Turbo encoding of Code Blocks in mbuf structure
577
578
579 BBDEV Turbo Decode Operation
580 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
581
582 .. code-block:: c
583
584     struct rte_bbdev_op_turbo_dec {
585         struct rte_bbdev_op_data input;
586         struct rte_bbdev_op_data hard_output;
587         struct rte_bbdev_op_data soft_output;
588
589         uint32_t op_flags;
590         uint8_t rv_index;
591         uint8_t iter_min:4;
592         uint8_t iter_max:4;
593         uint8_t iter_count;
594         uint8_t ext_scale;
595         uint8_t num_maps;
596         uint8_t code_block_mode;
597         union {
598             struct rte_bbdev_op_dec_cb_params cb_params;
599             struct rte_bbdev_op_dec_tb_params tb_params;
600         };
601     };
602
603 The Turbo decode structure is composed of the ``input`` and ``output`` mbuf
604 data pointers.
605
606 ``op_flags`` parameter holds all operation related flags, like whether CRC24B is
607 retained or not.
608
609 ``code_block_mode`` flag identifies the mode in which bbdev is operating in.
610
611 Similarly, the decode interface works on both the code block (CB) and the
612 transport block (TB). An operation executes in "CB-mode" when the CB is
613 standalone. While "TB-mode" executes when an operation performs on one or
614 multiple CBs that belong to a TB. Therefore, a given data can be standalone CB,
615 full-size TB or partial TB. Partial TB means that only a subset of CBs belonging
616 to a bigger TB are being enqueued.
617
618   **NOTE:** It is assumed that all enqueued ops in one ``rte_bbdev_enqueue_dec_ops()``
619   call belong to one mode, either CB-mode or TB-mode.
620
621 The input ``k`` is the size of the decoded CB (this maps to K as described in
622 3GPP TS 36.212 section 5.1.2), this size is inclusive of CRC24A/B.
623 The ``length`` is inclusive of CRC24A/B and equals to ``k`` in this case.
624
625 The input encoded CB data is the Virtual Circular Buffer data stream, wk, with
626 the null padding included as described in 3GPP TS 36.212 section 5.1.4.1.2 and
627 shown in 3GPP TS 36.212 section 5.1.4.1 Figure 5.1.4-1.
628 The size of the virtual circular buffer is 3*Kpi, where Kpi is the 32 byte
629 aligned value of K, as specified in 3GPP TS 36.212 section 5.1.4.1.1.
630
631 Each byte in the input circular buffer is the LLR value of each bit of the
632 original CB.
633
634 ``hard_output`` is a mandatory capability that all BBDEV PMDs support. This is
635 the decoded CBs of K sizes (CRC24A/B is the last 24-bit in each decoded CB).
636 Soft output is an optional capability for BBDEV PMDs. Setting flag
637 ``RTE_BBDEV_TURBO_DEC_TB_CRC_24B_KEEP`` in ``op_flags`` directs BBDEV to retain
638 CRC24B at the end of each CB. This might be useful for the application in debug
639 mode.
640 An LLR rate matched output is computed in the ``soft_output`` buffer structure
641 for the given ``e`` size (this maps to E described in 3GPP TS 36.212 section
642 5.1.4.1.2). The output mbuf buffer size needs to be big enough to hold the
643 encoded buffer of size ``e``.
644
645 The first CB Virtual Circular Buffer (VCB) index is given by ``r`` but the
646 number of the remaining CB VCBs is calculated automatically by BBDEV before
647 passing down to the driver.
648
649 The number of remaining CB VCBs should not be confused with ``c``. ``c`` is the
650 total number of CBs that composes the whole TB (this maps to C as
651 described in 3GPP TS 36.212 section 5.1.2).
652
653 The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in
654 case they were appended by the application.
655
656 The case when one CB belongs to TB and is being enqueued individually to BBDEV,
657 this case is considered as a special case of partial TB where its number of CBs
658 is 1. Therefore, it requires to get processed in TB-mode.
659
660 The output mbuf data structure is expected to be allocated by the application
661 with enough room for the output data.
662
663 The figure below visualizes the decoding of CBs using BBDEV interface in
664 TB-mode. CB-mode is a reduced version, where only one CB exists:
665
666 .. _figure_turbo_tb_decode:
667
668 .. figure:: img/turbo_tb_decode.svg
669
670     Turbo decoding of Code Blocks in mbuf structure
671
672
673 Sample code
674 -----------
675
676 The baseband device sample application gives an introduction on how to use the
677 bbdev framework, by giving a sample code performing a loop-back operation with a
678 baseband processor capable of transceiving data packets.
679
680 The following sample C-like pseudo-code shows the basic steps to encode several
681 buffers using (**sw_trubo**) bbdev PMD.
682
683 .. code-block:: c
684
685     /* EAL Init */
686     ret = rte_eal_init(argc, argv);
687     if (ret < 0)
688         rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n");
689
690     /* Get number of available bbdev devices */
691     nb_bbdevs = rte_bbdev_count();
692     if (nb_bbdevs == 0)
693         rte_exit(EXIT_FAILURE, "No bbdevs detected!\n");
694
695     /* Create bbdev op pools */
696     bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC] =
697             rte_bbdev_op_pool_create("bbdev_op_pool_enc",
698             RTE_BBDEV_OP_TURBO_ENC, NB_MBUF, 128, rte_socket_id());
699
700     /* Get information for this device */
701     rte_bbdev_info_get(dev_id, &info);
702
703     /* Setup BBDEV device queues */
704     ret = rte_bbdev_setup_queues(dev_id, qs_nb, info.socket_id);
705     if (ret < 0)
706         rte_exit(EXIT_FAILURE,
707                 "ERROR(%d): BBDEV %u not configured properly\n",
708                 ret, dev_id);
709
710     /* setup device queues */
711     qconf.socket = info.socket_id;
712     qconf.queue_size = info.drv.queue_size_lim;
713     qconf.op_type = RTE_BBDEV_OP_TURBO_ENC;
714
715     for (q_id = 0; q_id < qs_nb; q_id++) {
716         /* Configure all queues belonging to this bbdev device */
717         ret = rte_bbdev_queue_configure(dev_id, q_id, &qconf);
718         if (ret < 0)
719             rte_exit(EXIT_FAILURE,
720                     "ERROR(%d): BBDEV %u queue %u not configured properly\n",
721                     ret, dev_id, q_id);
722     }
723
724     /* Start bbdev device */
725     ret = rte_bbdev_start(dev_id);
726
727     /* Create the mbuf mempool for pkts */
728     mbuf_pool = rte_pktmbuf_pool_create("bbdev_mbuf_pool",
729             NB_MBUF, MEMPOOL_CACHE_SIZE, 0,
730             RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id());
731     if (mbuf_pool == NULL)
732         rte_exit(EXIT_FAILURE,
733                 "Unable to create '%s' pool\n", pool_name);
734
735     while (!global_exit_flag) {
736
737         /* Allocate burst of op structures in preparation for enqueue */
738         if (rte_bbdev_enc_op_alloc_bulk(bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC],
739             ops_burst, op_num) != 0)
740             continue;
741
742         /* Allocate input mbuf pkts */
743         ret = rte_pktmbuf_alloc_bulk(mbuf_pool, input_pkts_burst, MAX_PKT_BURST);
744         if (ret < 0)
745             continue;
746
747         /* Allocate output mbuf pkts */
748         ret = rte_pktmbuf_alloc_bulk(mbuf_pool, output_pkts_burst, MAX_PKT_BURST);
749         if (ret < 0)
750             continue;
751
752         for (j = 0; j < op_num; j++) {
753             /* Append the size of the ethernet header */
754             rte_pktmbuf_append(input_pkts_burst[j],
755                     sizeof(struct ether_hdr));
756
757             /* set op */
758
759             ops_burst[j]->turbo_enc.input.offset =
760                 sizeof(struct ether_hdr);
761
762             ops_burst[j]->turbo_enc->input.length =
763                 rte_pktmbuf_pkt_len(bbdev_pkts[j]);
764
765             ops_burst[j]->turbo_enc->input.data =
766                 input_pkts_burst[j];
767
768             ops_burst[j]->turbo_enc->output.offset =
769                 sizeof(struct ether_hdr);
770
771             ops_burst[j]->turbo_enc->output.data =
772                     output_pkts_burst[j];
773         }
774
775         /* Enqueue packets on BBDEV device */
776         op_num = rte_bbdev_enqueue_enc_ops(qconf->bbdev_id,
777                 qconf->bbdev_qs[q], ops_burst,
778                 MAX_PKT_BURST);
779
780         /* Dequeue packets from BBDEV device*/
781         op_num = rte_bbdev_dequeue_enc_ops(qconf->bbdev_id,
782                 qconf->bbdev_qs[q], ops_burst,
783                 MAX_PKT_BURST);
784     }
785
786
787 BBDEV Device API
788 ~~~~~~~~~~~~~~~~
789
790 The bbdev Library API is described in the *DPDK API Reference* document.