1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2017 Intel Corporation
4 Wireless Baseband Device Library
5 ================================
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.
13 The functional scope of the BBDEV library are those functions in relation to
14 the 3gpp Layer 1 signal processing (channel coding, modulation, ...).
16 The framework currently only supports Turbo Code FEC function.
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.
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,
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.
41 From the command line using the --vdev EAL option
43 .. code-block:: console
45 --vdev 'turbo_sw,max_nb_queues=8,socket_id=0'
47 Our using the rte_vdev_init API within the application code.
51 rte_vdev_init("turbo_sw", "max_nb_queues=2,socket_id=0")
53 All virtual bbdev devices support the following initialization parameters:
55 - ``max_nb_queues`` - maximum number of queues supported by the device.
57 - ``socket_id`` - socket on which to allocate the device resources on.
63 Each device, whether virtual or physical is uniquely designated by two
66 - A unique device index used to designate the bbdev device in all functions
67 exported by the bbdev API.
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
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.
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.
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)``.
97 The configuration of each bbdev device includes the following operations:
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.
103 The ``rte_bbdev_setup_queues`` API is used to setup queues for a bbdev device.
107 int rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues,
110 - ``num_queues`` argument identifies the total number of queues to setup for
113 - ``socket_id`` specifies which socket will be used to allocate the memory.
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.
121 int rte_bbdev_intr_enable(uint16_t dev_id);
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.
133 struct rte_bbdev_queue_conf {
138 enum rte_bbdev_op_type op_type;
141 Device & Queues Management
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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)
157 By default, all queues are started when the device is started, but they can be
158 stopped individually.
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)
166 Logical Cores, Memory and Queues Relationships
167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
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.
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.
191 Device Operation Capabilities
192 -----------------------------
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*.
201 struct rte_bbdev_op_cap;
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.
211 static const struct rte_bbdev_op_cap bbdev_capabilities[] = {
213 .type = RTE_BBDEV_OP_TURBO_DEC,
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 .num_buffers_src = RTE_BBDEV_MAX_CODE_BLOCKS,
221 .num_buffers_hard_out =
222 RTE_BBDEV_MAX_CODE_BLOCKS,
223 .num_buffers_soft_out = 0,
227 .type = RTE_BBDEV_OP_TURBO_ENC,
230 RTE_BBDEV_TURBO_CRC_24B_ATTACH |
231 RTE_BBDEV_TURBO_RATE_MATCH |
232 RTE_BBDEV_TURBO_RV_INDEX_BYPASS,
233 .num_buffers_src = RTE_BBDEV_MAX_CODE_BLOCKS,
234 .num_buffers_dst = RTE_BBDEV_MAX_CODE_BLOCKS,
237 RTE_BBDEV_END_OF_CAPABILITIES_LIST()
240 Capabilities Discovery
241 ~~~~~~~~~~~~~~~~~~~~~~
243 Discovering the features and capabilities of a bbdev device poll mode driver
244 is achieved through the ``rte_bbdev_info_get()`` function.
248 int rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info)
250 This allows the user to query a specific bbdev PMD and get all the device
251 capabilities. The ``rte_bbdev_info`` structure provides two levels of
254 - Device relevant information, like: name and related rte_bus.
256 - Driver specific information, as defined by the ``struct rte_bbdev_driver_info``
257 structure, this is where capabilities reside along with other specifics like:
258 maximum queue sizes and priority level.
262 struct rte_bbdev_info {
264 const char *dev_name;
265 const struct rte_bus *bus;
268 struct rte_bbdev_driver_info drv;
274 Scheduling of baseband operations on DPDK's application data path is
275 performed using a burst oriented asynchronous API set. A queue on a bbdev
276 device accepts a burst of baseband operations using enqueue burst API. On physical
277 bbdev devices the enqueue burst API will place the operations to be processed
278 on the device's hardware input queue, for virtual devices the processing of the
279 baseband operations is usually completed during the enqueue call to the bbdev
280 device. The dequeue burst API will retrieve any processed operations available
281 from the queue on the bbdev device, from physical devices this is usually
282 directly from the device's processed queue, and for virtual device's from a
283 ``rte_ring`` where processed operations are place after being processed on the
287 Enqueue / Dequeue Burst APIs
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
290 The burst enqueue API uses a bbdev device identifier and a queue
291 identifier to specify the bbdev device queue to schedule the processing on.
292 The ``num_ops`` parameter is the number of operations to process which are
293 supplied in the ``ops`` array of ``rte_bbdev_*_op`` structures.
294 The enqueue function returns the number of operations it actually enqueued for
295 processing, a return value equal to ``num_ops`` means that all packets have been
300 uint16_t rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
301 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
303 uint16_t rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
304 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
306 The dequeue API uses the same format as the enqueue API of processed but
307 the ``num_ops`` and ``ops`` parameters are now used to specify the max processed
308 operations the user wishes to retrieve and the location in which to store them.
309 The API call returns the actual number of processed operations returned, this
310 can never be larger than ``num_ops``.
314 uint16_t rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
315 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
317 uint16_t rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
318 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
320 Operation Representation
321 ~~~~~~~~~~~~~~~~~~~~~~~~
323 An encode bbdev operation is represented by ``rte_bbdev_enc_op`` structure,
324 and by ``rte_bbdev_dec_op`` for decode. These structures act as metadata
325 containers for all necessary information required for the bbdev operation to be
326 processed on a particular bbdev device poll mode driver.
330 struct rte_bbdev_enc_op {
332 struct rte_mempool *mempool;
334 struct rte_bbdev_op_turbo_enc turbo_enc;
337 struct rte_bbdev_dec_op {
339 struct rte_mempool *mempool;
341 struct rte_bbdev_op_turbo_dec turbo_dec;
344 The operation structure by itself defines the operation type. It includes an
345 operation status, a reference to the operation specific data, which can vary in
346 size and content depending on the operation being provisioned. It also contains
347 the source mempool for the operation, if it is allocated from a mempool.
349 If bbdev operations are allocated from a bbdev operation mempool, see next
350 section, there is also the ability to allocate private memory with the
351 operation for applications purposes.
353 Application software is responsible for specifying all the operation specific
354 fields in the ``rte_bbdev_*_op`` structure which are then used by the bbdev PMD
355 to process the requested operation.
358 Operation Management and Allocation
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
361 The bbdev library provides an API set for managing bbdev operations which
362 utilize the Mempool Library to allocate operation buffers. Therefore, it ensures
363 that the bbdev operation is interleaved optimally across the channels and
364 ranks for optimal processing.
369 rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type,
370 unsigned int num_elements, unsigned int cache_size,
373 ``rte_bbdev_*_op_alloc_bulk()`` and ``rte_bbdev_*_op_free_bulk()`` are used to
374 allocate bbdev operations of a specific type from a given bbdev operation mempool.
378 int rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool,
379 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
381 int rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool,
382 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
384 ``rte_bbdev_*_op_free_bulk()`` is called by the application to return an
385 operation to its allocating pool.
389 void rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops,
390 unsigned int num_ops)
391 void rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops,
392 unsigned int num_ops)
397 The bbdev operation structure contains all the mutable data relating to
398 performing Turbo code processing on a referenced mbuf data buffer. It is used
399 for either encode or decode operations.
401 Turbo Encode operation accepts one input and one output.
403 Turbo Decode operation accepts one input and two outputs, called *hard-decision*
404 and *soft-decision* outputs. *Soft-decision* output is optional.
406 It is expected that the application provides input and output ``mbuf`` pointers
407 allocated and ready to use. The baseband framework supports turbo coding on
408 Code Blocks (CB) and Transport Blocks (TB).
410 For the output buffer(s), the application needs only to provide an allocated and
411 free mbuf (containing only one mbuf segment), so that bbdev can write the
414 **Turbo Encode Op structure**
418 struct rte_bbdev_op_turbo_enc {
419 struct rte_bbdev_op_data input;
420 struct rte_bbdev_op_data output;
424 uint8_t code_block_mode;
426 struct rte_bbdev_op_enc_cb_params cb_params;
427 struct rte_bbdev_op_enc_tb_params tb_params;
432 **Turbo Decode Op structure**
436 struct rte_bbdev_op_turbo_dec {
437 struct rte_bbdev_op_data input;
438 struct rte_bbdev_op_data hard_output;
439 struct rte_bbdev_op_data soft_output;
448 uint8_t code_block_mode;
450 struct rte_bbdev_op_dec_cb_params cb_params;
451 struct rte_bbdev_op_dec_tb_params tb_params;
455 Input and output data buffers are identified by ``rte_bbdev_op_data`` structure.
456 This structure has three elements:
458 - ``data`` - This is the mbuf reference
460 - ``offset`` - The starting point for the Turbo input/output, in bytes, from the
461 start of the data in the data buffer. It must be smaller than data_len of the
464 - ``length`` - The length, in bytes, of the buffer on which the Turbo operation
465 will or has been computed. For the input, the length is set by the application.
466 For the output(s), the length is computed by the bbdev PMD driver.
471 The baseband device sample application gives an introduction on how to use the
472 bbdev framework, by giving a sample code performing a loop-back operation with a
473 baseband processor capable of transceiving data packets.
475 The following sample C-like pseudo-code shows the basic steps to encode several
476 buffers using (**sw_trubo**) bbdev PMD.
481 ret = rte_eal_init(argc, argv);
483 rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n");
485 /* Get number of available bbdev devices */
486 nb_bbdevs = rte_bbdev_count();
488 rte_exit(EXIT_FAILURE, "No bbdevs detected!\n");
490 /* Create bbdev op pools */
491 bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC] =
492 rte_bbdev_op_pool_create("bbdev_op_pool_enc",
493 RTE_BBDEV_OP_TURBO_ENC, NB_MBUF, 128, rte_socket_id());
495 /* Get information for this device */
496 rte_bbdev_info_get(dev_id, &info);
498 /* Setup BBDEV device queues */
499 ret = rte_bbdev_setup_queues(dev_id, qs_nb, info.socket_id);
501 rte_exit(EXIT_FAILURE,
502 "ERROR(%d): BBDEV %u not configured properly\n",
505 /* setup device queues */
506 qconf.socket = info.socket_id;
507 qconf.queue_size = info.drv.queue_size_lim;
508 qconf.op_type = RTE_BBDEV_OP_TURBO_ENC;
510 for (q_id = 0; q_id < qs_nb; q_id++) {
511 /* Configure all queues belonging to this bbdev device */
512 ret = rte_bbdev_queue_configure(dev_id, q_id, &qconf);
514 rte_exit(EXIT_FAILURE,
515 "ERROR(%d): BBDEV %u queue %u not configured properly\n",
519 /* Start bbdev device */
520 ret = rte_bbdev_start(dev_id);
522 /* Create the mbuf mempool for pkts */
523 mbuf_pool = rte_pktmbuf_pool_create("bbdev_mbuf_pool",
524 NB_MBUF, MEMPOOL_CACHE_SIZE, 0,
525 RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id());
526 if (mbuf_pool == NULL)
527 rte_exit(EXIT_FAILURE,
528 "Unable to create '%s' pool\n", pool_name);
530 while (!global_exit_flag) {
532 /* Allocate burst of op structures in preparation for enqueue */
533 if (rte_bbdev_enc_op_alloc_bulk(bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC],
534 ops_burst, op_num) != 0)
537 /* Allocate input mbuf pkts */
538 ret = rte_pktmbuf_alloc_bulk(mbuf_pool, input_pkts_burst, MAX_PKT_BURST);
542 /* Allocate output mbuf pkts */
543 ret = rte_pktmbuf_alloc_bulk(mbuf_pool, output_pkts_burst, MAX_PKT_BURST);
547 for (j = 0; j < op_num; j++) {
548 /* Append the size of the ethernet header */
549 rte_pktmbuf_append(input_pkts_burst[j],
550 sizeof(struct ether_hdr));
554 ops_burst[j]->turbo_enc.input.offset =
555 sizeof(struct ether_hdr);
557 ops_burst[j]->turbo_enc->input.length =
558 rte_pktmbuf_pkt_len(bbdev_pkts[j]);
560 ops_burst[j]->turbo_enc->input.data =
563 ops_burst[j]->turbo_enc->output.offset =
564 sizeof(struct ether_hdr);
566 ops_burst[j]->turbo_enc->output.data =
567 output_pkts_burst[j];
570 /* Enqueue packets on BBDEV device */
571 op_num = rte_bbdev_enqueue_enc_ops(qconf->bbdev_id,
572 qconf->bbdev_qs[q], ops_burst,
575 /* Dequeue packets from BBDEV device*/
576 op_num = rte_bbdev_dequeue_enc_ops(qconf->bbdev_id,
577 qconf->bbdev_qs[q], ops_burst,
585 The bbdev Library API is described in the *DPDK API Reference* document.