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_compat.h>
35 #include <rte_atomic.h>
37 #include <rte_cpuflags.h>
38 #include <rte_memory.h>
40 #include "rte_bbdev_op.h"
42 #ifndef RTE_BBDEV_MAX_DEVS
43 #define RTE_BBDEV_MAX_DEVS 128 /**< Max number of devices */
46 /** Flags indiciate current state of BBDEV device */
47 enum rte_bbdev_state {
53 * Get the total number of devices that have been successfully initialised.
56 * The total number of usable devices.
58 uint16_t __rte_experimental
59 rte_bbdev_count(void);
62 * Check if a device is valid.
65 * The identifier of the device.
68 * true if device ID is valid and device is attached, false otherwise.
70 bool __rte_experimental
71 rte_bbdev_is_valid(uint16_t dev_id);
74 * Get the next enabled device.
80 * - The next device, or
81 * - RTE_BBDEV_MAX_DEVS if none found
83 uint16_t __rte_experimental
84 rte_bbdev_find_next(uint16_t dev_id);
86 /** Iterate through all enabled devices */
87 #define RTE_BBDEV_FOREACH(i) for (i = rte_bbdev_find_next(-1); \
88 i < RTE_BBDEV_MAX_DEVS; \
89 i = rte_bbdev_find_next(i))
92 * Setup up device queues.
93 * This function must be called on a device before setting up the queues and
94 * starting the device. It can also be called when a device is in the stopped
95 * state. If any device queues have been configured their configuration will be
96 * cleared by a call to this function.
99 * The identifier of the device.
101 * Number of queues to configure on device.
103 * ID of a socket which will be used to allocate memory.
107 * - -ENODEV if dev_id is invalid or the device is corrupted
108 * - -EINVAL if num_queues is invalid, 0 or greater than maximum
109 * - -EBUSY if the identified device has already started
110 * - -ENOMEM if unable to allocate memory
112 int __rte_experimental
113 rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues, int socket_id);
117 * This function may be called before starting the device to enable the
118 * interrupts if they are available.
121 * The identifier of the device.
125 * - -ENODEV if dev_id is invalid or the device is corrupted
126 * - -EBUSY if the identified device has already started
127 * - -ENOTSUP if the interrupts are not supported by the device
129 int __rte_experimental
130 rte_bbdev_intr_enable(uint16_t dev_id);
132 /** Device queue configuration structure */
133 struct rte_bbdev_queue_conf {
134 int socket; /**< NUMA socket used for memory allocation */
135 uint32_t queue_size; /**< Size of queue */
136 uint8_t priority; /**< Queue priority */
137 bool deferred_start; /**< Do not start queue when device is started. */
138 enum rte_bbdev_op_type op_type; /**< Operation type */
142 * Configure a queue on a device.
143 * This function can be called after device configuration, and before starting.
144 * It can also be called when the device or the queue is in the stopped state.
147 * The identifier of the device.
149 * The index of the queue.
151 * The queue configuration. If NULL, a default configuration will be used.
155 * - EINVAL if the identified queue size or priority are invalid
156 * - EBUSY if the identified queue or its device have already started
158 int __rte_experimental
159 rte_bbdev_queue_configure(uint16_t dev_id, uint16_t queue_id,
160 const struct rte_bbdev_queue_conf *conf);
164 * This is the last step needed before enqueueing operations is possible.
167 * The identifier of the device.
171 * - negative value on failure - as returned from PMD driver
173 int __rte_experimental
174 rte_bbdev_start(uint16_t dev_id);
178 * The device can be reconfigured, and restarted after being stopped.
181 * The identifier of the device.
186 int __rte_experimental
187 rte_bbdev_stop(uint16_t dev_id);
191 * The device cannot be restarted without reconfiguration!
194 * The identifier of the device.
199 int __rte_experimental
200 rte_bbdev_close(uint16_t dev_id);
203 * Start a specified queue on a device.
204 * This is only needed if the queue has been stopped, or if the deferred_start
205 * flag has been set when configuring the queue.
208 * The identifier of the device.
210 * The index of the queue.
214 * - negative value on failure - as returned from PMD driver
216 int __rte_experimental
217 rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id);
220 * Stop a specified queue on a device, to allow re configuration.
223 * The identifier of the device.
225 * The index of the queue.
229 * - negative value on failure - as returned from PMD driver
231 int __rte_experimental
232 rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id);
234 /** Device statistics. */
235 struct rte_bbdev_stats {
236 uint64_t enqueued_count; /**< Count of all operations enqueued */
237 uint64_t dequeued_count; /**< Count of all operations dequeued */
238 /** Total error count on operations enqueued */
239 uint64_t enqueue_err_count;
240 /** Total error count on operations dequeued */
241 uint64_t dequeue_err_count;
243 uint64_t offload_time;
247 * Retrieve the general I/O statistics of a device.
250 * The identifier of the device.
252 * Pointer to structure to where statistics will be copied. On error, this
253 * location may or may not have been modified.
257 * - EINVAL if invalid parameter pointer is provided
259 int __rte_experimental
260 rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats);
263 * Reset the statistics of a device.
266 * The identifier of the device.
270 int __rte_experimental
271 rte_bbdev_stats_reset(uint16_t dev_id);
273 /** Device information supplied by the device's driver */
274 struct rte_bbdev_driver_info {
276 const char *driver_name;
278 /** Maximum number of queues supported by the device */
279 unsigned int max_num_queues;
280 /** Queue size limit (queue size must also be power of 2) */
281 uint32_t queue_size_lim;
282 /** Set if device off-loads operation to hardware */
283 bool hardware_accelerated;
284 /** Max value supported by queue priority */
285 uint8_t max_queue_priority;
286 /** Set if device supports per-queue interrupts */
287 bool queue_intr_supported;
288 /** Minimum alignment of buffers, in bytes */
289 uint16_t min_alignment;
290 /** Default queue configuration used if none is supplied */
291 struct rte_bbdev_queue_conf default_queue_conf;
292 /** Device operation capabilities */
293 const struct rte_bbdev_op_cap *capabilities;
294 /** Device cpu_flag requirements */
295 const enum rte_cpu_flag_t *cpu_flag_reqs;
298 /** Macro used at end of bbdev PMD list */
299 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \
300 { RTE_BBDEV_OP_NONE }
303 * Device information structure used by an application to discover a devices
304 * capabilities and current configuration
306 struct rte_bbdev_info {
307 int socket_id; /**< NUMA socket that device is on */
308 const char *dev_name; /**< Unique device name */
309 const struct rte_bus *bus; /**< Bus information */
310 uint16_t num_queues; /**< Number of queues currently configured */
311 bool started; /**< Set if device is currently started */
312 struct rte_bbdev_driver_info drv; /**< Info from device driver */
316 * Retrieve information about a device.
319 * The identifier of the device.
321 * Pointer to structure to where information will be copied. On error, this
322 * location may or may not have been modified.
326 * - EINVAL if invalid parameter pointer is provided
328 int __rte_experimental
329 rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info);
331 /** Queue information */
332 struct rte_bbdev_queue_info {
333 /** Current device configuration */
334 struct rte_bbdev_queue_conf conf;
335 /** Set if queue is currently started */
340 * Retrieve information about a specific queue on a device.
343 * The identifier of the device.
345 * The index of the queue.
347 * Pointer to structure to where information will be copied. On error, this
348 * location may or may not have been modified.
352 * - EINVAL if invalid parameter pointer is provided
354 int __rte_experimental
355 rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id,
356 struct rte_bbdev_queue_info *queue_info);
358 /** @internal The data structure associated with each queue of a device. */
359 struct rte_bbdev_queue_data {
360 void *queue_private; /**< Driver-specific per-queue data */
361 struct rte_bbdev_queue_conf conf; /**< Current configuration */
362 struct rte_bbdev_stats queue_stats; /**< Queue statistics */
363 bool started; /**< Queue state */
366 /** @internal Enqueue encode operations for processing on queue of a device. */
367 typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)(
368 struct rte_bbdev_queue_data *q_data,
369 struct rte_bbdev_enc_op **ops,
372 /** @internal Enqueue decode operations for processing on queue of a device. */
373 typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)(
374 struct rte_bbdev_queue_data *q_data,
375 struct rte_bbdev_dec_op **ops,
378 /** @internal Dequeue encode operations from a queue of a device. */
379 typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)(
380 struct rte_bbdev_queue_data *q_data,
381 struct rte_bbdev_enc_op **ops, uint16_t num);
383 /** @internal Dequeue decode operations from a queue of a device. */
384 typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)(
385 struct rte_bbdev_queue_data *q_data,
386 struct rte_bbdev_dec_op **ops, uint16_t num);
388 #define RTE_BBDEV_NAME_MAX_LEN 64 /**< Max length of device name */
391 * @internal The data associated with a device, with no function pointers.
392 * This structure is safe to place in shared memory to be common among
393 * different processes in a multi-process configuration. Drivers can access
394 * these fields, but should never write to them!
396 struct rte_bbdev_data {
397 char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */
398 void *dev_private; /**< Driver-specific private data */
399 uint16_t num_queues; /**< Number of currently configured queues */
400 struct rte_bbdev_queue_data *queues; /**< Queue structures */
401 uint16_t dev_id; /**< Device ID */
402 int socket_id; /**< NUMA socket that device is on */
403 bool started; /**< Device run-time state */
404 /** Counter of processes using the device */
405 rte_atomic16_t process_cnt;
408 /* Forward declarations */
409 struct rte_bbdev_ops;
410 struct rte_bbdev_callback;
411 struct rte_intr_handle;
413 /** Structure to keep track of registered callbacks */
414 TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback);
417 * @internal The data structure associated with a device. Drivers can access
418 * these fields, but should only write to the *_ops fields.
420 struct __rte_cache_aligned rte_bbdev {
421 /**< Enqueue encode function */
422 rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops;
423 /**< Enqueue decode function */
424 rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops;
425 /**< Dequeue encode function */
426 rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops;
427 /**< Dequeue decode function */
428 rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops;
429 const struct rte_bbdev_ops *dev_ops; /**< Functions exported by PMD */
430 struct rte_bbdev_data *data; /**< Pointer to device data */
431 enum rte_bbdev_state state; /**< If device is currently used or not */
432 struct rte_device *device; /**< Backing device */
433 /** User application callback for interrupts if present */
434 struct rte_bbdev_cb_list list_cbs;
435 struct rte_intr_handle *intr_handle; /**< Device interrupt handle */
438 /** @internal array of all devices */
439 extern struct rte_bbdev rte_bbdev_devices[];
442 * Enqueue a burst of processed encode operations to a queue of the device.
443 * This functions only enqueues as many operations as currently possible and
444 * does not block until @p num_ops entries in the queue are available.
445 * This function does not provide any error notification to avoid the
446 * corresponding overhead.
449 * The identifier of the device.
451 * The index of the queue.
453 * Pointer array containing operations to be enqueued Must have at least
456 * The maximum number of operations to enqueue.
459 * The number of operations actually enqueued (this is the number of processed
460 * entries in the @p ops array).
462 static inline uint16_t
463 rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
464 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
466 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
467 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
468 return dev->enqueue_enc_ops(q_data, ops, num_ops);
472 * Enqueue a burst of processed decode operations to a queue of the device.
473 * This functions only enqueues as many operations as currently possible and
474 * does not block until @p num_ops entries in the queue are available.
475 * This function does not provide any error notification to avoid the
476 * corresponding overhead.
479 * The identifier of the device.
481 * The index of the queue.
483 * Pointer array containing operations to be enqueued Must have at least
486 * The maximum number of operations to enqueue.
489 * The number of operations actually enqueued (this is the number of processed
490 * entries in the @p ops array).
492 static inline uint16_t
493 rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
494 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
496 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
497 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
498 return dev->enqueue_dec_ops(q_data, ops, num_ops);
502 * Dequeue a burst of processed encode operations from a queue of the device.
503 * This functions returns only the current contents of the queue, and does not
504 * block until @ num_ops is available.
505 * This function does not provide any error notification to avoid the
506 * corresponding overhead.
509 * The identifier of the device.
511 * The index of the queue.
513 * Pointer array where operations will be dequeued to. Must have at least
516 * The maximum number of operations to dequeue.
519 * The number of operations actually dequeued (this is the number of entries
520 * copied into the @p ops array).
522 static inline uint16_t
523 rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
524 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
526 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
527 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
528 return dev->dequeue_enc_ops(q_data, ops, num_ops);
532 * Dequeue a burst of processed decode operations from a queue of the device.
533 * This functions returns only the current contents of the queue, and does not
534 * block until @ num_ops is available.
535 * This function does not provide any error notification to avoid the
536 * corresponding overhead.
539 * The identifier of the device.
541 * The index of the queue.
543 * Pointer array where operations will be dequeued to. Must have at least
546 * The maximum number of operations to dequeue.
549 * The number of operations actually dequeued (this is the number of entries
550 * copied into the @p ops array).
553 static inline uint16_t
554 rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
555 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
557 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
558 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
559 return dev->dequeue_dec_ops(q_data, ops, num_ops);
562 /** Definitions of device event types */
563 enum rte_bbdev_event_type {
564 RTE_BBDEV_EVENT_UNKNOWN, /**< unknown event type */
565 RTE_BBDEV_EVENT_ERROR, /**< error interrupt event */
566 RTE_BBDEV_EVENT_DEQUEUE, /**< dequeue event */
567 RTE_BBDEV_EVENT_MAX /**< max value of this enum */
571 * Typedef for application callback function registered by application
572 * software for notification of device events
577 * Device event to register for notification of.
579 * User specified parameter to be passed to user's callback function.
581 * To pass data back to user application.
583 typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id,
584 enum rte_bbdev_event_type event, void *cb_arg,
588 * Register a callback function for specific device id. Multiple callbacks can
589 * be added and will be called in the order they are added when an event is
590 * triggered. Callbacks are called in a separate thread created by the DPDK EAL.
595 * The event that the callback will be registered for.
597 * User supplied callback function to be called.
599 * Pointer to parameter that will be passed to the callback.
602 * Zero on success, negative value on failure.
604 int __rte_experimental
605 rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event,
606 rte_bbdev_cb_fn cb_fn, void *cb_arg);
609 * Unregister a callback function for specific device id.
612 * The device identifier.
614 * The event that the callback will be unregistered for.
616 * User supplied callback function to be unregistered.
618 * Pointer to the parameter supplied when registering the callback.
619 * (void *)-1 means to remove all registered callbacks with the specified
624 * - EINVAL if invalid parameter pointer is provided
625 * - EAGAIN if the provided callback pointer does not exist
627 int __rte_experimental
628 rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event,
629 rte_bbdev_cb_fn cb_fn, void *cb_arg);
632 * Enable a one-shot interrupt on the next operation enqueued to a particular
633 * queue. The interrupt will be triggered when the operation is ready to be
634 * dequeued. To handle the interrupt, an epoll file descriptor must be
635 * registered using rte_bbdev_queue_intr_ctl(), and then an application
636 * thread/lcore can wait for the interrupt using rte_epoll_wait().
639 * The device identifier.
641 * The index of the queue.
645 * - negative value on failure - as returned from PMD driver
647 int __rte_experimental
648 rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id);
651 * Disable a one-shot interrupt on the next operation enqueued to a particular
652 * queue (if it has been enabled).
655 * The device identifier.
657 * The index of the queue.
661 * - negative value on failure - as returned from PMD driver
663 int __rte_experimental
664 rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id);
667 * Control interface for per-queue interrupts.
670 * The device identifier.
672 * The index of the queue.
674 * Epoll file descriptor that will be associated with the interrupt source.
675 * If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll
676 * file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also
677 * be used when calling rte_epoll_wait()).
679 * The operation be performed for the vector.RTE_INTR_EVENT_ADD or
680 * RTE_INTR_EVENT_DEL.
682 * User context, that will be returned in the epdata.data field of the
683 * rte_epoll_event structure filled in by rte_epoll_wait().
687 * - ENOTSUP if interrupts are not supported by the identified device
688 * - negative value on failure - as returned from PMD driver
690 int __rte_experimental
691 rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op,
698 #endif /* _RTE_BBDEV_H_ */