DPDK  20.05.0
Data Structures | Macros | Typedefs | Enumerations | Functions
rte_bbdev.h File Reference
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include <rte_compat.h>
#include <rte_atomic.h>
#include <rte_bus.h>
#include <rte_cpuflags.h>
#include <rte_memory.h>
#include "rte_bbdev_op.h"

Go to the source code of this file.

Data Structures

struct  rte_bbdev_queue_conf
 
struct  rte_bbdev_stats
 
struct  rte_bbdev_driver_info
 
struct  rte_bbdev_info
 
struct  rte_bbdev_queue_info
 

Macros

#define RTE_BBDEV_MAX_DEVS   128
 
#define RTE_BBDEV_FOREACH(i)
 
#define RTE_BBDEV_END_OF_CAPABILITIES_LIST()   { RTE_BBDEV_OP_NONE }
 
#define RTE_BBDEV_NAME_MAX_LEN   64
 

Typedefs

typedef void(* rte_bbdev_cb_fn) (uint16_t dev_id, enum rte_bbdev_event_type event, void *cb_arg, void *ret_param)
 

Enumerations

enum  rte_bbdev_state
 
enum  rte_bbdev_event_type { RTE_BBDEV_EVENT_UNKNOWN, RTE_BBDEV_EVENT_ERROR, RTE_BBDEV_EVENT_DEQUEUE, RTE_BBDEV_EVENT_MAX }
 

Functions

__rte_experimental uint16_t rte_bbdev_count (void)
 
__rte_experimental bool rte_bbdev_is_valid (uint16_t dev_id)
 
__rte_experimental uint16_t rte_bbdev_find_next (uint16_t dev_id)
 
__rte_experimental int rte_bbdev_setup_queues (uint16_t dev_id, uint16_t num_queues, int socket_id)
 
__rte_experimental int rte_bbdev_intr_enable (uint16_t dev_id)
 
__rte_experimental int rte_bbdev_queue_configure (uint16_t dev_id, uint16_t queue_id, const struct rte_bbdev_queue_conf *conf)
 
__rte_experimental int rte_bbdev_start (uint16_t dev_id)
 
__rte_experimental int rte_bbdev_stop (uint16_t dev_id)
 
__rte_experimental int rte_bbdev_close (uint16_t dev_id)
 
__rte_experimental int rte_bbdev_queue_start (uint16_t dev_id, uint16_t queue_id)
 
__rte_experimental int rte_bbdev_queue_stop (uint16_t dev_id, uint16_t queue_id)
 
__rte_experimental int rte_bbdev_stats_get (uint16_t dev_id, struct rte_bbdev_stats *stats)
 
__rte_experimental int rte_bbdev_stats_reset (uint16_t dev_id)
 
__rte_experimental int rte_bbdev_info_get (uint16_t dev_id, struct rte_bbdev_info *dev_info)
 
__rte_experimental int rte_bbdev_queue_info_get (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_queue_info *queue_info)
 
 TAILQ_HEAD (rte_bbdev_cb_list, rte_bbdev_callback)
 
static __rte_experimental uint16_t rte_bbdev_enqueue_enc_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_enqueue_dec_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_enqueue_ldpc_enc_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_enqueue_ldpc_dec_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_dequeue_enc_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_dequeue_dec_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_dequeue_ldpc_enc_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 
static __rte_experimental uint16_t rte_bbdev_dequeue_ldpc_dec_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 
__rte_experimental int rte_bbdev_callback_register (uint16_t dev_id, enum rte_bbdev_event_type event, rte_bbdev_cb_fn cb_fn, void *cb_arg)
 
__rte_experimental int rte_bbdev_callback_unregister (uint16_t dev_id, enum rte_bbdev_event_type event, rte_bbdev_cb_fn cb_fn, void *cb_arg)
 
__rte_experimental int rte_bbdev_queue_intr_enable (uint16_t dev_id, uint16_t queue_id)
 
__rte_experimental int rte_bbdev_queue_intr_disable (uint16_t dev_id, uint16_t queue_id)
 
__rte_experimental int rte_bbdev_queue_intr_ctl (uint16_t dev_id, uint16_t queue_id, int epfd, int op, void *data)
 

Detailed Description

Wireless base band device abstraction APIs.

Warning
EXPERIMENTAL: this API may change without prior notice

This API allows an application to discover, configure and use a device to process operations. An asynchronous API (enqueue, followed by later dequeue) is used for processing operations.

The functions in this API are not thread-safe when called on the same target object (a device, or a queue on a device), with the exception that one thread can enqueue operations to a queue while another thread dequeues from the same queue.

Definition in file rte_bbdev.h.

Macro Definition Documentation

