DPDK  19.02.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

uint16_t __rte_experimental rte_bbdev_count (void)
bool __rte_experimental rte_bbdev_is_valid (uint16_t dev_id)
uint16_t __rte_experimental rte_bbdev_find_next (uint16_t dev_id)
int __rte_experimental rte_bbdev_setup_queues (uint16_t dev_id, uint16_t num_queues, int socket_id)
int __rte_experimental rte_bbdev_intr_enable (uint16_t dev_id)
int __rte_experimental rte_bbdev_queue_configure (uint16_t dev_id, uint16_t queue_id, const struct rte_bbdev_queue_conf *conf)
int __rte_experimental rte_bbdev_start (uint16_t dev_id)
int __rte_experimental rte_bbdev_stop (uint16_t dev_id)
int __rte_experimental rte_bbdev_close (uint16_t dev_id)
int __rte_experimental rte_bbdev_queue_start (uint16_t dev_id, uint16_t queue_id)
int __rte_experimental rte_bbdev_queue_stop (uint16_t dev_id, uint16_t queue_id)
int __rte_experimental rte_bbdev_stats_get (uint16_t dev_id, struct rte_bbdev_stats *stats)
int __rte_experimental rte_bbdev_stats_reset (uint16_t dev_id)
int __rte_experimental rte_bbdev_info_get (uint16_t dev_id, struct rte_bbdev_info *dev_info)
int __rte_experimental 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 uint16_t __rte_experimental rte_bbdev_enqueue_enc_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_enc_op **ops, uint16_t num_ops)
static uint16_t __rte_experimental rte_bbdev_enqueue_dec_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_dec_op **ops, uint16_t num_ops)
static uint16_t __rte_experimental rte_bbdev_dequeue_enc_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_enc_op **ops, uint16_t num_ops)
static uint16_t __rte_experimental rte_bbdev_dequeue_dec_ops (uint16_t dev_id, uint16_t queue_id, struct rte_bbdev_dec_op **ops, uint16_t num_ops)
int __rte_experimental rte_bbdev_callback_register (uint16_t dev_id, enum rte_bbdev_event_type event, rte_bbdev_cb_fn cb_fn, void *cb_arg)
int __rte_experimental rte_bbdev_callback_unregister (uint16_t dev_id, enum rte_bbdev_event_type event, rte_bbdev_cb_fn cb_fn, void *cb_arg)
int __rte_experimental rte_bbdev_queue_intr_enable (uint16_t dev_id, uint16_t queue_id)
int __rte_experimental rte_bbdev_queue_intr_disable (uint16_t dev_id, uint16_t queue_id)
int __rte_experimental 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:

Iterate through all enabled devices

Definition at line 87 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 306 of file rte_bbdev.h.

#define RTE_BBDEV_NAME_MAX_LEN   64

Max length of device name

Definition at line 395 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 590 of file rte_bbdev.h.

Enumeration Type Documentation

Flags indiciate 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 570 of file rte_bbdev.h.

Function Documentation

uint16_t __rte_experimental 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.
bool __rte_experimental 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.
uint16_t __rte_experimental 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
int __rte_experimental 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.
int __rte_experimental 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
int __rte_experimental 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.
int __rte_experimental 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.
int __rte_experimental 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
int __rte_experimental 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
int __rte_experimental 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
int __rte_experimental 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
int __rte_experimental 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.
int __rte_experimental 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
int __rte_experimental 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.
int __rte_experimental 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 uint16_t __rte_experimental 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 470 of file rte_bbdev.h.

static uint16_t __rte_experimental 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 500 of file rte_bbdev.h.

static uint16_t __rte_experimental 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
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 530 of file rte_bbdev.h.

static uint16_t __rte_experimental 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
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 561 of file rte_bbdev.h.

int __rte_experimental 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.
int __rte_experimental 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
int __rte_experimental 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
int __rte_experimental 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
int __rte_experimental 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