Branch data Line data Source code
1 : : /* SPDX-License-Identifier: BSD-3-Clause
2 : : * Copyright(c) 2017 Intel Corporation
3 : : */
4 : :
5 : : #ifndef _RTE_BBDEV_H_
6 : : #define _RTE_BBDEV_H_
7 : :
8 : : /**
9 : : * @file rte_bbdev.h
10 : : *
11 : : * Wireless base band device abstraction APIs.
12 : : *
13 : : * This API allows an application to discover, configure and use a device to
14 : : * process operations. An asynchronous API (enqueue, followed by later dequeue)
15 : : * is used for processing operations.
16 : : *
17 : : * The functions in this API are not thread-safe when called on the same
18 : : * target object (a device, or a queue on a device), with the exception that
19 : : * one thread can enqueue operations to a queue while another thread dequeues
20 : : * from the same queue.
21 : : */
22 : :
23 : : #include <stdint.h>
24 : : #include <stdbool.h>
25 : :
26 : : #include <rte_compat.h>
27 : : #include <rte_cpuflags.h>
28 : :
29 : : #include "rte_bbdev_op.h"
30 : :
31 : : #ifdef __cplusplus
32 : : extern "C" {
33 : : #endif
34 : :
35 : : #ifndef RTE_BBDEV_MAX_DEVS
36 : : #define RTE_BBDEV_MAX_DEVS 128 /**< Max number of devices */
37 : : #endif
38 : :
39 : : /*
40 : : * Maximum size to be used to manage the enum rte_bbdev_enqueue_status
41 : : * including padding for future enum insertion.
42 : : * The enum values must be explicitly kept smaller or equal to this padded maximum size.
43 : : */
44 : : #define RTE_BBDEV_ENQ_STATUS_SIZE_MAX 6
45 : :
46 : : /** Flags indicate current state of BBDEV device */
47 : : enum rte_bbdev_state {
48 : : RTE_BBDEV_UNUSED,
49 : : RTE_BBDEV_INITIALIZED
50 : : };
51 : :
52 : : /**
53 : : * Get the total number of devices that have been successfully initialised.
54 : : *
55 : : * @return
56 : : * The total number of usable devices.
57 : : */
58 : : uint16_t
59 : : rte_bbdev_count(void);
60 : :
61 : : /**
62 : : * Check if a device is valid.
63 : : *
64 : : * @param dev_id
65 : : * The identifier of the device.
66 : : *
67 : : * @return
68 : : * true if device ID is valid and device is attached, false otherwise.
69 : : */
70 : : bool
71 : : rte_bbdev_is_valid(uint16_t dev_id);
72 : :
73 : : /**
74 : : * Get the next enabled device.
75 : : *
76 : : * @param dev_id
77 : : * The current device
78 : : *
79 : : * @return
80 : : * - The next device, or
81 : : * - RTE_BBDEV_MAX_DEVS if none found
82 : : */
83 : : uint16_t
84 : : rte_bbdev_find_next(uint16_t dev_id);
85 : :
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))
90 : :
91 : : /**
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.
97 : : *
98 : : * @param dev_id
99 : : * The identifier of the device.
100 : : * @param num_queues
101 : : * Number of queues to configure on device.
102 : : * @param socket_id
103 : : * ID of a socket which will be used to allocate memory.
104 : : *
105 : : * @return
106 : : * - 0 on success
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
111 : : */
112 : : int
113 : : rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues, int socket_id);
114 : :
115 : : /**
116 : : * Enable interrupts.
117 : : * This function may be called before starting the device to enable the
118 : : * interrupts if they are available.
119 : : *
120 : : * @param dev_id
121 : : * The identifier of the device.
122 : : *
123 : : * @return
124 : : * - 0 on success
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
128 : : */
129 : : int
130 : : rte_bbdev_intr_enable(uint16_t dev_id);
131 : :
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 */
139 : : };
140 : :
141 : : /**
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.
145 : : *
146 : : * @param dev_id
147 : : * The identifier of the device.
148 : : * @param queue_id
149 : : * The index of the queue.
150 : : * @param conf
151 : : * The queue configuration. If NULL, a default configuration will be used.
152 : : *
153 : : * @return
154 : : * - 0 on success
155 : : * - EINVAL if the identified queue size or priority are invalid
156 : : * - EBUSY if the identified queue or its device have already started
157 : : */
158 : : int
159 : : rte_bbdev_queue_configure(uint16_t dev_id, uint16_t queue_id,
160 : : const struct rte_bbdev_queue_conf *conf);
161 : :
162 : : /**
163 : : * Start a device.
164 : : * This is the last step needed before enqueueing operations is possible.
165 : : *
166 : : * @param dev_id
167 : : * The identifier of the device.
168 : : *
169 : : * @return
170 : : * - 0 on success
171 : : * - negative value on failure - as returned from PMD
172 : : */
173 : : int
174 : : rte_bbdev_start(uint16_t dev_id);
175 : :
176 : : /**
177 : : * Stop a device.
178 : : * The device can be reconfigured, and restarted after being stopped.
179 : : *
180 : : * @param dev_id
181 : : * The identifier of the device.
182 : : *
183 : : * @return
184 : : * - 0 on success
185 : : */
186 : : int
187 : : rte_bbdev_stop(uint16_t dev_id);
188 : :
189 : : /**
190 : : * Close a device.
191 : : * The device cannot be restarted without reconfiguration!
192 : : *
193 : : * @param dev_id
194 : : * The identifier of the device.
195 : : *
196 : : * @return
197 : : * - 0 on success
198 : : */
199 : : int
200 : : rte_bbdev_close(uint16_t dev_id);
201 : :
202 : : /**
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.
206 : : *
207 : : * @param dev_id
208 : : * The identifier of the device.
209 : : * @param queue_id
210 : : * The index of the queue.
211 : : *
212 : : * @return
213 : : * - 0 on success
214 : : * - negative value on failure - as returned from PMD
215 : : */
216 : : int
217 : : rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id);
218 : :
219 : : /**
220 : : * Stop a specified queue on a device, to allow re configuration.
221 : : *
222 : : * @param dev_id
223 : : * The identifier of the device.
224 : : * @param queue_id
225 : : * The index of the queue.
226 : : *
227 : : * @return
228 : : * - 0 on success
229 : : * - negative value on failure - as returned from PMD
230 : : */
231 : : int
232 : : rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id);
233 : :
234 : : /**
235 : : * Flags to indicate the reason why a previous enqueue may not have
236 : : * consumed all requested operations.
237 : : * In case of multiple reasons the latter supersedes a previous one.
238 : : * The related macro RTE_BBDEV_ENQ_STATUS_SIZE_MAX can be used
239 : : * as an absolute maximum for notably sizing array
240 : : * while allowing for future enumeration insertion.
241 : : */
242 : : enum rte_bbdev_enqueue_status {
243 : : RTE_BBDEV_ENQ_STATUS_NONE, /**< Nothing to report. */
244 : : RTE_BBDEV_ENQ_STATUS_QUEUE_FULL, /**< Not enough room in queue. */
245 : : RTE_BBDEV_ENQ_STATUS_RING_FULL, /**< Not enough room in ring. */
246 : : RTE_BBDEV_ENQ_STATUS_INVALID_OP, /**< Operation was rejected as invalid. */
247 : : /* Note: RTE_BBDEV_ENQ_STATUS_SIZE_MAX must be larger or equal to maximum enum value. */
248 : : };
249 : :
250 : : /**
251 : : * Flags to indicate the status of the device.
252 : : */
253 : : enum rte_bbdev_device_status {
254 : : RTE_BBDEV_DEV_NOSTATUS, /**< Nothing being reported. */
255 : : RTE_BBDEV_DEV_NOT_SUPPORTED, /**< Device status is not supported on the PMD. */
256 : : RTE_BBDEV_DEV_RESET, /**< Device in reset and un-configured state. */
257 : : RTE_BBDEV_DEV_CONFIGURED, /**< Device is configured and ready to use. */
258 : : RTE_BBDEV_DEV_ACTIVE, /**< Device is configured and VF is being used. */
259 : : RTE_BBDEV_DEV_FATAL_ERR, /**< Device has hit a fatal uncorrectable error. */
260 : : RTE_BBDEV_DEV_RESTART_REQ, /**< Device requires application to restart. */
261 : : RTE_BBDEV_DEV_RECONFIG_REQ, /**< Device requires application to reconfigure queues. */
262 : : RTE_BBDEV_DEV_CORRECT_ERR, /**< Warning of a correctable error event happened. */
263 : : };
264 : :
265 : : /** Device statistics. */
266 : : struct rte_bbdev_stats {
267 : : uint64_t enqueued_count; /**< Count of all operations enqueued */
268 : : uint64_t dequeued_count; /**< Count of all operations dequeued */
269 : : /** Total error count on operations enqueued */
270 : : uint64_t enqueue_err_count;
271 : : /** Total error count on operations dequeued */
272 : : uint64_t dequeue_err_count;
273 : : /** Total warning count on operations enqueued. */
274 : : uint64_t enqueue_warn_count;
275 : : /** Total warning count on operations dequeued. */
276 : : uint64_t dequeue_warn_count;
277 : : /** Total enqueue status count based on *rte_bbdev_enqueue_status* enum. */
278 : : uint64_t enqueue_status_count[RTE_BBDEV_ENQ_STATUS_SIZE_MAX];
279 : : /** CPU cycles consumed by the (HW/SW) accelerator device to offload
280 : : * the enqueue request to its internal queues.
281 : : * - For a HW device this is the cycles consumed in MMIO write
282 : : * - For a SW (vdev) device, this is the processing time of the
283 : : * bbdev operation
284 : : */
285 : : uint64_t acc_offload_cycles;
286 : : /** Available number of enqueue batch on that queue. */
287 : : uint16_t enqueue_depth_avail;
288 : : };
289 : :
290 : : /**
291 : : * Retrieve the general I/O statistics of a device.
292 : : *
293 : : * @param dev_id
294 : : * The identifier of the device.
295 : : * @param stats
296 : : * Pointer to structure to where statistics will be copied. On error, this
297 : : * location may or may not have been modified.
298 : : *
299 : : * @return
300 : : * - 0 on success
301 : : * - EINVAL if invalid parameter pointer is provided
302 : : */
303 : : int
304 : : rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats);
305 : :
306 : : /**
307 : : * Reset the statistics of a device.
308 : : *
309 : : * @param dev_id
310 : : * The identifier of the device.
311 : : * @return
312 : : * - 0 on success
313 : : */
314 : : int
315 : : rte_bbdev_stats_reset(uint16_t dev_id);
316 : :
317 : : /** Device information supplied by the device's driver */
318 : :
319 : : /* Structure rte_bbdev_driver_info 8< */
320 : : struct rte_bbdev_driver_info {
321 : : /** Driver name */
322 : : const char *driver_name;
323 : :
324 : : /** Maximum number of queues supported by the device */
325 : : unsigned int max_num_queues;
326 : : /** Maximum number of queues supported per operation type */
327 : : unsigned int num_queues[RTE_BBDEV_OP_TYPE_SIZE_MAX];
328 : : /** Priority level supported per operation type */
329 : : unsigned int queue_priority[RTE_BBDEV_OP_TYPE_SIZE_MAX];
330 : : /** Queue size limit (queue size must also be power of 2) */
331 : : uint32_t queue_size_lim;
332 : : /** Set if device off-loads operation to hardware */
333 : : bool hardware_accelerated;
334 : : /** Max value supported by queue priority for DL */
335 : : uint8_t max_dl_queue_priority;
336 : : /** Max value supported by queue priority for UL */
337 : : uint8_t max_ul_queue_priority;
338 : : /** Set if device supports per-queue interrupts */
339 : : bool queue_intr_supported;
340 : : /** Device Status */
341 : : enum rte_bbdev_device_status device_status;
342 : : /** HARQ memory available in kB */
343 : : uint32_t harq_buffer_size;
344 : : /** Minimum alignment of buffers, in bytes */
345 : : uint16_t min_alignment;
346 : : /** Byte endianness (RTE_BIG_ENDIAN/RTE_LITTLE_ENDIAN) supported
347 : : * for input/output data
348 : : */
349 : : uint8_t data_endianness;
350 : : /** Default queue configuration used if none is supplied */
351 : : struct rte_bbdev_queue_conf default_queue_conf;
352 : : /** Device operation capabilities */
353 : : const struct rte_bbdev_op_cap *capabilities;
354 : : /** Device cpu_flag requirements */
355 : : const enum rte_cpu_flag_t *cpu_flag_reqs;
356 : : /** FFT windowing width for 2048 FFT - size defined in capability. */
357 : : uint16_t *fft_window_width;
358 : : };
359 : : /* >8 End of structure rte_bbdev_driver_info. */
360 : :
361 : : /** Macro used at end of bbdev PMD list */
362 : : #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \
363 : : { RTE_BBDEV_OP_NONE }
364 : :
365 : : /**
366 : : * Device information structure used by an application to discover a devices
367 : : * capabilities and current configuration
368 : : */
369 : :
370 : : /* Structure rte_bbdev_info 8< */
371 : : struct rte_bbdev_info {
372 : : int socket_id; /**< NUMA socket that device is on */
373 : : const char *dev_name; /**< Unique device name */
374 : : const struct rte_device *device; /**< Device Information */
375 : : uint16_t num_queues; /**< Number of queues currently configured */
376 : : bool started; /**< Set if device is currently started */
377 : : struct rte_bbdev_driver_info drv; /**< Info from device driver */
378 : : };
379 : : /* >8 End of structure rte_bbdev_info. */
380 : :
381 : : /**
382 : : * Retrieve information about a device.
383 : : *
384 : : * @param dev_id
385 : : * The identifier of the device.
386 : : * @param dev_info
387 : : * Pointer to structure to where information will be copied. On error, this
388 : : * location may or may not have been modified.
389 : : *
390 : : * @return
391 : : * - 0 on success
392 : : * - EINVAL if invalid parameter pointer is provided
393 : : */
394 : : int
395 : : rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info);
396 : :
397 : : /** Queue information */
398 : : struct rte_bbdev_queue_info {
399 : : /** Current device configuration */
400 : : struct rte_bbdev_queue_conf conf;
401 : : /** Set if queue is currently started */
402 : : bool started;
403 : : };
404 : :
405 : : /**
406 : : * Retrieve information about a specific queue on a device.
407 : : *
408 : : * @param dev_id
409 : : * The identifier of the device.
410 : : * @param queue_id
411 : : * The index of the queue.
412 : : * @param queue_info
413 : : * Pointer to structure to where information will be copied. On error, this
414 : : * location may or may not have been modified.
415 : : *
416 : : * @return
417 : : * - 0 on success
418 : : * - EINVAL if invalid parameter pointer is provided
419 : : */
420 : : int
421 : : rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id,
422 : : struct rte_bbdev_queue_info *queue_info);
423 : :
424 : : /** @internal The data structure associated with each queue of a device. */
425 : : struct rte_bbdev_queue_data {
426 : : void *queue_private; /**< Driver-specific per-queue data */
427 : : struct rte_bbdev_queue_conf conf; /**< Current configuration */
428 : : struct rte_bbdev_stats queue_stats; /**< Queue statistics */
429 : : enum rte_bbdev_enqueue_status enqueue_status; /**< Enqueue status when op is rejected */
430 : : bool started; /**< Queue state */
431 : : };
432 : :
433 : : /** @internal Enqueue encode operations for processing on queue of a device. */
434 : : typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)(
435 : : struct rte_bbdev_queue_data *q_data,
436 : : struct rte_bbdev_enc_op **ops,
437 : : uint16_t num);
438 : :
439 : : /** @internal Enqueue decode operations for processing on queue of a device. */
440 : : typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)(
441 : : struct rte_bbdev_queue_data *q_data,
442 : : struct rte_bbdev_dec_op **ops,
443 : : uint16_t num);
444 : :
445 : : /** @internal Enqueue FFT operations for processing on queue of a device. */
446 : : typedef uint16_t (*rte_bbdev_enqueue_fft_ops_t)(
447 : : struct rte_bbdev_queue_data *q_data,
448 : : struct rte_bbdev_fft_op **ops,
449 : : uint16_t num);
450 : :
451 : : /** @internal Enqueue MLD-TS operations for processing on queue of a device. */
452 : : typedef uint16_t (*rte_bbdev_enqueue_mldts_ops_t)(
453 : : struct rte_bbdev_queue_data *q_data,
454 : : struct rte_bbdev_mldts_op **ops,
455 : : uint16_t num);
456 : :
457 : : /** @internal Dequeue encode operations from a queue of a device. */
458 : : typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)(
459 : : struct rte_bbdev_queue_data *q_data,
460 : : struct rte_bbdev_enc_op **ops, uint16_t num);
461 : :
462 : : /** @internal Dequeue decode operations from a queue of a device. */
463 : : typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)(
464 : : struct rte_bbdev_queue_data *q_data,
465 : : struct rte_bbdev_dec_op **ops, uint16_t num);
466 : :
467 : : /** @internal Dequeue FFT operations from a queue of a device. */
468 : : typedef uint16_t (*rte_bbdev_dequeue_fft_ops_t)(
469 : : struct rte_bbdev_queue_data *q_data,
470 : : struct rte_bbdev_fft_op **ops, uint16_t num);
471 : :
472 : : /** @internal Dequeue MLDTS operations from a queue of a device. */
473 : : typedef uint16_t (*rte_bbdev_dequeue_mldts_ops_t)(
474 : : struct rte_bbdev_queue_data *q_data,
475 : : struct rte_bbdev_mldts_op **ops, uint16_t num);
476 : :
477 : : #define RTE_BBDEV_NAME_MAX_LEN 64 /**< Max length of device name */
478 : :
479 : : /**
480 : : * @internal The data associated with a device, with no function pointers.
481 : : * This structure is safe to place in shared memory to be common among
482 : : * different processes in a multi-process configuration. Drivers can access
483 : : * these fields, but should never write to them!
484 : : */
485 : : struct rte_bbdev_data {
486 : : char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */
487 : : void *dev_private; /**< Driver-specific private data */
488 : : uint16_t num_queues; /**< Number of currently configured queues */
489 : : struct rte_bbdev_queue_data *queues; /**< Queue structures */
490 : : uint16_t dev_id; /**< Device ID */
491 : : int socket_id; /**< NUMA socket that device is on */
492 : : bool started; /**< Device run-time state */
493 : : RTE_ATOMIC(uint16_t) process_cnt; /** Counter of processes using the device */
494 : : };
495 : :
496 : : /* Forward declarations */
497 : : struct rte_bbdev_ops;
498 : : struct rte_bbdev_callback;
499 : : struct rte_intr_handle;
500 : :
501 : : /** Structure to keep track of registered callbacks */
502 : : RTE_TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback);
503 : :
504 : : /**
505 : : * @internal The data structure associated with a device. Drivers can access
506 : : * these fields, but should only write to the *_ops fields.
507 : : */
508 : : struct __rte_cache_aligned rte_bbdev {
509 : : /** Enqueue encode function */
510 : : rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops;
511 : : /** Enqueue decode function */
512 : : rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops;
513 : : /** Dequeue encode function */
514 : : rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops;
515 : : /** Dequeue decode function */
516 : : rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops;
517 : : /** Enqueue encode function */
518 : : rte_bbdev_enqueue_enc_ops_t enqueue_ldpc_enc_ops;
519 : : /** Enqueue decode function */
520 : : rte_bbdev_enqueue_dec_ops_t enqueue_ldpc_dec_ops;
521 : : /** Dequeue encode function */
522 : : rte_bbdev_dequeue_enc_ops_t dequeue_ldpc_enc_ops;
523 : : /** Dequeue decode function */
524 : : rte_bbdev_dequeue_dec_ops_t dequeue_ldpc_dec_ops;
525 : : /** Enqueue FFT function */
526 : : rte_bbdev_enqueue_fft_ops_t enqueue_fft_ops;
527 : : /** Dequeue FFT function */
528 : : rte_bbdev_dequeue_fft_ops_t dequeue_fft_ops;
529 : : const struct rte_bbdev_ops *dev_ops; /**< Functions exported by PMD */
530 : : struct rte_bbdev_data *data; /**< Pointer to device data */
531 : : enum rte_bbdev_state state; /**< If device is currently used or not */
532 : : struct rte_device *device; /**< Backing device */
533 : : /** User application callback for interrupts if present */
534 : : struct rte_bbdev_cb_list list_cbs;
535 : : struct rte_intr_handle *intr_handle; /**< Device interrupt handle */
536 : : /** Enqueue MLD-TS function */
537 : : rte_bbdev_enqueue_mldts_ops_t enqueue_mldts_ops;
538 : : /** Dequeue MLD-TS function */
539 : : rte_bbdev_dequeue_mldts_ops_t dequeue_mldts_ops;
540 : : };
541 : :
542 : : /** @internal array of all devices */
543 : : extern struct rte_bbdev rte_bbdev_devices[];
544 : :
545 : : /**
546 : : * Enqueue a burst of processed encode operations to a queue of the device.
547 : : * This functions only enqueues as many operations as currently possible and
548 : : * does not block until @p num_ops entries in the queue are available.
549 : : * This function does not provide any error notification to avoid the
550 : : * corresponding overhead.
551 : : *
552 : : * @param dev_id
553 : : * The identifier of the device.
554 : : * @param queue_id
555 : : * The index of the queue.
556 : : * @param ops
557 : : * Pointer array containing operations to be enqueued Must have at least
558 : : * @p num_ops entries
559 : : * @param num_ops
560 : : * The maximum number of operations to enqueue.
561 : : *
562 : : * @return
563 : : * The number of operations actually enqueued (this is the number of processed
564 : : * entries in the @p ops array).
565 : : */
566 : : static inline uint16_t
567 : : rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
568 : : struct rte_bbdev_enc_op **ops, uint16_t num_ops)
569 : : {
570 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
571 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
572 : 0 : return dev->enqueue_enc_ops(q_data, ops, num_ops);
573 : : }
574 : :
575 : : /**
576 : : * Enqueue a burst of processed decode operations to a queue of the device.
577 : : * This functions only enqueues as many operations as currently possible and
578 : : * does not block until @p num_ops entries in the queue are available.
579 : : * This function does not provide any error notification to avoid the
580 : : * corresponding overhead.
581 : : *
582 : : * @param dev_id
583 : : * The identifier of the device.
584 : : * @param queue_id
585 : : * The index of the queue.
586 : : * @param ops
587 : : * Pointer array containing operations to be enqueued Must have at least
588 : : * @p num_ops entries
589 : : * @param num_ops
590 : : * The maximum number of operations to enqueue.
591 : : *
592 : : * @return
593 : : * The number of operations actually enqueued (this is the number of processed
594 : : * entries in the @p ops array).
595 : : */
596 : : static inline uint16_t
597 : : rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
598 : : struct rte_bbdev_dec_op **ops, uint16_t num_ops)
599 : : {
600 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
601 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
602 : 0 : return dev->enqueue_dec_ops(q_data, ops, num_ops);
603 : : }
604 : :
605 : : /**
606 : : * Enqueue a burst of processed encode operations to a queue of the device.
607 : : * This functions only enqueues as many operations as currently possible and
608 : : * does not block until @p num_ops entries in the queue are available.
609 : : * This function does not provide any error notification to avoid the
610 : : * corresponding overhead.
611 : : *
612 : : * @param dev_id
613 : : * The identifier of the device.
614 : : * @param queue_id
615 : : * The index of the queue.
616 : : * @param ops
617 : : * Pointer array containing operations to be enqueued Must have at least
618 : : * @p num_ops entries
619 : : * @param num_ops
620 : : * The maximum number of operations to enqueue.
621 : : *
622 : : * @return
623 : : * The number of operations actually enqueued (this is the number of processed
624 : : * entries in the @p ops array).
625 : : */
626 : : static inline uint16_t
627 : : rte_bbdev_enqueue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id,
628 : : struct rte_bbdev_enc_op **ops, uint16_t num_ops)
629 : : {
630 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
631 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
632 : 0 : return dev->enqueue_ldpc_enc_ops(q_data, ops, num_ops);
633 : : }
634 : :
635 : : /**
636 : : * Enqueue a burst of processed decode operations to a queue of the device.
637 : : * This functions only enqueues as many operations as currently possible and
638 : : * does not block until @p num_ops entries in the queue are available.
639 : : * This function does not provide any error notification to avoid the
640 : : * corresponding overhead.
641 : : *
642 : : * @param dev_id
643 : : * The identifier of the device.
644 : : * @param queue_id
645 : : * The index of the queue.
646 : : * @param ops
647 : : * Pointer array containing operations to be enqueued Must have at least
648 : : * @p num_ops entries
649 : : * @param num_ops
650 : : * The maximum number of operations to enqueue.
651 : : *
652 : : * @return
653 : : * The number of operations actually enqueued (this is the number of processed
654 : : * entries in the @p ops array).
655 : : */
656 : : static inline uint16_t
657 : : rte_bbdev_enqueue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id,
658 : : struct rte_bbdev_dec_op **ops, uint16_t num_ops)
659 : : {
660 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
661 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
662 : 0 : return dev->enqueue_ldpc_dec_ops(q_data, ops, num_ops);
663 : : }
664 : :
665 : : /**
666 : : * Enqueue a burst of FFT operations to a queue of the device.
667 : : * This functions only enqueues as many operations as currently possible and
668 : : * does not block until @p num_ops entries in the queue are available.
669 : : * This function does not provide any error notification to avoid the
670 : : * corresponding overhead.
671 : : *
672 : : * @param dev_id
673 : : * The identifier of the device.
674 : : * @param queue_id
675 : : * The index of the queue.
676 : : * @param ops
677 : : * Pointer array containing operations to be enqueued.
678 : : * Must have at least @p num_ops entries.
679 : : * @param num_ops
680 : : * The maximum number of operations to enqueue.
681 : : *
682 : : * @return
683 : : * The number of operations actually enqueued.
684 : : * (This is the number of processed entries in the @p ops array.)
685 : : */
686 : : static inline uint16_t
687 : : rte_bbdev_enqueue_fft_ops(uint16_t dev_id, uint16_t queue_id,
688 : : struct rte_bbdev_fft_op **ops, uint16_t num_ops)
689 : : {
690 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
691 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
692 : 0 : return dev->enqueue_fft_ops(q_data, ops, num_ops);
693 : : }
694 : :
695 : : /**
696 : : * Enqueue a burst of MLDTS operations to a queue of the device.
697 : : * This functions only enqueues as many operations as currently possible and
698 : : * does not block until @p num_ops entries in the queue are available.
699 : : * This function does not provide any error notification to avoid the
700 : : * corresponding overhead.
701 : : *
702 : : * @param dev_id
703 : : * The identifier of the device.
704 : : * @param queue_id
705 : : * The index of the queue.
706 : : * @param ops
707 : : * Pointer array containing operations to be enqueued Must have at least
708 : : * @p num_ops entries
709 : : * @param num_ops
710 : : * The maximum number of operations to enqueue.
711 : : *
712 : : * @return
713 : : * The number of operations actually enqueued (this is the number of processed
714 : : * entries in the @p ops array).
715 : : */
716 : : static inline uint16_t
717 : : rte_bbdev_enqueue_mldts_ops(uint16_t dev_id, uint16_t queue_id,
718 : : struct rte_bbdev_mldts_op **ops, uint16_t num_ops)
719 : : {
720 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
721 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
722 : 0 : return dev->enqueue_mldts_ops(q_data, ops, num_ops);
723 : : }
724 : :
725 : : /**
726 : : * Dequeue a burst of processed encode operations from a queue of the device.
727 : : * This functions returns only the current contents of the queue,
728 : : * and does not block until @ num_ops is available.
729 : : * This function does not provide any error notification to avoid the
730 : : * corresponding overhead.
731 : : *
732 : : * @param dev_id
733 : : * The identifier of the device.
734 : : * @param queue_id
735 : : * The index of the queue.
736 : : * @param ops
737 : : * Pointer array where operations will be dequeued to.
738 : : * Must have at least @p num_ops entries, i.e.
739 : : * a pointer to a table of void * pointers (ops) that will be filled.
740 : : * @param num_ops
741 : : * The maximum number of operations to dequeue.
742 : : *
743 : : * @return
744 : : * The number of operations actually dequeued.
745 : : * (This is the number of entries copied into the @p ops array.)
746 : : */
747 : : static inline uint16_t
748 : : rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
749 : : struct rte_bbdev_enc_op **ops, uint16_t num_ops)
750 : : {
751 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
752 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
753 : 0 : return dev->dequeue_enc_ops(q_data, ops, num_ops);
754 : : }
755 : :
756 : : /**
757 : : * Dequeue a burst of processed decode operations from a queue of the device.
758 : : * This functions returns only the current contents of the queue, and does not
759 : : * block until @ num_ops is available.
760 : : * This function does not provide any error notification to avoid the
761 : : * corresponding overhead.
762 : : *
763 : : * @param dev_id
764 : : * The identifier of the device.
765 : : * @param queue_id
766 : : * The index of the queue.
767 : : * @param ops
768 : : * Pointer array where operations will be dequeued to. Must have at least
769 : : * @p num_ops entries
770 : : * ie. A pointer to a table of void * pointers (ops) that will be filled.
771 : : * @param num_ops
772 : : * The maximum number of operations to dequeue.
773 : : *
774 : : * @return
775 : : * The number of operations actually dequeued (this is the number of entries
776 : : * copied into the @p ops array).
777 : : */
778 : :
779 : : static inline uint16_t
780 : : rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
781 : : struct rte_bbdev_dec_op **ops, uint16_t num_ops)
782 : : {
783 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
784 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
785 : 0 : return dev->dequeue_dec_ops(q_data, ops, num_ops);
786 : : }
787 : :
788 : :
789 : : /**
790 : : * Dequeue a burst of processed encode operations from a queue of the device.
791 : : * This functions returns only the current contents of the queue, and does not
792 : : * block until @ num_ops is available.
793 : : * This function does not provide any error notification to avoid the
794 : : * corresponding overhead.
795 : : *
796 : : * @param dev_id
797 : : * The identifier of the device.
798 : : * @param queue_id
799 : : * The index of the queue.
800 : : * @param ops
801 : : * Pointer array where operations will be dequeued to. Must have at least
802 : : * @p num_ops entries
803 : : * @param num_ops
804 : : * The maximum number of operations to dequeue.
805 : : *
806 : : * @return
807 : : * The number of operations actually dequeued (this is the number of entries
808 : : * copied into the @p ops array).
809 : : */
810 : : static inline uint16_t
811 : : rte_bbdev_dequeue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id,
812 : : struct rte_bbdev_enc_op **ops, uint16_t num_ops)
813 : : {
814 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
815 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
816 : 0 : return dev->dequeue_ldpc_enc_ops(q_data, ops, num_ops);
817 : : }
818 : :
819 : : /**
820 : : * Dequeue a burst of processed decode operations from a queue of the device.
821 : : * This functions returns only the current contents of the queue, and does not
822 : : * block until @ num_ops is available.
823 : : * This function does not provide any error notification to avoid the
824 : : * corresponding overhead.
825 : : *
826 : : * @param dev_id
827 : : * The identifier of the device.
828 : : * @param queue_id
829 : : * The index of the queue.
830 : : * @param ops
831 : : * Pointer array where operations will be dequeued to. Must have at least
832 : : * @p num_ops entries
833 : : * @param num_ops
834 : : * The maximum number of operations to dequeue.
835 : : *
836 : : * @return
837 : : * The number of operations actually dequeued (this is the number of entries
838 : : * copied into the @p ops array).
839 : : */
840 : : static inline uint16_t
841 : : rte_bbdev_dequeue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id,
842 : : struct rte_bbdev_dec_op **ops, uint16_t num_ops)
843 : : {
844 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
845 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
846 : 0 : return dev->dequeue_ldpc_dec_ops(q_data, ops, num_ops);
847 : : }
848 : :
849 : : /**
850 : : * Dequeue a burst of FFT operations from a queue of the device.
851 : : * This functions returns only the current contents of the queue, and does not
852 : : * block until @ num_ops is available.
853 : : * This function does not provide any error notification to avoid the
854 : : * corresponding overhead.
855 : : *
856 : : * @param dev_id
857 : : * The identifier of the device.
858 : : * @param queue_id
859 : : * The index of the queue.
860 : : * @param ops
861 : : * Pointer array where operations will be dequeued to. Must have at least
862 : : * @p num_ops entries
863 : : * @param num_ops
864 : : * The maximum number of operations to dequeue.
865 : : *
866 : : * @return
867 : : * The number of operations actually dequeued (this is the number of entries
868 : : * copied into the @p ops array).
869 : : */
870 : : static inline uint16_t
871 : : rte_bbdev_dequeue_fft_ops(uint16_t dev_id, uint16_t queue_id,
872 : : struct rte_bbdev_fft_op **ops, uint16_t num_ops)
873 : : {
874 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
875 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
876 : 0 : return dev->dequeue_fft_ops(q_data, ops, num_ops);
877 : : }
878 : :
879 : : /**
880 : : * Dequeue a burst of MLDTS operations from a queue of the device.
881 : : * This functions returns only the current contents of the queue, and does not
882 : : * block until @p num_ops is available.
883 : : * This function does not provide any error notification to avoid the
884 : : * corresponding overhead.
885 : : *
886 : : * @param dev_id
887 : : * The identifier of the device.
888 : : * @param queue_id
889 : : * The index of the queue.
890 : : * @param ops
891 : : * Pointer array where operations will be dequeued to. Must have at least
892 : : * @p num_ops entries
893 : : * @param num_ops
894 : : * The maximum number of operations to dequeue.
895 : : *
896 : : * @return
897 : : * The number of operations actually dequeued (this is the number of entries
898 : : * copied into the @p ops array).
899 : : */
900 : : static inline uint16_t
901 : : rte_bbdev_dequeue_mldts_ops(uint16_t dev_id, uint16_t queue_id,
902 : : struct rte_bbdev_mldts_op **ops, uint16_t num_ops)
903 : : {
904 : : struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
905 : 0 : struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
906 : 0 : return dev->dequeue_mldts_ops(q_data, ops, num_ops);
907 : : }
908 : :
909 : : /** Definitions of device event types */
910 : : enum rte_bbdev_event_type {
911 : : RTE_BBDEV_EVENT_UNKNOWN, /**< unknown event type */
912 : : RTE_BBDEV_EVENT_ERROR, /**< error interrupt event */
913 : : RTE_BBDEV_EVENT_DEQUEUE, /**< dequeue event */
914 : : RTE_BBDEV_EVENT_MAX /**< max value of this enum */
915 : : };
916 : :
917 : : /**
918 : : * Typedef for application callback function registered by application
919 : : * software for notification of device events
920 : : *
921 : : * @param dev_id
922 : : * Device identifier
923 : : * @param event
924 : : * Device event to register for notification of.
925 : : * @param cb_arg
926 : : * User specified parameter to be passed to user's callback function.
927 : : * @param ret_param
928 : : * To pass data back to user application.
929 : : */
930 : : typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id,
931 : : enum rte_bbdev_event_type event, void *cb_arg,
932 : : void *ret_param);
933 : :
934 : : /**
935 : : * Register a callback function for specific device id. Multiple callbacks can
936 : : * be added and will be called in the order they are added when an event is
937 : : * triggered. Callbacks are called in a separate thread created by the DPDK EAL.
938 : : *
939 : : * @param dev_id
940 : : * Device id.
941 : : * @param event
942 : : * The event that the callback will be registered for.
943 : : * @param cb_fn
944 : : * User supplied callback function to be called.
945 : : * @param cb_arg
946 : : * Pointer to parameter that will be passed to the callback.
947 : : *
948 : : * @return
949 : : * Zero on success, negative value on failure.
950 : : */
951 : : int
952 : : rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event,
953 : : rte_bbdev_cb_fn cb_fn, void *cb_arg);
954 : :
955 : : /**
956 : : * Unregister a callback function for specific device id.
957 : : *
958 : : * @param dev_id
959 : : * The device identifier.
960 : : * @param event
961 : : * The event that the callback will be unregistered for.
962 : : * @param cb_fn
963 : : * User supplied callback function to be unregistered.
964 : : * @param cb_arg
965 : : * Pointer to the parameter supplied when registering the callback.
966 : : * (void *)-1 means to remove all registered callbacks with the specified
967 : : * function address.
968 : : *
969 : : * @return
970 : : * - 0 on success
971 : : * - EINVAL if invalid parameter pointer is provided
972 : : * - EAGAIN if the provided callback pointer does not exist
973 : : */
974 : : int
975 : : rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event,
976 : : rte_bbdev_cb_fn cb_fn, void *cb_arg);
977 : :
978 : : /**
979 : : * Enable a one-shot interrupt on the next operation enqueued to a particular
980 : : * queue. The interrupt will be triggered when the operation is ready to be
981 : : * dequeued. To handle the interrupt, an epoll file descriptor must be
982 : : * registered using rte_bbdev_queue_intr_ctl(), and then an application
983 : : * thread/lcore can wait for the interrupt using rte_epoll_wait().
984 : : *
985 : : * @param dev_id
986 : : * The device identifier.
987 : : * @param queue_id
988 : : * The index of the queue.
989 : : *
990 : : * @return
991 : : * - 0 on success
992 : : * - negative value on failure - as returned from PMD
993 : : */
994 : : int
995 : : rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id);
996 : :
997 : : /**
998 : : * Disable a one-shot interrupt on the next operation enqueued to a particular
999 : : * queue (if it has been enabled).
1000 : : *
1001 : : * @param dev_id
1002 : : * The device identifier.
1003 : : * @param queue_id
1004 : : * The index of the queue.
1005 : : *
1006 : : * @return
1007 : : * - 0 on success
1008 : : * - negative value on failure - as returned from PMD
1009 : : */
1010 : : int
1011 : : rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id);
1012 : :
1013 : : /**
1014 : : * Control interface for per-queue interrupts.
1015 : : *
1016 : : * @param dev_id
1017 : : * The device identifier.
1018 : : * @param queue_id
1019 : : * The index of the queue.
1020 : : * @param epfd
1021 : : * Epoll file descriptor that will be associated with the interrupt source.
1022 : : * If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll
1023 : : * file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also
1024 : : * be used when calling rte_epoll_wait()).
1025 : : * @param op
1026 : : * The operation be performed for the vector.RTE_INTR_EVENT_ADD or
1027 : : * RTE_INTR_EVENT_DEL.
1028 : : * @param data
1029 : : * User context, that will be returned in the epdata.data field of the
1030 : : * rte_epoll_event structure filled in by rte_epoll_wait().
1031 : : *
1032 : : * @return
1033 : : * - 0 on success
1034 : : * - ENOTSUP if interrupts are not supported by the identified device
1035 : : * - negative value on failure - as returned from PMD
1036 : : */
1037 : : int
1038 : : rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op,
1039 : : void *data);
1040 : :
1041 : : /**
1042 : : * Convert device status from enum to string.
1043 : : *
1044 : : * @param status
1045 : : * Device status as enum.
1046 : : *
1047 : : * @returns
1048 : : * Device status as string or NULL if invalid.
1049 : : */
1050 : : const char*
1051 : : rte_bbdev_device_status_str(enum rte_bbdev_device_status status);
1052 : :
1053 : : /**
1054 : : * Convert queue status from enum to string.
1055 : : *
1056 : : * @param status
1057 : : * Queue status as enum.
1058 : : *
1059 : : * @returns
1060 : : * Queue status as string or NULL if op_type is invalid.
1061 : : */
1062 : : const char*
1063 : : rte_bbdev_enqueue_status_str(enum rte_bbdev_enqueue_status status);
1064 : :
1065 : : /**
1066 : : * Dump operations info from device to a file.
1067 : : * This API is used for debugging provided input operations, not a dataplane API.
1068 : : *
1069 : : * @param dev_id
1070 : : * The device identifier.
1071 : : *
1072 : : * @param queue_index
1073 : : * Index of queue.
1074 : : *
1075 : : * @param file
1076 : : * A pointer to a file for output.
1077 : : *
1078 : : * @returns
1079 : : * - 0 on success
1080 : : * - ENOTSUP if interrupts are not supported by the identified device
1081 : : * - negative value on failure - as returned from PMD
1082 : : *
1083 : : */
1084 : : __rte_experimental
1085 : : int
1086 : : rte_bbdev_queue_ops_dump(uint16_t dev_id, uint16_t queue_index, FILE *file);
1087 : :
1088 : :
1089 : : /**
1090 : : * String of parameters related to the parameters of an operation of a given type.
1091 : : *
1092 : : * @param op
1093 : : * Pointer to an operation.
1094 : : *
1095 : : * @param op_type
1096 : : * Operation type enum.
1097 : : *
1098 : : * @param str
1099 : : * String being describing the operations.
1100 : : *
1101 : : * @param len
1102 : : * Size of the string buffer.
1103 : : *
1104 : : * @returns
1105 : : * String describing the provided operation.
1106 : : *
1107 : : */
1108 : : __rte_experimental
1109 : : char *
1110 : : rte_bbdev_ops_param_string(void *op, enum rte_bbdev_op_type op_type, char *str, uint32_t len);
1111 : :
1112 : : #ifdef __cplusplus
1113 : : }
1114 : : #endif
1115 : :
1116 : : #endif /* _RTE_BBDEV_H_ */
|
