#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"

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); \
        i < RTE_BBDEV_MAX_DEVS; \
        i = rte_bbdev_find_next(i))

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_id	Device identifier
event	Device event to register for notification of.
cb_arg	User specified parameter to be passed to user's callback function.
ret_param	To pass data back to user application.

Definition at line 747 of file rte_bbdev.h.

Enumeration Type Documentation

enum rte_bbdev_state

Flags indicate current state of BBDEV device

Definition at line 47 of file rte_bbdev.h.

enum rte_bbdev_event_type

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_id The 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_id The 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_id	The identifier of the device.
num_queues	Number of queues to configure on device.
socket_id	ID 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_id The 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_id	The identifier of the device.
queue_id	The index of the queue.
conf	The 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_id The 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_id The 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_id The 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_id	The identifier of the device.
queue_id	The 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_id	The identifier of the device.
queue_id	The 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_id	The identifier of the device.
stats	Pointer 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_id The 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_id	The identifier of the device.
dev_info	Pointer 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_id	The identifier of the device.
queue_id	The index of the queue.
queue_info	Pointer 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer array containing operations to be enqueued Must have at least `num_ops` entries
num_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer array containing operations to be enqueued Must have at least `num_ops` entries
num_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer array containing operations to be enqueued Must have at least `num_ops` entries
num_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer array containing operations to be enqueued Must have at least `num_ops` entries
num_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer 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_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer 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_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer array where operations will be dequeued to. Must have at least `num_ops` entries
num_ops	The 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_id	The identifier of the device.
queue_id	The index of the queue.
ops	Pointer array where operations will be dequeued to. Must have at least `num_ops` entries
num_ops	The 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_id	Device id.
event	The event that the callback will be registered for.
cb_fn	User supplied callback function to be called.
cb_arg	Pointer 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_id	The device identifier.
event	The event that the callback will be unregistered for.
cb_fn	User supplied callback function to be unregistered.
cb_arg	Pointer 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_id	The device identifier.
queue_id	The 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_id	The device identifier.
queue_id	The 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_id	The device identifier.
queue_id	The index of the queue.
epfd	Epoll 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()).
op	The operation be performed for the vector.RTE_INTR_EVENT_ADD or RTE_INTR_EVENT_DEL.
data	User 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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation