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 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #include <stdint.h> 28 #include <stdbool.h> 29 30 #include <rte_compat.h> 31 #include <rte_cpuflags.h> 32 33 #include "rte_bbdev_op.h" 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 }; 287 288 /** 289 * Retrieve the general I/O statistics of a device. 290 * 291 * @param dev_id 292 * The identifier of the device. 293 * @param stats 294 * Pointer to structure to where statistics will be copied. On error, this 295 * location may or may not have been modified. 296 * 297 * @return 298 * - 0 on success 299 * - EINVAL if invalid parameter pointer is provided 300 */ 301 int 302 rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats); 303 304 /** 305 * Reset the statistics of a device. 306 * 307 * @param dev_id 308 * The identifier of the device. 309 * @return 310 * - 0 on success 311 */ 312 int 313 rte_bbdev_stats_reset(uint16_t dev_id); 314 315 /** Device information supplied by the device's driver */ 316 struct rte_bbdev_driver_info { 317 /** Driver name */ 318 const char *driver_name; 319 320 /** Maximum number of queues supported by the device */ 321 unsigned int max_num_queues; 322 /** Maximum number of queues supported per operation type */ 323 unsigned int num_queues[RTE_BBDEV_OP_TYPE_SIZE_MAX]; 324 /** Priority level supported per operation type */ 325 unsigned int queue_priority[RTE_BBDEV_OP_TYPE_SIZE_MAX]; 326 /** Queue size limit (queue size must also be power of 2) */ 327 uint32_t queue_size_lim; 328 /** Set if device off-loads operation to hardware */ 329 bool hardware_accelerated; 330 /** Max value supported by queue priority for DL */ 331 uint8_t max_dl_queue_priority; 332 /** Max value supported by queue priority for UL */ 333 uint8_t max_ul_queue_priority; 334 /** Set if device supports per-queue interrupts */ 335 bool queue_intr_supported; 336 /** Device Status */ 337 enum rte_bbdev_device_status device_status; 338 /** HARQ memory available in kB */ 339 uint32_t harq_buffer_size; 340 /** Minimum alignment of buffers, in bytes */ 341 uint16_t min_alignment; 342 /** Byte endianness (RTE_BIG_ENDIAN/RTE_LITTLE_ENDIAN) supported 343 * for input/output data 344 */ 345 uint8_t data_endianness; 346 /** Default queue configuration used if none is supplied */ 347 struct rte_bbdev_queue_conf default_queue_conf; 348 /** Device operation capabilities */ 349 const struct rte_bbdev_op_cap *capabilities; 350 /** Device cpu_flag requirements */ 351 const enum rte_cpu_flag_t *cpu_flag_reqs; 352 }; 353 354 /** Macro used at end of bbdev PMD list */ 355 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \ 356 { RTE_BBDEV_OP_NONE } 357 358 /** 359 * Device information structure used by an application to discover a devices 360 * capabilities and current configuration 361 */ 362 struct rte_bbdev_info { 363 int socket_id; /**< NUMA socket that device is on */ 364 const char *dev_name; /**< Unique device name */ 365 const struct rte_device *device; /**< Device Information */ 366 uint16_t num_queues; /**< Number of queues currently configured */ 367 bool started; /**< Set if device is currently started */ 368 struct rte_bbdev_driver_info drv; /**< Info from device driver */ 369 }; 370 371 /** 372 * Retrieve information about a device. 373 * 374 * @param dev_id 375 * The identifier of the device. 376 * @param dev_info 377 * Pointer to structure to where information will be copied. On error, this 378 * location may or may not have been modified. 379 * 380 * @return 381 * - 0 on success 382 * - EINVAL if invalid parameter pointer is provided 383 */ 384 int 385 rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info); 386 387 /** Queue information */ 388 struct rte_bbdev_queue_info { 389 /** Current device configuration */ 390 struct rte_bbdev_queue_conf conf; 391 /** Set if queue is currently started */ 392 bool started; 393 }; 394 395 /** 396 * Retrieve information about a specific queue on a device. 397 * 398 * @param dev_id 399 * The identifier of the device. 400 * @param queue_id 401 * The index of the queue. 402 * @param queue_info 403 * Pointer to structure to where information will be copied. On error, this 404 * location may or may not have been modified. 405 * 406 * @return 407 * - 0 on success 408 * - EINVAL if invalid parameter pointer is provided 409 */ 410 int 411 rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id, 412 struct rte_bbdev_queue_info *queue_info); 413 414 /** @internal The data structure associated with each queue of a device. */ 415 struct rte_bbdev_queue_data { 416 void *queue_private; /**< Driver-specific per-queue data */ 417 struct rte_bbdev_queue_conf conf; /**< Current configuration */ 418 struct rte_bbdev_stats queue_stats; /**< Queue statistics */ 419 enum rte_bbdev_enqueue_status enqueue_status; /**< Enqueue status when op is rejected */ 420 bool started; /**< Queue state */ 421 }; 422 423 /** @internal Enqueue encode operations for processing on queue of a device. */ 424 typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)( 425 struct rte_bbdev_queue_data *q_data, 426 struct rte_bbdev_enc_op **ops, 427 uint16_t num); 428 429 /** @internal Enqueue decode operations for processing on queue of a device. */ 430 typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)( 431 struct rte_bbdev_queue_data *q_data, 432 struct rte_bbdev_dec_op **ops, 433 uint16_t num); 434 435 /** @internal Enqueue FFT operations for processing on queue of a device. */ 436 typedef uint16_t (*rte_bbdev_enqueue_fft_ops_t)( 437 struct rte_bbdev_queue_data *q_data, 438 struct rte_bbdev_fft_op **ops, 439 uint16_t num); 440 441 /** @internal Enqueue MLD-TS operations for processing on queue of a device. */ 442 typedef uint16_t (*rte_bbdev_enqueue_mldts_ops_t)( 443 struct rte_bbdev_queue_data *q_data, 444 struct rte_bbdev_mldts_op **ops, 445 uint16_t num); 446 447 /** @internal Dequeue encode operations from a queue of a device. */ 448 typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)( 449 struct rte_bbdev_queue_data *q_data, 450 struct rte_bbdev_enc_op **ops, uint16_t num); 451 452 /** @internal Dequeue decode operations from a queue of a device. */ 453 typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)( 454 struct rte_bbdev_queue_data *q_data, 455 struct rte_bbdev_dec_op **ops, uint16_t num); 456 457 /** @internal Dequeue FFT operations from a queue of a device. */ 458 typedef uint16_t (*rte_bbdev_dequeue_fft_ops_t)( 459 struct rte_bbdev_queue_data *q_data, 460 struct rte_bbdev_fft_op **ops, uint16_t num); 461 462 /** @internal Dequeue MLDTS operations from a queue of a device. */ 463 typedef uint16_t (*rte_bbdev_dequeue_mldts_ops_t)( 464 struct rte_bbdev_queue_data *q_data, 465 struct rte_bbdev_mldts_op **ops, uint16_t num); 466 467 #define RTE_BBDEV_NAME_MAX_LEN 64 /**< Max length of device name */ 468 469 /** 470 * @internal The data associated with a device, with no function pointers. 471 * This structure is safe to place in shared memory to be common among 472 * different processes in a multi-process configuration. Drivers can access 473 * these fields, but should never write to them! 474 */ 475 struct rte_bbdev_data { 476 char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */ 477 void *dev_private; /**< Driver-specific private data */ 478 uint16_t num_queues; /**< Number of currently configured queues */ 479 struct rte_bbdev_queue_data *queues; /**< Queue structures */ 480 uint16_t dev_id; /**< Device ID */ 481 int socket_id; /**< NUMA socket that device is on */ 482 bool started; /**< Device run-time state */ 483 uint16_t process_cnt; /** Counter of processes using the device */ 484 }; 485 486 /* Forward declarations */ 487 struct rte_bbdev_ops; 488 struct rte_bbdev_callback; 489 struct rte_intr_handle; 490 491 /** Structure to keep track of registered callbacks */ 492 RTE_TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback); 493 494 /** 495 * @internal The data structure associated with a device. Drivers can access 496 * these fields, but should only write to the *_ops fields. 497 */ 498 struct __rte_cache_aligned rte_bbdev { 499 /** Enqueue encode function */ 500 rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops; 501 /** Enqueue decode function */ 502 rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops; 503 /** Dequeue encode function */ 504 rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops; 505 /** Dequeue decode function */ 506 rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops; 507 /** Enqueue encode function */ 508 rte_bbdev_enqueue_enc_ops_t enqueue_ldpc_enc_ops; 509 /** Enqueue decode function */ 510 rte_bbdev_enqueue_dec_ops_t enqueue_ldpc_dec_ops; 511 /** Dequeue encode function */ 512 rte_bbdev_dequeue_enc_ops_t dequeue_ldpc_enc_ops; 513 /** Dequeue decode function */ 514 rte_bbdev_dequeue_dec_ops_t dequeue_ldpc_dec_ops; 515 /** Enqueue FFT function */ 516 rte_bbdev_enqueue_fft_ops_t enqueue_fft_ops; 517 /** Dequeue FFT function */ 518 rte_bbdev_dequeue_fft_ops_t dequeue_fft_ops; 519 const struct rte_bbdev_ops *dev_ops; /**< Functions exported by PMD */ 520 struct rte_bbdev_data *data; /**< Pointer to device data */ 521 enum rte_bbdev_state state; /**< If device is currently used or not */ 522 struct rte_device *device; /**< Backing device */ 523 /** User application callback for interrupts if present */ 524 struct rte_bbdev_cb_list list_cbs; 525 struct rte_intr_handle *intr_handle; /**< Device interrupt handle */ 526 /** Enqueue MLD-TS function */ 527 rte_bbdev_enqueue_mldts_ops_t enqueue_mldts_ops; 528 /** Dequeue MLD-TS function */ 529 rte_bbdev_dequeue_mldts_ops_t dequeue_mldts_ops; 530 }; 531 532 /** @internal array of all devices */ 533 extern struct rte_bbdev rte_bbdev_devices[]; 534 535 /** 536 * Enqueue a burst of processed encode operations to a queue of the device. 537 * This functions only enqueues as many operations as currently possible and 538 * does not block until @p num_ops entries in the queue are available. 539 * This function does not provide any error notification to avoid the 540 * corresponding overhead. 541 * 542 * @param dev_id 543 * The identifier of the device. 544 * @param queue_id 545 * The index of the queue. 546 * @param ops 547 * Pointer array containing operations to be enqueued Must have at least 548 * @p num_ops entries 549 * @param num_ops 550 * The maximum number of operations to enqueue. 551 * 552 * @return 553 * The number of operations actually enqueued (this is the number of processed 554 * entries in the @p ops array). 555 */ 556 static inline uint16_t 557 rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id, 558 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 559 { 560 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 561 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 562 return dev->enqueue_enc_ops(q_data, ops, num_ops); 563 } 564 565 /** 566 * Enqueue a burst of processed decode operations to a queue of the device. 567 * This functions only enqueues as many operations as currently possible and 568 * does not block until @p num_ops entries in the queue are available. 569 * This function does not provide any error notification to avoid the 570 * corresponding overhead. 571 * 572 * @param dev_id 573 * The identifier of the device. 574 * @param queue_id 575 * The index of the queue. 576 * @param ops 577 * Pointer array containing operations to be enqueued Must have at least 578 * @p num_ops entries 579 * @param num_ops 580 * The maximum number of operations to enqueue. 581 * 582 * @return 583 * The number of operations actually enqueued (this is the number of processed 584 * entries in the @p ops array). 585 */ 586 static inline uint16_t 587 rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id, 588 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 589 { 590 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 591 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 592 return dev->enqueue_dec_ops(q_data, ops, num_ops); 593 } 594 595 /** 596 * Enqueue a burst of processed encode operations to a queue of the device. 597 * This functions only enqueues as many operations as currently possible and 598 * does not block until @p num_ops entries in the queue are available. 599 * This function does not provide any error notification to avoid the 600 * corresponding overhead. 601 * 602 * @param dev_id 603 * The identifier of the device. 604 * @param queue_id 605 * The index of the queue. 606 * @param ops 607 * Pointer array containing operations to be enqueued Must have at least 608 * @p num_ops entries 609 * @param num_ops 610 * The maximum number of operations to enqueue. 611 * 612 * @return 613 * The number of operations actually enqueued (this is the number of processed 614 * entries in the @p ops array). 615 */ 616 static inline uint16_t 617 rte_bbdev_enqueue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id, 618 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 619 { 620 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 621 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 622 return dev->enqueue_ldpc_enc_ops(q_data, ops, num_ops); 623 } 624 625 /** 626 * Enqueue a burst of processed decode operations to a queue of the device. 627 * This functions only enqueues as many operations as currently possible and 628 * does not block until @p num_ops entries in the queue are available. 629 * This function does not provide any error notification to avoid the 630 * corresponding overhead. 631 * 632 * @param dev_id 633 * The identifier of the device. 634 * @param queue_id 635 * The index of the queue. 636 * @param ops 637 * Pointer array containing operations to be enqueued Must have at least 638 * @p num_ops entries 639 * @param num_ops 640 * The maximum number of operations to enqueue. 641 * 642 * @return 643 * The number of operations actually enqueued (this is the number of processed 644 * entries in the @p ops array). 645 */ 646 static inline uint16_t 647 rte_bbdev_enqueue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id, 648 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 649 { 650 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 651 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 652 return dev->enqueue_ldpc_dec_ops(q_data, ops, num_ops); 653 } 654 655 /** 656 * Enqueue a burst of FFT operations to a queue of the device. 657 * This functions only enqueues as many operations as currently possible and 658 * does not block until @p num_ops entries in the queue are available. 659 * This function does not provide any error notification to avoid the 660 * corresponding overhead. 661 * 662 * @param dev_id 663 * The identifier of the device. 664 * @param queue_id 665 * The index of the queue. 666 * @param ops 667 * Pointer array containing operations to be enqueued. 668 * Must have at least @p num_ops entries. 669 * @param num_ops 670 * The maximum number of operations to enqueue. 671 * 672 * @return 673 * The number of operations actually enqueued. 674 * (This is the number of processed entries in the @p ops array.) 675 */ 676 __rte_experimental 677 static inline uint16_t 678 rte_bbdev_enqueue_fft_ops(uint16_t dev_id, uint16_t queue_id, 679 struct rte_bbdev_fft_op **ops, uint16_t num_ops) 680 { 681 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 682 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 683 return dev->enqueue_fft_ops(q_data, ops, num_ops); 684 } 685 686 /** 687 * Enqueue a burst of MLDTS operations to a queue of the device. 688 * This functions only enqueues as many operations as currently possible and 689 * does not block until @p num_ops entries in the queue are available. 690 * This function does not provide any error notification to avoid the 691 * corresponding overhead. 692 * 693 * @param dev_id 694 * The identifier of the device. 695 * @param queue_id 696 * The index of the queue. 697 * @param ops 698 * Pointer array containing operations to be enqueued Must have at least 699 * @p num_ops entries 700 * @param num_ops 701 * The maximum number of operations to enqueue. 702 * 703 * @return 704 * The number of operations actually enqueued (this is the number of processed 705 * entries in the @p ops array). 706 */ 707 static inline uint16_t 708 rte_bbdev_enqueue_mldts_ops(uint16_t dev_id, uint16_t queue_id, 709 struct rte_bbdev_mldts_op **ops, uint16_t num_ops) 710 { 711 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 712 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 713 return dev->enqueue_mldts_ops(q_data, ops, num_ops); 714 } 715 716 /** 717 * Dequeue a burst of processed encode operations from a queue of the device. 718 * This functions returns only the current contents of the queue, 719 * and does not block until @ num_ops is available. 720 * This function does not provide any error notification to avoid the 721 * corresponding overhead. 722 * 723 * @param dev_id 724 * The identifier of the device. 725 * @param queue_id 726 * The index of the queue. 727 * @param ops 728 * Pointer array where operations will be dequeued to. 729 * Must have at least @p num_ops entries, i.e. 730 * a pointer to a table of void * pointers (ops) that will be filled. 731 * @param num_ops 732 * The maximum number of operations to dequeue. 733 * 734 * @return 735 * The number of operations actually dequeued. 736 * (This is the number of entries copied into the @p ops array.) 737 */ 738 static inline uint16_t 739 rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id, 740 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 741 { 742 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 743 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 744 return dev->dequeue_enc_ops(q_data, ops, num_ops); 745 } 746 747 /** 748 * Dequeue a burst of processed decode operations from a queue of the device. 749 * This functions returns only the current contents of the queue, and does not 750 * block until @ num_ops is available. 751 * This function does not provide any error notification to avoid the 752 * corresponding overhead. 753 * 754 * @param dev_id 755 * The identifier of the device. 756 * @param queue_id 757 * The index of the queue. 758 * @param ops 759 * Pointer array where operations will be dequeued to. Must have at least 760 * @p num_ops entries 761 * ie. A pointer to a table of void * pointers (ops) that will be filled. 762 * @param num_ops 763 * The maximum number of operations to dequeue. 764 * 765 * @return 766 * The number of operations actually dequeued (this is the number of entries 767 * copied into the @p ops array). 768 */ 769 770 static inline uint16_t 771 rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id, 772 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 773 { 774 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 775 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 776 return dev->dequeue_dec_ops(q_data, ops, num_ops); 777 } 778 779 780 /** 781 * Dequeue a burst of processed encode operations from a queue of the device. 782 * This functions returns only the current contents of the queue, and does not 783 * block until @ num_ops is available. 784 * This function does not provide any error notification to avoid the 785 * corresponding overhead. 786 * 787 * @param dev_id 788 * The identifier of the device. 789 * @param queue_id 790 * The index of the queue. 791 * @param ops 792 * Pointer array where operations will be dequeued to. Must have at least 793 * @p num_ops entries 794 * @param num_ops 795 * The maximum number of operations to dequeue. 796 * 797 * @return 798 * The number of operations actually dequeued (this is the number of entries 799 * copied into the @p ops array). 800 */ 801 static inline uint16_t 802 rte_bbdev_dequeue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id, 803 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 804 { 805 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 806 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 807 return dev->dequeue_ldpc_enc_ops(q_data, ops, num_ops); 808 } 809 810 /** 811 * Dequeue a burst of processed decode operations from a queue of the device. 812 * This functions returns only the current contents of the queue, and does not 813 * block until @ num_ops is available. 814 * This function does not provide any error notification to avoid the 815 * corresponding overhead. 816 * 817 * @param dev_id 818 * The identifier of the device. 819 * @param queue_id 820 * The index of the queue. 821 * @param ops 822 * Pointer array where operations will be dequeued to. Must have at least 823 * @p num_ops entries 824 * @param num_ops 825 * The maximum number of operations to dequeue. 826 * 827 * @return 828 * The number of operations actually dequeued (this is the number of entries 829 * copied into the @p ops array). 830 */ 831 static inline uint16_t 832 rte_bbdev_dequeue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id, 833 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 834 { 835 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 836 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 837 return dev->dequeue_ldpc_dec_ops(q_data, ops, num_ops); 838 } 839 840 /** 841 * Dequeue a burst of FFT operations from a queue of the device. 842 * This functions returns only the current contents of the queue, and does not 843 * block until @ num_ops is available. 844 * This function does not provide any error notification to avoid the 845 * corresponding overhead. 846 * 847 * @param dev_id 848 * The identifier of the device. 849 * @param queue_id 850 * The index of the queue. 851 * @param ops 852 * Pointer array where operations will be dequeued to. Must have at least 853 * @p num_ops entries 854 * @param num_ops 855 * The maximum number of operations to dequeue. 856 * 857 * @return 858 * The number of operations actually dequeued (this is the number of entries 859 * copied into the @p ops array). 860 */ 861 __rte_experimental 862 static inline uint16_t 863 rte_bbdev_dequeue_fft_ops(uint16_t dev_id, uint16_t queue_id, 864 struct rte_bbdev_fft_op **ops, uint16_t num_ops) 865 { 866 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 867 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 868 return dev->dequeue_fft_ops(q_data, ops, num_ops); 869 } 870 871 /** 872 * Dequeue a burst of MLDTS operations from a queue of the device. 873 * This functions returns only the current contents of the queue, and does not 874 * block until @p num_ops is available. 875 * This function does not provide any error notification to avoid the 876 * corresponding overhead. 877 * 878 * @param dev_id 879 * The identifier of the device. 880 * @param queue_id 881 * The index of the queue. 882 * @param ops 883 * Pointer array where operations will be dequeued to. Must have at least 884 * @p num_ops entries 885 * @param num_ops 886 * The maximum number of operations to dequeue. 887 * 888 * @return 889 * The number of operations actually dequeued (this is the number of entries 890 * copied into the @p ops array). 891 */ 892 __rte_experimental 893 static inline uint16_t 894 rte_bbdev_dequeue_mldts_ops(uint16_t dev_id, uint16_t queue_id, 895 struct rte_bbdev_mldts_op **ops, uint16_t num_ops) 896 { 897 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 898 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 899 return dev->dequeue_mldts_ops(q_data, ops, num_ops); 900 } 901 902 /** Definitions of device event types */ 903 enum rte_bbdev_event_type { 904 RTE_BBDEV_EVENT_UNKNOWN, /**< unknown event type */ 905 RTE_BBDEV_EVENT_ERROR, /**< error interrupt event */ 906 RTE_BBDEV_EVENT_DEQUEUE, /**< dequeue event */ 907 RTE_BBDEV_EVENT_MAX /**< max value of this enum */ 908 }; 909 910 /** 911 * Typedef for application callback function registered by application 912 * software for notification of device events 913 * 914 * @param dev_id 915 * Device identifier 916 * @param event 917 * Device event to register for notification of. 918 * @param cb_arg 919 * User specified parameter to be passed to user's callback function. 920 * @param ret_param 921 * To pass data back to user application. 922 */ 923 typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id, 924 enum rte_bbdev_event_type event, void *cb_arg, 925 void *ret_param); 926 927 /** 928 * Register a callback function for specific device id. Multiple callbacks can 929 * be added and will be called in the order they are added when an event is 930 * triggered. Callbacks are called in a separate thread created by the DPDK EAL. 931 * 932 * @param dev_id 933 * Device id. 934 * @param event 935 * The event that the callback will be registered for. 936 * @param cb_fn 937 * User supplied callback function to be called. 938 * @param cb_arg 939 * Pointer to parameter that will be passed to the callback. 940 * 941 * @return 942 * Zero on success, negative value on failure. 943 */ 944 int 945 rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event, 946 rte_bbdev_cb_fn cb_fn, void *cb_arg); 947 948 /** 949 * Unregister a callback function for specific device id. 950 * 951 * @param dev_id 952 * The device identifier. 953 * @param event 954 * The event that the callback will be unregistered for. 955 * @param cb_fn 956 * User supplied callback function to be unregistered. 957 * @param cb_arg 958 * Pointer to the parameter supplied when registering the callback. 959 * (void *)-1 means to remove all registered callbacks with the specified 960 * function address. 961 * 962 * @return 963 * - 0 on success 964 * - EINVAL if invalid parameter pointer is provided 965 * - EAGAIN if the provided callback pointer does not exist 966 */ 967 int 968 rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event, 969 rte_bbdev_cb_fn cb_fn, void *cb_arg); 970 971 /** 972 * Enable a one-shot interrupt on the next operation enqueued to a particular 973 * queue. The interrupt will be triggered when the operation is ready to be 974 * dequeued. To handle the interrupt, an epoll file descriptor must be 975 * registered using rte_bbdev_queue_intr_ctl(), and then an application 976 * thread/lcore can wait for the interrupt using rte_epoll_wait(). 977 * 978 * @param dev_id 979 * The device identifier. 980 * @param queue_id 981 * The index of the queue. 982 * 983 * @return 984 * - 0 on success 985 * - negative value on failure - as returned from PMD 986 */ 987 int 988 rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id); 989 990 /** 991 * Disable a one-shot interrupt on the next operation enqueued to a particular 992 * queue (if it has been enabled). 993 * 994 * @param dev_id 995 * The device identifier. 996 * @param queue_id 997 * The index of the queue. 998 * 999 * @return 1000 * - 0 on success 1001 * - negative value on failure - as returned from PMD 1002 */ 1003 int 1004 rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id); 1005 1006 /** 1007 * Control interface for per-queue interrupts. 1008 * 1009 * @param dev_id 1010 * The device identifier. 1011 * @param queue_id 1012 * The index of the queue. 1013 * @param epfd 1014 * Epoll file descriptor that will be associated with the interrupt source. 1015 * If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll 1016 * file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also 1017 * be used when calling rte_epoll_wait()). 1018 * @param op 1019 * The operation be performed for the vector.RTE_INTR_EVENT_ADD or 1020 * RTE_INTR_EVENT_DEL. 1021 * @param data 1022 * User context, that will be returned in the epdata.data field of the 1023 * rte_epoll_event structure filled in by rte_epoll_wait(). 1024 * 1025 * @return 1026 * - 0 on success 1027 * - ENOTSUP if interrupts are not supported by the identified device 1028 * - negative value on failure - as returned from PMD 1029 */ 1030 int 1031 rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op, 1032 void *data); 1033 1034 /** 1035 * Convert device status from enum to string. 1036 * 1037 * @param status 1038 * Device status as enum. 1039 * 1040 * @returns 1041 * Device status as string or NULL if invalid. 1042 */ 1043 __rte_experimental 1044 const char* 1045 rte_bbdev_device_status_str(enum rte_bbdev_device_status status); 1046 1047 /** 1048 * Convert queue status from enum to string. 1049 * 1050 * @param status 1051 * Queue status as enum. 1052 * 1053 * @returns 1054 * Queue status as string or NULL if op_type is invalid. 1055 */ 1056 __rte_experimental 1057 const char* 1058 rte_bbdev_enqueue_status_str(enum rte_bbdev_enqueue_status status); 1059 1060 #ifdef __cplusplus 1061 } 1062 #endif 1063 1064 #endif /* _RTE_BBDEV_H_ */ 1065