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 * @warning 14 * @b EXPERIMENTAL: this API may change without prior notice 15 * 16 * This API allows an application to discover, configure and use a device to 17 * process operations. An asynchronous API (enqueue, followed by later dequeue) 18 * is used for processing operations. 19 * 20 * The functions in this API are not thread-safe when called on the same 21 * target object (a device, or a queue on a device), with the exception that 22 * one thread can enqueue operations to a queue while another thread dequeues 23 * from the same queue. 24 */ 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #include <stdint.h> 31 #include <stdbool.h> 32 #include <string.h> 33 34 #include <rte_compat.h> 35 #include <rte_atomic.h> 36 #include <rte_bus.h> 37 #include <rte_cpuflags.h> 38 #include <rte_memory.h> 39 40 #include "rte_bbdev_op.h" 41 42 #ifndef RTE_BBDEV_MAX_DEVS 43 #define RTE_BBDEV_MAX_DEVS 128 /**< Max number of devices */ 44 #endif 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 __rte_experimental 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 __rte_experimental 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 __rte_experimental 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 __rte_experimental 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 __rte_experimental 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 __rte_experimental 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 enqueuing 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 driver 172 */ 173 int __rte_experimental 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 __rte_experimental 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 __rte_experimental 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 driver 215 */ 216 int __rte_experimental 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 driver 230 */ 231 int __rte_experimental 232 rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id); 233 234 /** Device statistics. */ 235 struct rte_bbdev_stats { 236 uint64_t enqueued_count; /**< Count of all operations enqueued */ 237 uint64_t dequeued_count; /**< Count of all operations dequeued */ 238 /** Total error count on operations enqueued */ 239 uint64_t enqueue_err_count; 240 /** Total error count on operations dequeued */ 241 uint64_t dequeue_err_count; 242 /** Offload time */ 243 uint64_t offload_time; 244 }; 245 246 /** 247 * Retrieve the general I/O statistics of a device. 248 * 249 * @param dev_id 250 * The identifier of the device. 251 * @param stats 252 * Pointer to structure to where statistics will be copied. On error, this 253 * location may or may not have been modified. 254 * 255 * @return 256 * - 0 on success 257 * - EINVAL if invalid parameter pointer is provided 258 */ 259 int __rte_experimental 260 rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats); 261 262 /** 263 * Reset the statistics of a device. 264 * 265 * @param dev_id 266 * The identifier of the device. 267 * @return 268 * - 0 on success 269 */ 270 int __rte_experimental 271 rte_bbdev_stats_reset(uint16_t dev_id); 272 273 /** Device information supplied by the device's driver */ 274 struct rte_bbdev_driver_info { 275 /** Driver name */ 276 const char *driver_name; 277 278 /** Maximum number of queues supported by the device */ 279 unsigned int max_num_queues; 280 /** Queue size limit (queue size must also be power of 2) */ 281 uint32_t queue_size_lim; 282 /** Set if device off-loads operation to hardware */ 283 bool hardware_accelerated; 284 /** Max value supported by queue priority for DL */ 285 uint8_t max_dl_queue_priority; 286 /** Max value supported by queue priority for UL */ 287 uint8_t max_ul_queue_priority; 288 /** Set if device supports per-queue interrupts */ 289 bool queue_intr_supported; 290 /** Minimum alignment of buffers, in bytes */ 291 uint16_t min_alignment; 292 /** Default queue configuration used if none is supplied */ 293 struct rte_bbdev_queue_conf default_queue_conf; 294 /** Device operation capabilities */ 295 const struct rte_bbdev_op_cap *capabilities; 296 /** Device cpu_flag requirements */ 297 const enum rte_cpu_flag_t *cpu_flag_reqs; 298 }; 299 300 /** Macro used at end of bbdev PMD list */ 301 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \ 302 { RTE_BBDEV_OP_NONE } 303 304 /** 305 * Device information structure used by an application to discover a devices 306 * capabilities and current configuration 307 */ 308 struct rte_bbdev_info { 309 int socket_id; /**< NUMA socket that device is on */ 310 const char *dev_name; /**< Unique device name */ 311 const struct rte_bus *bus; /**< Bus information */ 312 uint16_t num_queues; /**< Number of queues currently configured */ 313 bool started; /**< Set if device is currently started */ 314 struct rte_bbdev_driver_info drv; /**< Info from device driver */ 315 }; 316 317 /** 318 * Retrieve information about a device. 319 * 320 * @param dev_id 321 * The identifier of the device. 322 * @param dev_info 323 * Pointer to structure to where information will be copied. On error, this 324 * location may or may not have been modified. 325 * 326 * @return 327 * - 0 on success 328 * - EINVAL if invalid parameter pointer is provided 329 */ 330 int __rte_experimental 331 rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info); 332 333 /** Queue information */ 334 struct rte_bbdev_queue_info { 335 /** Current device configuration */ 336 struct rte_bbdev_queue_conf conf; 337 /** Set if queue is currently started */ 338 bool started; 339 }; 340 341 /** 342 * Retrieve information about a specific queue on a device. 343 * 344 * @param dev_id 345 * The identifier of the device. 346 * @param queue_id 347 * The index of the queue. 348 * @param queue_info 349 * Pointer to structure to where information will be copied. On error, this 350 * location may or may not have been modified. 351 * 352 * @return 353 * - 0 on success 354 * - EINVAL if invalid parameter pointer is provided 355 */ 356 int __rte_experimental 357 rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id, 358 struct rte_bbdev_queue_info *queue_info); 359 360 /** @internal The data structure associated with each queue of a device. */ 361 struct rte_bbdev_queue_data { 362 void *queue_private; /**< Driver-specific per-queue data */ 363 struct rte_bbdev_queue_conf conf; /**< Current configuration */ 364 struct rte_bbdev_stats queue_stats; /**< Queue statistics */ 365 bool started; /**< Queue state */ 366 }; 367 368 /** @internal Enqueue encode operations for processing on queue of a device. */ 369 typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)( 370 struct rte_bbdev_queue_data *q_data, 371 struct rte_bbdev_enc_op **ops, 372 uint16_t num); 373 374 /** @internal Enqueue decode operations for processing on queue of a device. */ 375 typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)( 376 struct rte_bbdev_queue_data *q_data, 377 struct rte_bbdev_dec_op **ops, 378 uint16_t num); 379 380 /** @internal Dequeue encode operations from a queue of a device. */ 381 typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)( 382 struct rte_bbdev_queue_data *q_data, 383 struct rte_bbdev_enc_op **ops, uint16_t num); 384 385 /** @internal Dequeue decode operations from a queue of a device. */ 386 typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)( 387 struct rte_bbdev_queue_data *q_data, 388 struct rte_bbdev_dec_op **ops, uint16_t num); 389 390 #define RTE_BBDEV_NAME_MAX_LEN 64 /**< Max length of device name */ 391 392 /** 393 * @internal The data associated with a device, with no function pointers. 394 * This structure is safe to place in shared memory to be common among 395 * different processes in a multi-process configuration. Drivers can access 396 * these fields, but should never write to them! 397 */ 398 struct rte_bbdev_data { 399 char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */ 400 void *dev_private; /**< Driver-specific private data */ 401 uint16_t num_queues; /**< Number of currently configured queues */ 402 struct rte_bbdev_queue_data *queues; /**< Queue structures */ 403 uint16_t dev_id; /**< Device ID */ 404 int socket_id; /**< NUMA socket that device is on */ 405 bool started; /**< Device run-time state */ 406 /** Counter of processes using the device */ 407 rte_atomic16_t process_cnt; 408 }; 409 410 /* Forward declarations */ 411 struct rte_bbdev_ops; 412 struct rte_bbdev_callback; 413 struct rte_intr_handle; 414 415 /** Structure to keep track of registered callbacks */ 416 TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback); 417 418 /** 419 * @internal The data structure associated with a device. Drivers can access 420 * these fields, but should only write to the *_ops fields. 421 */ 422 struct __rte_cache_aligned rte_bbdev { 423 /**< Enqueue encode function */ 424 rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops; 425 /**< Enqueue decode function */ 426 rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops; 427 /**< Dequeue encode function */ 428 rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops; 429 /**< Dequeue decode function */ 430 rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops; 431 const struct rte_bbdev_ops *dev_ops; /**< Functions exported by PMD */ 432 struct rte_bbdev_data *data; /**< Pointer to device data */ 433 enum rte_bbdev_state state; /**< If device is currently used or not */ 434 struct rte_device *device; /**< Backing device */ 435 /** User application callback for interrupts if present */ 436 struct rte_bbdev_cb_list list_cbs; 437 struct rte_intr_handle *intr_handle; /**< Device interrupt handle */ 438 }; 439 440 /** @internal array of all devices */ 441 extern struct rte_bbdev rte_bbdev_devices[]; 442 443 /** 444 * Enqueue a burst of processed encode operations to a queue of the device. 445 * This functions only enqueues as many operations as currently possible and 446 * does not block until @p num_ops entries in the queue are available. 447 * This function does not provide any error notification to avoid the 448 * corresponding overhead. 449 * 450 * @param dev_id 451 * The identifier of the device. 452 * @param queue_id 453 * The index of the queue. 454 * @param ops 455 * Pointer array containing operations to be enqueued Must have at least 456 * @p num_ops entries 457 * @param num_ops 458 * The maximum number of operations to enqueue. 459 * 460 * @return 461 * The number of operations actually enqueued (this is the number of processed 462 * entries in the @p ops array). 463 */ 464 static inline uint16_t 465 rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id, 466 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 467 { 468 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 469 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 470 return dev->enqueue_enc_ops(q_data, ops, num_ops); 471 } 472 473 /** 474 * Enqueue a burst of processed decode operations to a queue of the device. 475 * This functions only enqueues as many operations as currently possible and 476 * does not block until @p num_ops entries in the queue are available. 477 * This function does not provide any error notification to avoid the 478 * corresponding overhead. 479 * 480 * @param dev_id 481 * The identifier of the device. 482 * @param queue_id 483 * The index of the queue. 484 * @param ops 485 * Pointer array containing operations to be enqueued Must have at least 486 * @p num_ops entries 487 * @param num_ops 488 * The maximum number of operations to enqueue. 489 * 490 * @return 491 * The number of operations actually enqueued (this is the number of processed 492 * entries in the @p ops array). 493 */ 494 static inline uint16_t 495 rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id, 496 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 497 { 498 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 499 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 500 return dev->enqueue_dec_ops(q_data, ops, num_ops); 501 } 502 503 /** 504 * Dequeue a burst of processed encode operations from a queue of the device. 505 * This functions returns only the current contents of the queue, and does not 506 * block until @ num_ops is available. 507 * This function does not provide any error notification to avoid the 508 * corresponding overhead. 509 * 510 * @param dev_id 511 * The identifier of the device. 512 * @param queue_id 513 * The index of the queue. 514 * @param ops 515 * Pointer array where operations will be dequeued to. Must have at least 516 * @p num_ops entries 517 * @param num_ops 518 * The maximum number of operations to dequeue. 519 * 520 * @return 521 * The number of operations actually dequeued (this is the number of entries 522 * copied into the @p ops array). 523 */ 524 static inline uint16_t 525 rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id, 526 struct rte_bbdev_enc_op **ops, uint16_t num_ops) 527 { 528 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 529 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 530 return dev->dequeue_enc_ops(q_data, ops, num_ops); 531 } 532 533 /** 534 * Dequeue a burst of processed decode operations from a queue of the device. 535 * This functions returns only the current contents of the queue, and does not 536 * block until @ num_ops is available. 537 * This function does not provide any error notification to avoid the 538 * corresponding overhead. 539 * 540 * @param dev_id 541 * The identifier of the device. 542 * @param queue_id 543 * The index of the queue. 544 * @param ops 545 * Pointer array where operations will be dequeued to. Must have at least 546 * @p num_ops entries 547 * @param num_ops 548 * The maximum number of operations to dequeue. 549 * 550 * @return 551 * The number of operations actually dequeued (this is the number of entries 552 * copied into the @p ops array). 553 */ 554 555 static inline uint16_t 556 rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id, 557 struct rte_bbdev_dec_op **ops, uint16_t num_ops) 558 { 559 struct rte_bbdev *dev = &rte_bbdev_devices[dev_id]; 560 struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id]; 561 return dev->dequeue_dec_ops(q_data, ops, num_ops); 562 } 563 564 /** Definitions of device event types */ 565 enum rte_bbdev_event_type { 566 RTE_BBDEV_EVENT_UNKNOWN, /**< unknown event type */ 567 RTE_BBDEV_EVENT_ERROR, /**< error interrupt event */ 568 RTE_BBDEV_EVENT_DEQUEUE, /**< dequeue event */ 569 RTE_BBDEV_EVENT_MAX /**< max value of this enum */ 570 }; 571 572 /** 573 * Typedef for application callback function registered by application 574 * software for notification of device events 575 * 576 * @param dev_id 577 * Device identifier 578 * @param event 579 * Device event to register for notification of. 580 * @param cb_arg 581 * User specified parameter to be passed to user's callback function. 582 * @param ret_param 583 * To pass data back to user application. 584 */ 585 typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id, 586 enum rte_bbdev_event_type event, void *cb_arg, 587 void *ret_param); 588 589 /** 590 * Register a callback function for specific device id. Multiple callbacks can 591 * be added and will be called in the order they are added when an event is 592 * triggered. Callbacks are called in a separate thread created by the DPDK EAL. 593 * 594 * @param dev_id 595 * Device id. 596 * @param event 597 * The event that the callback will be registered for. 598 * @param cb_fn 599 * User supplied callback function to be called. 600 * @param cb_arg 601 * Pointer to parameter that will be passed to the callback. 602 * 603 * @return 604 * Zero on success, negative value on failure. 605 */ 606 int __rte_experimental 607 rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event, 608 rte_bbdev_cb_fn cb_fn, void *cb_arg); 609 610 /** 611 * Unregister a callback function for specific device id. 612 * 613 * @param dev_id 614 * The device identifier. 615 * @param event 616 * The event that the callback will be unregistered for. 617 * @param cb_fn 618 * User supplied callback function to be unregistered. 619 * @param cb_arg 620 * Pointer to the parameter supplied when registering the callback. 621 * (void *)-1 means to remove all registered callbacks with the specified 622 * function address. 623 * 624 * @return 625 * - 0 on success 626 * - EINVAL if invalid parameter pointer is provided 627 * - EAGAIN if the provided callback pointer does not exist 628 */ 629 int __rte_experimental 630 rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event, 631 rte_bbdev_cb_fn cb_fn, void *cb_arg); 632 633 /** 634 * Enable a one-shot interrupt on the next operation enqueued to a particular 635 * queue. The interrupt will be triggered when the operation is ready to be 636 * dequeued. To handle the interrupt, an epoll file descriptor must be 637 * registered using rte_bbdev_queue_intr_ctl(), and then an application 638 * thread/lcore can wait for the interrupt using rte_epoll_wait(). 639 * 640 * @param dev_id 641 * The device identifier. 642 * @param queue_id 643 * The index of the queue. 644 * 645 * @return 646 * - 0 on success 647 * - negative value on failure - as returned from PMD driver 648 */ 649 int __rte_experimental 650 rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id); 651 652 /** 653 * Disable a one-shot interrupt on the next operation enqueued to a particular 654 * queue (if it has been enabled). 655 * 656 * @param dev_id 657 * The device identifier. 658 * @param queue_id 659 * The index of the queue. 660 * 661 * @return 662 * - 0 on success 663 * - negative value on failure - as returned from PMD driver 664 */ 665 int __rte_experimental 666 rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id); 667 668 /** 669 * Control interface for per-queue interrupts. 670 * 671 * @param dev_id 672 * The device identifier. 673 * @param queue_id 674 * The index of the queue. 675 * @param epfd 676 * Epoll file descriptor that will be associated with the interrupt source. 677 * If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll 678 * file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also 679 * be used when calling rte_epoll_wait()). 680 * @param op 681 * The operation be performed for the vector.RTE_INTR_EVENT_ADD or 682 * RTE_INTR_EVENT_DEL. 683 * @param data 684 * User context, that will be returned in the epdata.data field of the 685 * rte_epoll_event structure filled in by rte_epoll_wait(). 686 * 687 * @return 688 * - 0 on success 689 * - ENOTSUP if interrupts are not supported by the identified device 690 * - negative value on failure - as returned from PMD driver 691 */ 692 int __rte_experimental 693 rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op, 694 void *data); 695 696 #ifdef __cplusplus 697 } 698 #endif 699 700 #endif /* _RTE_BBDEV_H_ */ 701