#define RTE_BBDEV_MAX_DEVS   128

Max number of devices

Definition at line 43 of file rte_bbdev.h.

#define RTE_BBDEV_FOREACH (   i)
Value:
for (i = rte_bbdev_find_next(-1); \
#define RTE_BBDEV_MAX_DEVS
Definition: rte_bbdev.h:43
__rte_experimental uint16_t rte_bbdev_find_next(uint16_t dev_id)

Iterate through all enabled devices

Definition at line 90 of file rte_bbdev.h.

#define RTE_BBDEV_END_OF_CAPABILITIES_LIST ( )    { RTE_BBDEV_OP_NONE }

Macro used at end of bbdev PMD list

Definition at line 321 of file rte_bbdev.h.

#define RTE_BBDEV_NAME_MAX_LEN   64

Max length of device name

Definition at line 412 of file rte_bbdev.h.

Typedef Documentation

typedef void(* rte_bbdev_cb_fn) (uint16_t dev_id, enum rte_bbdev_event_type event, void *cb_arg, void *ret_param)

Typedef for application callback function registered by application software for notification of device events

Parameters
dev_idDevice identifier
eventDevice event to register for notification of.
cb_argUser specified parameter to be passed to user's callback function.
ret_paramTo pass data back to user application.

Definition at line 747 of file rte_bbdev.h.

Enumeration Type Documentation

Flags indicate current state of BBDEV device

Definition at line 47 of file rte_bbdev.h.

Definitions of device event types

Enumerator
RTE_BBDEV_EVENT_UNKNOWN 

unknown event type

RTE_BBDEV_EVENT_ERROR 

error interrupt event

RTE_BBDEV_EVENT_DEQUEUE 

dequeue event

RTE_BBDEV_EVENT_MAX 

max value of this enum

Definition at line 727 of file rte_bbdev.h.

Function Documentation

__rte_experimental uint16_t rte_bbdev_count ( void  )

Get the total number of devices that have been successfully initialised.

Returns
The total number of usable devices.
Examples:
examples/bbdev_app/main.c.
__rte_experimental bool rte_bbdev_is_valid ( uint16_t  dev_id)

Check if a device is valid.

Parameters
dev_idThe identifier of the device.
Returns
true if device ID is valid and device is attached, false otherwise.
__rte_experimental uint16_t rte_bbdev_find_next ( uint16_t  dev_id)

Get the next enabled device.

Parameters
dev_idThe current device
Returns
  • The next device, or
  • RTE_BBDEV_MAX_DEVS if none found
__rte_experimental int rte_bbdev_setup_queues ( uint16_t  dev_id,
uint16_t  num_queues,
int  socket_id 
)

Setup up device queues. This function must be called on a device before setting up the queues and starting the device. It can also be called when a device is in the stopped state. If any device queues have been configured their configuration will be cleared by a call to this function.

Parameters
dev_idThe identifier of the device.
num_queuesNumber of queues to configure on device.
socket_idID of a socket which will be used to allocate memory.
Returns
  • 0 on success
  • -ENODEV if dev_id is invalid or the device is corrupted
  • -EINVAL if num_queues is invalid, 0 or greater than maximum
  • -EBUSY if the identified device has already started
  • -ENOMEM if unable to allocate memory
Examples:
examples/bbdev_app/main.c.
__rte_experimental int rte_bbdev_intr_enable ( uint16_t  dev_id)

Enable interrupts. This function may be called before starting the device to enable the interrupts if they are available.

Parameters
dev_idThe identifier of the device.
Returns
  • 0 on success
  • -ENODEV if dev_id is invalid or the device is corrupted
  • -EBUSY if the identified device has already started
  • -ENOTSUP if the interrupts are not supported by the device
__rte_experimental int rte_bbdev_queue_configure ( uint16_t  dev_id,
uint16_t  queue_id,
const struct rte_bbdev_queue_conf conf 
)

Configure a queue on a device. This function can be called after device configuration, and before starting. It can also be called when the device or the queue is in the stopped state.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
confThe queue configuration. If NULL, a default configuration will be used.
Returns
  • 0 on success
  • EINVAL if the identified queue size or priority are invalid
  • EBUSY if the identified queue or its device have already started
Examples:
examples/bbdev_app/main.c.
__rte_experimental int rte_bbdev_start ( uint16_t  dev_id)

Start a device. This is the last step needed before enqueueing operations is possible.

Parameters
dev_idThe identifier of the device.
Returns
  • 0 on success
  • negative value on failure - as returned from PMD driver
Examples:
examples/bbdev_app/main.c.
__rte_experimental int rte_bbdev_stop ( uint16_t  dev_id)

Stop a device. The device can be reconfigured, and restarted after being stopped.

Parameters
dev_idThe identifier of the device.
Returns
  • 0 on success
__rte_experimental int rte_bbdev_close ( uint16_t  dev_id)

Close a device. The device cannot be restarted without reconfiguration!

Parameters
dev_idThe identifier of the device.
Returns
  • 0 on success
__rte_experimental int rte_bbdev_queue_start ( uint16_t  dev_id,
uint16_t  queue_id 
)

Start a specified queue on a device. This is only needed if the queue has been stopped, or if the deferred_start flag has been set when configuring the queue.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
Returns
  • 0 on success
  • negative value on failure - as returned from PMD driver
__rte_experimental int rte_bbdev_queue_stop ( uint16_t  dev_id,
uint16_t  queue_id 
)

Stop a specified queue on a device, to allow re configuration.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
Returns
  • 0 on success
  • negative value on failure - as returned from PMD driver
__rte_experimental int rte_bbdev_stats_get ( uint16_t  dev_id,
struct rte_bbdev_stats stats 
)

Retrieve the general I/O statistics of a device.

Parameters
dev_idThe identifier of the device.
statsPointer to structure to where statistics will be copied. On error, this location may or may not have been modified.
Returns
  • 0 on success
  • EINVAL if invalid parameter pointer is provided
Examples:
examples/bbdev_app/main.c.
__rte_experimental int rte_bbdev_stats_reset ( uint16_t  dev_id)

Reset the statistics of a device.

Parameters
dev_idThe identifier of the device.
Returns
  • 0 on success
__rte_experimental int rte_bbdev_info_get ( uint16_t  dev_id,
struct rte_bbdev_info dev_info 
)

Retrieve information about a device.

Parameters
dev_idThe identifier of the device.
dev_infoPointer to structure to where information will be copied. On error, this location may or may not have been modified.
Returns
  • 0 on success
  • EINVAL if invalid parameter pointer is provided
Examples:
examples/bbdev_app/main.c.
__rte_experimental int rte_bbdev_queue_info_get ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_queue_info queue_info 
)

