1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation
11 * Wireless base band device abstraction APIs.
15 * All functions in this file may be changed or removed without prior notice.
17 * This API allows an application to discover, configure and use a device to
18 * process operations. An asynchronous API (enqueue, followed by later dequeue)
19 * is used for processing operations.
21 * The functions in this API are not thread-safe when called on the same
22 * target object (a device, or a queue on a device), with the exception that
23 * one thread can enqueue operations to a queue while another thread dequeues
24 * from the same queue.
35 #include <rte_compat.h>
36 #include <rte_atomic.h>
38 #include <rte_cpuflags.h>
39 #include <rte_memory.h>
41 #include "rte_bbdev_op.h"
43 #ifndef RTE_BBDEV_MAX_DEVS
44 #define RTE_BBDEV_MAX_DEVS 128 /**< Max number of devices */
47 /** Flags indicate current state of BBDEV device */
48 enum rte_bbdev_state {
54 * Get the total number of devices that have been successfully initialised.
57 * The total number of usable devices.
61 rte_bbdev_count(void);
64 * Check if a device is valid.
67 * The identifier of the device.
70 * true if device ID is valid and device is attached, false otherwise.
74 rte_bbdev_is_valid(uint16_t dev_id);
77 * Get the next enabled device.
83 * - The next device, or
84 * - RTE_BBDEV_MAX_DEVS if none found
88 rte_bbdev_find_next(uint16_t dev_id);
90 /** Iterate through all enabled devices */
91 #define RTE_BBDEV_FOREACH(i) for (i = rte_bbdev_find_next(-1); \
92 i < RTE_BBDEV_MAX_DEVS; \
93 i = rte_bbdev_find_next(i))
96 * Setup up device queues.
97 * This function must be called on a device before setting up the queues and
98 * starting the device. It can also be called when a device is in the stopped
99 * state. If any device queues have been configured their configuration will be
100 * cleared by a call to this function.
103 * The identifier of the device.
105 * Number of queues to configure on device.
107 * ID of a socket which will be used to allocate memory.
111 * - -ENODEV if dev_id is invalid or the device is corrupted
112 * - -EINVAL if num_queues is invalid, 0 or greater than maximum
113 * - -EBUSY if the identified device has already started
114 * - -ENOMEM if unable to allocate memory
118 rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues, int socket_id);
122 * This function may be called before starting the device to enable the
123 * interrupts if they are available.
126 * The identifier of the device.
130 * - -ENODEV if dev_id is invalid or the device is corrupted
131 * - -EBUSY if the identified device has already started
132 * - -ENOTSUP if the interrupts are not supported by the device
136 rte_bbdev_intr_enable(uint16_t dev_id);
138 /** Device queue configuration structure */
139 struct rte_bbdev_queue_conf {
140 int socket; /**< NUMA socket used for memory allocation */
141 uint32_t queue_size; /**< Size of queue */
142 uint8_t priority; /**< Queue priority */
143 bool deferred_start; /**< Do not start queue when device is started. */
144 enum rte_bbdev_op_type op_type; /**< Operation type */
148 * Configure a queue on a device.
149 * This function can be called after device configuration, and before starting.
150 * It can also be called when the device or the queue is in the stopped state.
153 * The identifier of the device.
155 * The index of the queue.
157 * The queue configuration. If NULL, a default configuration will be used.
161 * - EINVAL if the identified queue size or priority are invalid
162 * - EBUSY if the identified queue or its device have already started
166 rte_bbdev_queue_configure(uint16_t dev_id, uint16_t queue_id,
167 const struct rte_bbdev_queue_conf *conf);
171 * This is the last step needed before enqueueing operations is possible.
174 * The identifier of the device.
178 * - negative value on failure - as returned from PMD driver
182 rte_bbdev_start(uint16_t dev_id);
186 * The device can be reconfigured, and restarted after being stopped.
189 * The identifier of the device.
196 rte_bbdev_stop(uint16_t dev_id);
200 * The device cannot be restarted without reconfiguration!
203 * The identifier of the device.
210 rte_bbdev_close(uint16_t dev_id);
213 * Start a specified queue on a device.
214 * This is only needed if the queue has been stopped, or if the deferred_start
215 * flag has been set when configuring the queue.
218 * The identifier of the device.
220 * The index of the queue.
224 * - negative value on failure - as returned from PMD driver
228 rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id);
231 * Stop a specified queue on a device, to allow re configuration.
234 * The identifier of the device.
236 * The index of the queue.
240 * - negative value on failure - as returned from PMD driver
244 rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id);
246 /** Device statistics. */
247 struct rte_bbdev_stats {
248 uint64_t enqueued_count; /**< Count of all operations enqueued */
249 uint64_t dequeued_count; /**< Count of all operations dequeued */
250 /** Total error count on operations enqueued */
251 uint64_t enqueue_err_count;
252 /** Total error count on operations dequeued */
253 uint64_t dequeue_err_count;
254 /** CPU cycles consumed by the (HW/SW) accelerator device to offload
255 * the enqueue request to its internal queues.
256 * - For a HW device this is the cycles consumed in MMIO write
257 * - For a SW (vdev) device, this is the processing time of the
260 uint64_t acc_offload_cycles;
264 * Retrieve the general I/O statistics of a device.
267 * The identifier of the device.
269 * Pointer to structure to where statistics will be copied. On error, this
270 * location may or may not have been modified.
274 * - EINVAL if invalid parameter pointer is provided
278 rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats);
281 * Reset the statistics of a device.
284 * The identifier of the device.
290 rte_bbdev_stats_reset(uint16_t dev_id);
292 /** Device information supplied by the device's driver */
293 struct rte_bbdev_driver_info {
295 const char *driver_name;
297 /** Maximum number of queues supported by the device */
298 unsigned int max_num_queues;
299 /** Queue size limit (queue size must also be power of 2) */
300 uint32_t queue_size_lim;
301 /** Set if device off-loads operation to hardware */
302 bool hardware_accelerated;
303 /** Max value supported by queue priority for DL */
304 uint8_t max_dl_queue_priority;
305 /** Max value supported by queue priority for UL */
306 uint8_t max_ul_queue_priority;
307 /** Set if device supports per-queue interrupts */
308 bool queue_intr_supported;
309 /** Minimum alignment of buffers, in bytes */
310 uint16_t min_alignment;
311 /** HARQ memory available in kB */
312 uint32_t harq_buffer_size;
313 /** Default queue configuration used if none is supplied */
314 struct rte_bbdev_queue_conf default_queue_conf;
315 /** Device operation capabilities */
316 const struct rte_bbdev_op_cap *capabilities;
317 /** Device cpu_flag requirements */
318 const enum rte_cpu_flag_t *cpu_flag_reqs;
321 /** Macro used at end of bbdev PMD list */
322 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \
323 { RTE_BBDEV_OP_NONE }
326 * Device information structure used by an application to discover a devices
327 * capabilities and current configuration
329 struct rte_bbdev_info {
330 int socket_id; /**< NUMA socket that device is on */
331 const char *dev_name; /**< Unique device name */
332 const struct rte_device *device; /**< Device Information */
333 uint16_t num_queues; /**< Number of queues currently configured */
334 bool started; /**< Set if device is currently started */
335 struct rte_bbdev_driver_info drv; /**< Info from device driver */
339 * Retrieve information about a device.
342 * The identifier of the device.
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
353 rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info);
355 /** Queue information */
356 struct rte_bbdev_queue_info {
357 /** Current device configuration */
358 struct rte_bbdev_queue_conf conf;
359 /** Set if queue is currently started */
364 * Retrieve information about a specific queue on a device.
367 * The identifier of the device.
369 * The index of the queue.
371 * Pointer to structure to where information will be copied. On error, this
372 * location may or may not have been modified.
376 * - EINVAL if invalid parameter pointer is provided
380 rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id,
381 struct rte_bbdev_queue_info *queue_info);
383 /** @internal The data structure associated with each queue of a device. */
384 struct rte_bbdev_queue_data {
385 void *queue_private; /**< Driver-specific per-queue data */
386 struct rte_bbdev_queue_conf conf; /**< Current configuration */
387 struct rte_bbdev_stats queue_stats; /**< Queue statistics */
388 bool started; /**< Queue state */
391 /** @internal Enqueue encode operations for processing on queue of a device. */
392 typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)(
393 struct rte_bbdev_queue_data *q_data,
394 struct rte_bbdev_enc_op **ops,
397 /** @internal Enqueue decode operations for processing on queue of a device. */
398 typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)(
399 struct rte_bbdev_queue_data *q_data,
400 struct rte_bbdev_dec_op **ops,
403 /** @internal Dequeue encode operations from a queue of a device. */
404 typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)(
405 struct rte_bbdev_queue_data *q_data,
406 struct rte_bbdev_enc_op **ops, uint16_t num);
408 /** @internal Dequeue decode operations from a queue of a device. */
409 typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)(
410 struct rte_bbdev_queue_data *q_data,
411 struct rte_bbdev_dec_op **ops, uint16_t num);
413 #define RTE_BBDEV_NAME_MAX_LEN 64 /**< Max length of device name */
416 * @internal The data associated with a device, with no function pointers.
417 * This structure is safe to place in shared memory to be common among
418 * different processes in a multi-process configuration. Drivers can access
419 * these fields, but should never write to them!
421 struct rte_bbdev_data {
422 char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */
423 void *dev_private; /**< Driver-specific private data */
424 uint16_t num_queues; /**< Number of currently configured queues */
425 struct rte_bbdev_queue_data *queues; /**< Queue structures */
426 uint16_t dev_id; /**< Device ID */
427 int socket_id; /**< NUMA socket that device is on */
428 bool started; /**< Device run-time state */
429 /** Counter of processes using the device */
430 rte_atomic16_t process_cnt;
433 /* Forward declarations */
434 struct rte_bbdev_ops;
435 struct rte_bbdev_callback;
436 struct rte_intr_handle;
438 /** Structure to keep track of registered callbacks */
439 TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback);
442 * @internal The data structure associated with a device. Drivers can access
443 * these fields, but should only write to the *_ops fields.
445 struct __rte_cache_aligned rte_bbdev {
446 /** Enqueue encode function */
447 rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops;
448 /** Enqueue decode function */
449 rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops;
450 /** Dequeue encode function */
451 rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops;
452 /** Dequeue decode function */
453 rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops;
454 /** Enqueue encode function */
455 rte_bbdev_enqueue_enc_ops_t enqueue_ldpc_enc_ops;
456 /** Enqueue decode function */
457 rte_bbdev_enqueue_dec_ops_t enqueue_ldpc_dec_ops;
458 /** Dequeue encode function */
459 rte_bbdev_dequeue_enc_ops_t dequeue_ldpc_enc_ops;
460 /** Dequeue decode function */
461 rte_bbdev_dequeue_dec_ops_t dequeue_ldpc_dec_ops;
462 const struct rte_bbdev_ops *dev_ops; /**< Functions exported by PMD */
463 struct rte_bbdev_data *data; /**< Pointer to device data */
464 enum rte_bbdev_state state; /**< If device is currently used or not */
465 struct rte_device *device; /**< Backing device */
466 /** User application callback for interrupts if present */
467 struct rte_bbdev_cb_list list_cbs;
468 struct rte_intr_handle *intr_handle; /**< Device interrupt handle */
471 /** @internal array of all devices */
472 extern struct rte_bbdev rte_bbdev_devices[];
475 * Enqueue a burst of processed encode operations to a queue of the device.
476 * This functions only enqueues as many operations as currently possible and
477 * does not block until @p num_ops entries in the queue are available.
478 * This function does not provide any error notification to avoid the
479 * corresponding overhead.
482 * The identifier of the device.
484 * The index of the queue.
486 * Pointer array containing operations to be enqueued Must have at least
489 * The maximum number of operations to enqueue.
492 * The number of operations actually enqueued (this is the number of processed
493 * entries in the @p ops array).
496 static inline uint16_t
497 rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
498 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
500 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
501 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
502 return dev->enqueue_enc_ops(q_data, ops, num_ops);
506 * Enqueue a burst of processed decode operations to a queue of the device.
507 * This functions only enqueues as many operations as currently possible and
508 * does not block until @p num_ops entries in the queue are available.
509 * This function does not provide any error notification to avoid the
510 * corresponding overhead.
513 * The identifier of the device.
515 * The index of the queue.
517 * Pointer array containing operations to be enqueued Must have at least
520 * The maximum number of operations to enqueue.
523 * The number of operations actually enqueued (this is the number of processed
524 * entries in the @p ops array).
527 static inline uint16_t
528 rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
529 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
531 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
532 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
533 return dev->enqueue_dec_ops(q_data, ops, num_ops);
537 * Enqueue a burst of processed encode operations to a queue of the device.
538 * This functions only enqueues as many operations as currently possible and
539 * does not block until @p num_ops entries in the queue are available.
540 * This function does not provide any error notification to avoid the
541 * corresponding overhead.
544 * The identifier of the device.
546 * The index of the queue.
548 * Pointer array containing operations to be enqueued Must have at least
551 * The maximum number of operations to enqueue.
554 * The number of operations actually enqueued (this is the number of processed
555 * entries in the @p ops array).
558 static inline uint16_t
559 rte_bbdev_enqueue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id,
560 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
562 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
563 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
564 return dev->enqueue_ldpc_enc_ops(q_data, ops, num_ops);
568 * Enqueue a burst of processed decode operations to a queue of the device.
569 * This functions only enqueues as many operations as currently possible and
570 * does not block until @p num_ops entries in the queue are available.
571 * This function does not provide any error notification to avoid the
572 * corresponding overhead.
575 * The identifier of the device.
577 * The index of the queue.
579 * Pointer array containing operations to be enqueued Must have at least
582 * The maximum number of operations to enqueue.
585 * The number of operations actually enqueued (this is the number of processed
586 * entries in the @p ops array).
589 static inline uint16_t
590 rte_bbdev_enqueue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id,
591 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
593 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
594 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
595 return dev->enqueue_ldpc_dec_ops(q_data, ops, num_ops);
600 * Dequeue a burst of processed encode operations from a queue of the device.
601 * This functions returns only the current contents of the queue, and does not
602 * block until @ num_ops is available.
603 * This function does not provide any error notification to avoid the
604 * corresponding overhead.
607 * The identifier of the device.
609 * The index of the queue.
611 * Pointer array where operations will be dequeued to. Must have at least
613 * ie. A pointer to a table of void * pointers (ops) that will be filled.
615 * The maximum number of operations to dequeue.
618 * The number of operations actually dequeued (this is the number of entries
619 * copied into the @p ops array).
622 static inline uint16_t
623 rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
624 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
626 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
627 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
628 return dev->dequeue_enc_ops(q_data, ops, num_ops);
632 * Dequeue a burst of processed decode operations from a queue of the device.
633 * This functions returns only the current contents of the queue, and does not
634 * block until @ num_ops is available.
635 * This function does not provide any error notification to avoid the
636 * corresponding overhead.
639 * The identifier of the device.
641 * The index of the queue.
643 * Pointer array where operations will be dequeued to. Must have at least
645 * ie. A pointer to a table of void * pointers (ops) that will be filled.
647 * The maximum number of operations to dequeue.
650 * The number of operations actually dequeued (this is the number of entries
651 * copied into the @p ops array).
655 static inline uint16_t
656 rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
657 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
659 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
660 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
661 return dev->dequeue_dec_ops(q_data, ops, num_ops);
666 * Dequeue a burst of processed encode operations from a queue of the device.
667 * This functions returns only the current contents of the queue, and does not
668 * block until @ num_ops is available.
669 * This function does not provide any error notification to avoid the
670 * corresponding overhead.
673 * The identifier of the device.
675 * The index of the queue.
677 * Pointer array where operations will be dequeued to. Must have at least
680 * The maximum number of operations to dequeue.
683 * The number of operations actually dequeued (this is the number of entries
684 * copied into the @p ops array).
687 static inline uint16_t
688 rte_bbdev_dequeue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id,
689 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
691 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
692 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
693 return dev->dequeue_ldpc_enc_ops(q_data, ops, num_ops);
697 * Dequeue a burst of processed decode operations from a queue of the device.
698 * This functions returns only the current contents of the queue, and does not
699 * block until @ num_ops is available.
700 * This function does not provide any error notification to avoid the
701 * corresponding overhead.
704 * The identifier of the device.
706 * The index of the queue.
708 * Pointer array where operations will be dequeued to. Must have at least
711 * The maximum number of operations to dequeue.
714 * The number of operations actually dequeued (this is the number of entries
715 * copied into the @p ops array).
718 static inline uint16_t
719 rte_bbdev_dequeue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id,
720 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
722 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
723 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
724 return dev->dequeue_ldpc_dec_ops(q_data, ops, num_ops);
727 /** Definitions of device event types */
728 enum rte_bbdev_event_type {
729 RTE_BBDEV_EVENT_UNKNOWN, /**< unknown event type */
730 RTE_BBDEV_EVENT_ERROR, /**< error interrupt event */
731 RTE_BBDEV_EVENT_DEQUEUE, /**< dequeue event */
732 RTE_BBDEV_EVENT_MAX /**< max value of this enum */
736 * Typedef for application callback function registered by application
737 * software for notification of device events
742 * Device event to register for notification of.
744 * User specified parameter to be passed to user's callback function.
746 * To pass data back to user application.
748 typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id,
749 enum rte_bbdev_event_type event, void *cb_arg,
753 * Register a callback function for specific device id. Multiple callbacks can
754 * be added and will be called in the order they are added when an event is
755 * triggered. Callbacks are called in a separate thread created by the DPDK EAL.
760 * The event that the callback will be registered for.
762 * User supplied callback function to be called.
764 * Pointer to parameter that will be passed to the callback.
767 * Zero on success, negative value on failure.
771 rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event,
772 rte_bbdev_cb_fn cb_fn, void *cb_arg);
775 * Unregister a callback function for specific device id.
778 * The device identifier.
780 * The event that the callback will be unregistered for.
782 * User supplied callback function to be unregistered.
784 * Pointer to the parameter supplied when registering the callback.
785 * (void *)-1 means to remove all registered callbacks with the specified
790 * - EINVAL if invalid parameter pointer is provided
791 * - EAGAIN if the provided callback pointer does not exist
795 rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event,
796 rte_bbdev_cb_fn cb_fn, void *cb_arg);
799 * Enable a one-shot interrupt on the next operation enqueued to a particular
800 * queue. The interrupt will be triggered when the operation is ready to be
801 * dequeued. To handle the interrupt, an epoll file descriptor must be
802 * registered using rte_bbdev_queue_intr_ctl(), and then an application
803 * thread/lcore can wait for the interrupt using rte_epoll_wait().
806 * The device identifier.
808 * The index of the queue.
812 * - negative value on failure - as returned from PMD driver
816 rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id);
819 * Disable a one-shot interrupt on the next operation enqueued to a particular
820 * queue (if it has been enabled).
823 * The device identifier.
825 * The index of the queue.
829 * - negative value on failure - as returned from PMD driver
833 rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id);
836 * Control interface for per-queue interrupts.
839 * The device identifier.
841 * The index of the queue.
843 * Epoll file descriptor that will be associated with the interrupt source.
844 * If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll
845 * file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also
846 * be used when calling rte_epoll_wait()).
848 * The operation be performed for the vector.RTE_INTR_EVENT_ADD or
849 * RTE_INTR_EVENT_DEL.
851 * User context, that will be returned in the epdata.data field of the
852 * rte_epoll_event structure filled in by rte_epoll_wait().
856 * - ENOTSUP if interrupts are not supported by the identified device
857 * - negative value on failure - as returned from PMD driver
861 rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op,
868 #endif /* _RTE_BBDEV_H_ */