1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation
11 * Wireless base band device abstraction APIs.
14 * @b EXPERIMENTAL: this API may change without prior notice
16 * This API allows an application to discover, configure and use a device to
17 * process operations. An asynchronous API (enqueue, followed by later dequeue)
18 * is used for processing operations.
20 * The functions in this API are not thread-safe when called on the same
21 * target object (a device, or a queue on a device), with the exception that
22 * one thread can enqueue operations to a queue while another thread dequeues
23 * from the same queue.
34 #include <rte_atomic.h>
36 #include <rte_cpuflags.h>
37 #include <rte_memory.h>
39 #include "rte_bbdev_op.h"
41 #ifndef RTE_BBDEV_MAX_DEVS
42 #define RTE_BBDEV_MAX_DEVS 128 /**< Max number of devices */
45 /** Flags indiciate current state of BBDEV device */
46 enum rte_bbdev_state {
52 * Get the total number of devices that have been successfully initialised.
55 * The total number of usable devices.
58 rte_bbdev_count(void);
61 * Check if a device is valid.
64 * The identifier of the device.
67 * true if device ID is valid and device is attached, false otherwise.
70 rte_bbdev_is_valid(uint16_t dev_id);
73 * Get the next enabled device.
79 * - The next device, or
80 * - RTE_BBDEV_MAX_DEVS if none found
83 rte_bbdev_find_next(uint16_t dev_id);
85 /** Iterate through all enabled devices */
86 #define RTE_BBDEV_FOREACH(i) for (i = rte_bbdev_find_next(-1); \
87 i < RTE_BBDEV_MAX_DEVS; \
88 i = rte_bbdev_find_next(i))
91 * Setup up device queues.
92 * This function must be called on a device before setting up the queues and
93 * starting the device. It can also be called when a device is in the stopped
94 * state. If any device queues have been configured their configuration will be
95 * cleared by a call to this function.
98 * The identifier of the device.
100 * Number of queues to configure on device.
102 * ID of a socket which will be used to allocate memory.
106 * - -ENODEV if dev_id is invalid or the device is corrupted
107 * - -EINVAL if num_queues is invalid, 0 or greater than maximum
108 * - -EBUSY if the identified device has already started
109 * - -ENOMEM if unable to allocate memory
112 rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues, int socket_id);
116 * This function may be called before starting the device to enable the
117 * interrupts if they are available.
120 * The identifier of the device.
124 * - -ENODEV if dev_id is invalid or the device is corrupted
125 * - -EBUSY if the identified device has already started
126 * - -ENOTSUP if the interrupts are not supported by the device
129 rte_bbdev_intr_enable(uint16_t dev_id);
131 /** Device queue configuration structure */
132 struct rte_bbdev_queue_conf {
133 int socket; /**< NUMA socket used for memory allocation */
134 uint32_t queue_size; /**< Size of queue */
135 uint8_t priority; /**< Queue priority */
136 bool deferred_start; /**< Do not start queue when device is started. */
137 enum rte_bbdev_op_type op_type; /**< Operation type */
141 * Configure a queue on a device.
142 * This function can be called after device configuration, and before starting.
143 * It can also be called when the device or the queue is in the stopped state.
146 * The identifier of the device.
148 * The index of the queue.
150 * The queue configuration. If NULL, a default configuration will be used.
154 * - EINVAL if the identified queue size or priority are invalid
155 * - EBUSY if the identified queue or its device have already started
158 rte_bbdev_queue_configure(uint16_t dev_id, uint16_t queue_id,
159 const struct rte_bbdev_queue_conf *conf);
163 * This is the last step needed before enqueueing operations is possible.
166 * The identifier of the device.
170 * - negative value on failure - as returned from PMD driver
173 rte_bbdev_start(uint16_t dev_id);
177 * The device can be reconfigured, and restarted after being stopped.
180 * The identifier of the device.
186 rte_bbdev_stop(uint16_t dev_id);
190 * The device cannot be restarted without reconfiguration!
193 * The identifier of the device.
199 rte_bbdev_close(uint16_t dev_id);
202 * Start a specified queue on a device.
203 * This is only needed if the queue has been stopped, or if the deferred_start
204 * flag has been set when configuring the queue.
207 * The identifier of the device.
209 * The index of the queue.
213 * - negative value on failure - as returned from PMD driver
216 rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id);
219 * Stop a specified queue on a device, to allow re configuration.
222 * The identifier of the device.
224 * The index of the queue.
228 * - negative value on failure - as returned from PMD driver
231 rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id);
233 /** Device statistics. */
234 struct rte_bbdev_stats {
235 uint64_t enqueued_count; /**< Count of all operations enqueued */
236 uint64_t dequeued_count; /**< Count of all operations dequeued */
237 /** Total error count on operations enqueued */
238 uint64_t enqueue_err_count;
239 /** Total error count on operations dequeued */
240 uint64_t dequeue_err_count;
244 * Retrieve the general I/O statistics of a device.
247 * The identifier of the device.
249 * Pointer to structure to where statistics will be copied. On error, this
250 * location may or may not have been modified.
254 * - EINVAL if invalid parameter pointer is provided
257 rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats);
260 * Reset the statistics of a device.
263 * The identifier of the device.
268 rte_bbdev_stats_reset(uint16_t dev_id);
270 /** Device information supplied by the device's driver */
271 struct rte_bbdev_driver_info {
273 const char *driver_name;
275 /** Maximum number of queues supported by the device */
276 unsigned int max_num_queues;
277 /** Queue size limit (queue size must also be power of 2) */
278 uint32_t queue_size_lim;
279 /** Set if device off-loads operation to hardware */
280 bool hardware_accelerated;
281 /** Max value supported by queue priority */
282 uint8_t max_queue_priority;
283 /** Set if device supports per-queue interrupts */
284 bool queue_intr_supported;
285 /** Minimum alignment of buffers, in bytes */
286 uint16_t min_alignment;
287 /** Default queue configuration used if none is supplied */
288 struct rte_bbdev_queue_conf default_queue_conf;
289 /** Device operation capabilities */
290 const struct rte_bbdev_op_cap *capabilities;
291 /** Device cpu_flag requirements */
292 const enum rte_cpu_flag_t *cpu_flag_reqs;
295 /** Macro used at end of bbdev PMD list */
296 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \
297 { RTE_BBDEV_OP_NONE }
300 * Device information structure used by an application to discover a devices
301 * capabilities and current configuration
303 struct rte_bbdev_info {
304 int socket_id; /**< NUMA socket that device is on */
305 const char *dev_name; /**< Unique device name */
306 const struct rte_bus *bus; /**< Bus information */
307 uint16_t num_queues; /**< Number of queues currently configured */
308 bool started; /**< Set if device is currently started */
309 struct rte_bbdev_driver_info drv; /**< Info from device driver */
313 * Retrieve information about a device.
316 * The identifier of the device.
318 * Pointer to structure to where information will be copied. On error, this
319 * location may or may not have been modified.
323 * - EINVAL if invalid parameter pointer is provided
326 rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info);
328 /** Queue information */
329 struct rte_bbdev_queue_info {
330 /** Current device configuration */
331 struct rte_bbdev_queue_conf conf;
332 /** Set if queue is currently started */
337 * Retrieve information about a specific queue on a device.
340 * The identifier of the device.
342 * The index of the queue.
344 * Pointer to structure to where information will be copied. On error, this
345 * location may or may not have been modified.
349 * - EINVAL if invalid parameter pointer is provided
352 rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id,
353 struct rte_bbdev_queue_info *queue_info);
355 /** @internal The data structure associated with each queue of a device. */
356 struct rte_bbdev_queue_data {
357 void *queue_private; /**< Driver-specific per-queue data */
358 struct rte_bbdev_queue_conf conf; /**< Current configuration */
359 struct rte_bbdev_stats queue_stats; /**< Queue statistics */
360 bool started; /**< Queue state */
363 /** @internal Enqueue encode operations for processing on queue of a device. */
364 typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)(
365 struct rte_bbdev_queue_data *q_data,
366 struct rte_bbdev_enc_op **ops,
369 /** @internal Enqueue decode operations for processing on queue of a device. */
370 typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)(
371 struct rte_bbdev_queue_data *q_data,
372 struct rte_bbdev_dec_op **ops,
375 /** @internal Dequeue encode operations from a queue of a device. */
376 typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)(
377 struct rte_bbdev_queue_data *q_data,
378 struct rte_bbdev_enc_op **ops, uint16_t num);
380 /** @internal Dequeue decode operations from a queue of a device. */
381 typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)(
382 struct rte_bbdev_queue_data *q_data,
383 struct rte_bbdev_dec_op **ops, uint16_t num);
385 #define RTE_BBDEV_NAME_MAX_LEN 64 /**< Max length of device name */
388 * @internal The data associated with a device, with no function pointers.
389 * This structure is safe to place in shared memory to be common among
390 * different processes in a multi-process configuration. Drivers can access
391 * these fields, but should never write to them!
393 struct rte_bbdev_data {
394 char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */
395 void *dev_private; /**< Driver-specific private data */
396 uint16_t num_queues; /**< Number of currently configured queues */
397 struct rte_bbdev_queue_data *queues; /**< Queue structures */
398 uint16_t dev_id; /**< Device ID */
399 int socket_id; /**< NUMA socket that device is on */
400 bool started; /**< Device run-time state */
401 /** Counter of processes using the device */
402 rte_atomic16_t process_cnt;
405 /* Forward declarations */
406 struct rte_bbdev_ops;
407 struct rte_bbdev_callback;
408 struct rte_intr_handle;
410 /** Structure to keep track of registered callbacks */
411 TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback);
414 * @internal The data structure associated with a device. Drivers can access
415 * these fields, but should only write to the *_ops fields.
417 struct __rte_cache_aligned rte_bbdev {
418 /**< Enqueue encode function */
419 rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops;
420 /**< Enqueue decode function */
421 rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops;
422 /**< Dequeue encode function */
423 rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops;
424 /**< Dequeue decode function */
425 rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops;
426 const struct rte_bbdev_ops *dev_ops; /**< Functions exported by PMD */
427 struct rte_bbdev_data *data; /**< Pointer to device data */
428 enum rte_bbdev_state state; /**< If device is currently used or not */
429 struct rte_device *device; /**< Backing device */
430 /** User application callback for interrupts if present */
431 struct rte_bbdev_cb_list list_cbs;
432 struct rte_intr_handle *intr_handle; /**< Device interrupt handle */
435 /** @internal array of all devices */
436 extern struct rte_bbdev rte_bbdev_devices[];
439 * Enqueue a burst of processed encode operations to a queue of the device.
440 * This functions only enqueues as many operations as currently possible and
441 * does not block until @p num_ops entries in the queue are available.
442 * This function does not provide any error notification to avoid the
443 * corresponding overhead.
446 * The identifier of the device.
448 * The index of the queue.
450 * Pointer array containing operations to be enqueued Must have at least
453 * The maximum number of operations to enqueue.
456 * The number of operations actually enqueued (this is the number of processed
457 * entries in the @p ops array).
459 static inline uint16_t
460 rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
461 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
463 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
464 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
465 uint16_t n = dev->enqueue_enc_ops(q_data, ops, num_ops);
467 rte_bbdev_log_verbose("%u encode ops enqueued to dev%u,q%u.\n",
468 num_ops, dev_id, queue_id);
474 * Enqueue a burst of processed decode operations to a queue of the device.
475 * This functions only enqueues as many operations as currently possible and
476 * does not block until @p num_ops entries in the queue are available.
477 * This function does not provide any error notification to avoid the
478 * corresponding overhead.
481 * The identifier of the device.
483 * The index of the queue.
485 * Pointer array containing operations to be enqueued Must have at least
488 * The maximum number of operations to enqueue.
491 * The number of operations actually enqueued (this is the number of processed
492 * entries in the @p ops array).
494 static inline uint16_t
495 rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
496 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
498 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
499 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
500 uint16_t n = dev->enqueue_dec_ops(q_data, ops, num_ops);
502 rte_bbdev_log_verbose("%u decode ops enqueued to dev%u,q%u.\n",
503 num_ops, dev_id, queue_id);
509 * Dequeue a burst of processed encode operations from a queue of the device.
510 * This functions returns only the current contents of the queue, and does not
511 * block until @ num_ops is available.
512 * This function does not provide any error notification to avoid the
513 * corresponding overhead.
516 * The identifier of the device.
518 * The index of the queue.
520 * Pointer array where operations will be dequeued to. Must have at least
523 * The maximum number of operations to dequeue.
526 * The number of operations actually dequeued (this is the number of entries
527 * copied into the @p ops array).
529 static inline uint16_t
530 rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
531 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
533 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
534 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
535 uint16_t n = dev->dequeue_enc_ops(q_data, ops, num_ops);
537 rte_bbdev_log_verbose("%u encode ops dequeued to dev%u,q%u\n",
538 n, dev_id, queue_id);
544 * Dequeue a burst of processed decode operations from a queue of the device.
545 * This functions returns only the current contents of the queue, and does not
546 * block until @ num_ops is available.
547 * This function does not provide any error notification to avoid the
548 * corresponding overhead.
551 * The identifier of the device.
553 * The index of the queue.
555 * Pointer array where operations will be dequeued to. Must have at least
558 * The maximum number of operations to dequeue.
561 * The number of operations actually dequeued (this is the number of entries
562 * copied into the @p ops array).
565 static inline uint16_t
566 rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
567 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
569 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
570 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
571 uint16_t n = dev->dequeue_dec_ops(q_data, ops, num_ops);
573 rte_bbdev_log_verbose("%u decode ops dequeued to dev%u,q%u\n",
574 n, dev_id, queue_id);
579 /** Definitions of device event types */
580 enum rte_bbdev_event_type {
581 RTE_BBDEV_EVENT_UNKNOWN, /**< unknown event type */
582 RTE_BBDEV_EVENT_ERROR, /**< error interrupt event */
583 RTE_BBDEV_EVENT_DEQUEUE, /**< dequeue event */
584 RTE_BBDEV_EVENT_MAX /**< max value of this enum */
588 * Typedef for application callback function registered by application
589 * software for notification of device events
594 * Device event to register for notification of.
596 * User specified parameter to be passed to user's callback function.
598 * To pass data back to user application.
600 typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id,
601 enum rte_bbdev_event_type event, void *cb_arg,
605 * Register a callback function for specific device id. Multiple callbacks can
606 * be added and will be called in the order they are added when an event is
607 * triggered. Callbacks are called in a separate thread created by the DPDK EAL.
612 * The event that the callback will be registered for.
614 * User supplied callback function to be called.
616 * Pointer to parameter that will be passed to the callback.
619 * Zero on success, negative value on failure.
622 rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event,
623 rte_bbdev_cb_fn cb_fn, void *cb_arg);
626 * Unregister a callback function for specific device id.
629 * The device identifier.
631 * The event that the callback will be unregistered for.
633 * User supplied callback function to be unregistered.
635 * Pointer to the parameter supplied when registering the callback.
636 * (void *)-1 means to remove all registered callbacks with the specified
641 * - EINVAL if invalid parameter pointer is provided
642 * - EAGAIN if the provided callback pointer does not exist
645 rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event,
646 rte_bbdev_cb_fn cb_fn, void *cb_arg);
649 * Enable a one-shot interrupt on the next operation enqueued to a particular
650 * queue. The interrupt will be triggered when the operation is ready to be
651 * dequeued. To handle the interrupt, an epoll file descriptor must be
652 * registered using rte_bbdev_queue_intr_ctl(), and then an application
653 * thread/lcore can wait for the interrupt using rte_epoll_wait().
656 * The device identifier.
658 * The index of the queue.
662 * - negative value on failure - as returned from PMD driver
665 rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id);
668 * Disable a one-shot interrupt on the next operation enqueued to a particular
669 * queue (if it has been enabled).
672 * The device identifier.
674 * The index of the queue.
678 * - negative value on failure - as returned from PMD driver
681 rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id);
684 * Control interface for per-queue interrupts.
687 * The device identifier.
689 * The index of the queue.
691 * Epoll file descriptor that will be associated with the interrupt source.
692 * If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll
693 * file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also
694 * be used when calling rte_epoll_wait()).
696 * The operation be performed for the vector.RTE_INTR_EVENT_ADD or
697 * RTE_INTR_EVENT_DEL.
699 * User context, that will be returned in the epdata.data field of the
700 * rte_epoll_event structure filled in by rte_epoll_wait().
704 * - ENOTSUP if interrupts are not supported by the identified device
705 * - negative value on failure - as returned from PMD driver
708 rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op,
715 #endif /* _RTE_BBDEV_H_ */