Retrieve information about a specific queue on a device.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
queue_infoPointer to structure to where information will be copied. On error, this location may or may not have been modified.
Returns
  • 0 on success
  • EINVAL if invalid parameter pointer is provided
TAILQ_HEAD ( rte_bbdev_cb_list  ,
rte_bbdev_callback   
)

Structure to keep track of registered callbacks

static __rte_experimental uint16_t rte_bbdev_enqueue_enc_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_enc_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Enqueue a burst of processed encode operations to a queue of the device. This functions only enqueues as many operations as currently possible and does not block until num_ops entries in the queue are available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array containing operations to be enqueued Must have at least num_ops entries
num_opsThe maximum number of operations to enqueue.
Returns
The number of operations actually enqueued (this is the number of processed entries in the ops array).
Examples:
examples/bbdev_app/main.c.

Definition at line 496 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_enqueue_dec_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_dec_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Enqueue a burst of processed decode operations to a queue of the device. This functions only enqueues as many operations as currently possible and does not block until num_ops entries in the queue are available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array containing operations to be enqueued Must have at least num_ops entries
num_opsThe maximum number of operations to enqueue.
Returns
The number of operations actually enqueued (this is the number of processed entries in the ops array).
Examples:
examples/bbdev_app/main.c.

Definition at line 527 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_enqueue_ldpc_enc_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_enc_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Enqueue a burst of processed encode operations to a queue of the device. This functions only enqueues as many operations as currently possible and does not block until num_ops entries in the queue are available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array containing operations to be enqueued Must have at least num_ops entries
num_opsThe maximum number of operations to enqueue.
Returns
The number of operations actually enqueued (this is the number of processed entries in the ops array).

Definition at line 558 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_enqueue_ldpc_dec_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_dec_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Enqueue a burst of processed decode operations to a queue of the device. This functions only enqueues as many operations as currently possible and does not block until num_ops entries in the queue are available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array containing operations to be enqueued Must have at least num_ops entries
num_opsThe maximum number of operations to enqueue.
Returns
The number of operations actually enqueued (this is the number of processed entries in the ops array).

Definition at line 589 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_dequeue_enc_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_enc_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Dequeue a burst of processed encode operations from a queue of the device. This functions returns only the current contents of the queue, and does not block until @ num_ops is available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array where operations will be dequeued to. Must have at least num_ops entries ie. A pointer to a table of void * pointers (ops) that will be filled.
num_opsThe maximum number of operations to dequeue.
Returns
The number of operations actually dequeued (this is the number of entries copied into the ops array).
Examples:
examples/bbdev_app/main.c.

Definition at line 622 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_dequeue_dec_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_dec_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Dequeue a burst of processed decode operations from a queue of the device. This functions returns only the current contents of the queue, and does not block until @ num_ops is available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array where operations will be dequeued to. Must have at least num_ops entries ie. A pointer to a table of void * pointers (ops) that will be filled.
num_opsThe maximum number of operations to dequeue.
Returns
The number of operations actually dequeued (this is the number of entries copied into the ops array).
Examples:
examples/bbdev_app/main.c.

Definition at line 655 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_dequeue_ldpc_enc_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_enc_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Dequeue a burst of processed encode operations from a queue of the device. This functions returns only the current contents of the queue, and does not block until @ num_ops is available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array where operations will be dequeued to. Must have at least num_ops entries
num_opsThe maximum number of operations to dequeue.
Returns
The number of operations actually dequeued (this is the number of entries copied into the ops array).

Definition at line 687 of file rte_bbdev.h.

static __rte_experimental uint16_t rte_bbdev_dequeue_ldpc_dec_ops ( uint16_t  dev_id,
uint16_t  queue_id,
struct rte_bbdev_dec_op **  ops,
uint16_t  num_ops 
)
inlinestatic

Dequeue a burst of processed decode operations from a queue of the device. This functions returns only the current contents of the queue, and does not block until @ num_ops is available. This function does not provide any error notification to avoid the corresponding overhead.

Parameters
dev_idThe identifier of the device.
queue_idThe index of the queue.
opsPointer array where operations will be dequeued to. Must have at least num_ops entries
num_opsThe maximum number of operations to dequeue.
Returns
The number of operations actually dequeued (this is the number of entries copied into the ops array).

Definition at line 718 of file rte_bbdev.h.

__rte_experimental int rte_bbdev_callback_register ( uint16_t  dev_id,
enum rte_bbdev_event_type  event,
rte_bbdev_cb_fn  cb_fn,
void *  cb_arg 
)

Register a callback function for specific device id. Multiple callbacks can be added and will be called in the order they are added when an event is triggered. Callbacks are called in a separate thread created by the DPDK EAL.

Parameters
dev_idDevice id.
eventThe event that the callback will be registered for.
cb_fnUser supplied callback function to be called.
cb_argPointer to parameter that will be passed to the callback.
Returns
Zero on success, negative value on failure.
__rte_experimental int rte_bbdev_callback_unregister ( uint16_t  dev_id,
enum rte_bbdev_event_type  event,
rte_bbdev_cb_fn  cb_fn,
void *  cb_arg 
)

Unregister a callback function for specific device id.

Parameters
dev_idThe device identifier.
eventThe event that the callback will be unregistered for.
cb_fnUser supplied callback function to be unregistered.
cb_argPointer to the parameter supplied when registering the callback. (void *)-1 means to remove all registered callbacks with the specified function address.
Returns
  • 0 on success
  • EINVAL if invalid parameter pointer is provided
  • EAGAIN if the provided callback pointer does not exist
__rte_experimental int rte_bbdev_queue_intr_enable ( uint16_t  dev_id,
uint16_t  queue_id 
)

Enable a one-shot interrupt on the next operation enqueued to a particular queue. The interrupt will be triggered when the operation is ready to be dequeued. To handle the interrupt, an epoll file descriptor must be registered using rte_bbdev_queue_intr_ctl(), and then an application thread/lcore can wait for the interrupt using rte_epoll_wait().

Parameters
dev_idThe device identifier.
queue_idThe index of the queue.
Returns
  • 0 on success
  • negative value on failure - as returned from PMD driver
__rte_experimental int rte_bbdev_queue_intr_disable ( uint16_t  dev_id,
uint16_t  queue_id 
)

Disable a one-shot interrupt on the next operation enqueued to a particular queue (if it has been enabled).

Parameters
dev_idThe device identifier.
queue_idThe index of the queue.
Returns
  • 0 on success
  • negative value on failure - as returned from PMD driver
__rte_experimental int rte_bbdev_queue_intr_ctl ( uint16_t  dev_id,
uint16_t  queue_id,
int  epfd,
int  op,
void *  data 
)

Control interface for per-queue interrupts.

Parameters
dev_idThe device identifier.
queue_idThe index of the queue.
epfdEpoll file descriptor that will be associated with the interrupt source. If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also be used when calling rte_epoll_wait()).
opThe operation be performed for the vector.RTE_INTR_EVENT_ADD or RTE_INTR_EVENT_DEL.
dataUser context, that will be returned in the epdata.data field of the rte_epoll_event structure filled in by rte_epoll_wait().
Returns
  • 0 on success
  • ENOTSUP if interrupts are not supported by the identified device
  • negative value on failure - as returned from PMD driver