lib/librte_bbdev/rte_bbdev.h

   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:
  15  * All functions in this file may be changed or removed without prior notice.
  16  *
  17  * This API allows an application to discover, configure and use a device to
  18  * process operations. An asynchronous API (enqueue, followed by later dequeue)
  19  * is used for processing operations.
  20  *
  21  * The functions in this API are not thread-safe when called on the same
  22  * target object (a device, or a queue on a device), with the exception that
  23  * one thread can enqueue operations to a queue while another thread dequeues
  24  * from the same queue.
  25  */
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 #include <stdint.h>
  32 #include <stdbool.h>
  33 #include <string.h>
  34
  35 #include <rte_compat.h>
  36 #include <rte_atomic.h>
  37 #include <rte_bus.h>
  38 #include <rte_cpuflags.h>
  39 #include <rte_memory.h>
  40
  41 #include "rte_bbdev_op.h"
  42
  43 #ifndef RTE_BBDEV_MAX_DEVS
  44 #define RTE_BBDEV_MAX_DEVS 128  /**< Max number of devices */
  45 #endif
  46
  47 /** Flags indicate current state of BBDEV device */
  48 enum rte_bbdev_state {
  49         RTE_BBDEV_UNUSED,
  50         RTE_BBDEV_INITIALIZED
  51 };
  52
  53 /**
  54  * Get the total number of devices that have been successfully initialised.
  55  *
  56  * @return
  57  *   The total number of usable devices.
  58  */
  59 __rte_experimental
  60 uint16_t
  61 rte_bbdev_count(void);
  62
  63 /**
  64  * Check if a device is valid.
  65  *
  66  * @param dev_id
  67  *   The identifier of the device.
  68  *
  69  * @return
  70  *   true if device ID is valid and device is attached, false otherwise.
  71  */
  72 __rte_experimental
  73 bool
  74 rte_bbdev_is_valid(uint16_t dev_id);
  75
  76 /**
  77  * Get the next enabled device.
  78  *
  79  * @param dev_id
  80  *   The current device
  81  *
  82  * @return
  83  *   - The next device, or
  84  *   - RTE_BBDEV_MAX_DEVS if none found
  85  */
  86 __rte_experimental
  87 uint16_t
  88 rte_bbdev_find_next(uint16_t dev_id);
  89
  90 /** Iterate through all enabled devices */
  91 #define RTE_BBDEV_FOREACH(i) for (i = rte_bbdev_find_next(-1); \
  92                 i < RTE_BBDEV_MAX_DEVS; \
  93                 i = rte_bbdev_find_next(i))
  94
  95 /**
  96  * Setup up device queues.
  97  * This function must be called on a device before setting up the queues and
  98  * starting the device. It can also be called when a device is in the stopped
  99  * state. If any device queues have been configured their configuration will be
 100  * cleared by a call to this function.
 101  *
 102  * @param dev_id
 103  *   The identifier of the device.
 104  * @param num_queues
 105  *   Number of queues to configure on device.
 106  * @param socket_id
 107  *   ID of a socket which will be used to allocate memory.
 108  *
 109  * @return
 110  *   - 0 on success
 111  *   - -ENODEV if dev_id is invalid or the device is corrupted
 112  *   - -EINVAL if num_queues is invalid, 0 or greater than maximum
 113  *   - -EBUSY if the identified device has already started
 114  *   - -ENOMEM if unable to allocate memory
 115  */
 116 __rte_experimental
 117 int
 118 rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues, int socket_id);
 119
 120 /**
 121  * Enable interrupts.
 122  * This function may be called before starting the device to enable the
 123  * interrupts if they are available.
 124  *
 125  * @param dev_id
 126  *   The identifier of the device.
 127  *
 128  * @return
 129  *   - 0 on success
 130  *   - -ENODEV if dev_id is invalid or the device is corrupted
 131  *   - -EBUSY if the identified device has already started
 132  *   - -ENOTSUP if the interrupts are not supported by the device
 133  */
 134 __rte_experimental
 135 int
 136 rte_bbdev_intr_enable(uint16_t dev_id);
 137
 138 /** Device queue configuration structure */
 139 struct rte_bbdev_queue_conf {
 140         int socket;  /**< NUMA socket used for memory allocation */
 141         uint32_t queue_size;  /**< Size of queue */
 142         uint8_t priority;  /**< Queue priority */
 143         bool deferred_start; /**< Do not start queue when device is started. */
 144         enum rte_bbdev_op_type op_type; /**< Operation type */
 145 };
 146
 147 /**
 148  * Configure a queue on a device.
 149  * This function can be called after device configuration, and before starting.
 150  * It can also be called when the device or the queue is in the stopped state.
 151  *
 152  * @param dev_id
 153  *   The identifier of the device.
 154  * @param queue_id
 155  *   The index of the queue.
 156  * @param conf
 157  *   The queue configuration. If NULL, a default configuration will be used.
 158  *
 159  * @return
 160  *   - 0 on success
 161  *   - EINVAL if the identified queue size or priority are invalid
 162  *   - EBUSY if the identified queue or its device have already started
 163  */
 164 __rte_experimental
 165 int
 166 rte_bbdev_queue_configure(uint16_t dev_id, uint16_t queue_id,
 167                 const struct rte_bbdev_queue_conf *conf);
 168
 169 /**
 170  * Start a device.
 171  * This is the last step needed before enqueueing operations is possible.
 172  *
 173  * @param dev_id
 174  *   The identifier of the device.
 175  *
 176  * @return
 177  *   - 0 on success
 178  *   - negative value on failure - as returned from PMD driver
 179  */
 180 __rte_experimental
 181 int
 182 rte_bbdev_start(uint16_t dev_id);
 183
 184 /**
 185  * Stop a device.
 186  * The device can be reconfigured, and restarted after being stopped.
 187  *
 188  * @param dev_id
 189  *   The identifier of the device.
 190  *
 191  * @return
 192  *   - 0 on success
 193  */
 194 __rte_experimental
 195 int
 196 rte_bbdev_stop(uint16_t dev_id);
 197
 198 /**
 199  * Close a device.
 200  * The device cannot be restarted without reconfiguration!
 201  *
 202  * @param dev_id
 203  *   The identifier of the device.
 204  *
 205  * @return
 206  *   - 0 on success
 207  */
 208 __rte_experimental
 209 int
 210 rte_bbdev_close(uint16_t dev_id);
 211
 212 /**
 213  * Start a specified queue on a device.
 214  * This is only needed if the queue has been stopped, or if the deferred_start
 215  * flag has been set when configuring the queue.
 216  *
 217  * @param dev_id
 218  *   The identifier of the device.
 219  * @param queue_id
 220  *   The index of the queue.
 221  *
 222  * @return
 223  *   - 0 on success
 224  *   - negative value on failure - as returned from PMD driver
 225  */
 226 __rte_experimental
 227 int
 228 rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id);
 229
 230 /**
 231  * Stop a specified queue on a device, to allow re configuration.
 232  *
 233  * @param dev_id
 234  *   The identifier of the device.
 235  * @param queue_id
 236  *   The index of the queue.
 237  *
 238  * @return
 239  *   - 0 on success
 240  *   - negative value on failure - as returned from PMD driver
 241  */
 242 __rte_experimental
 243 int
 244 rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id);
 245
 246 /** Device statistics. */
 247 struct rte_bbdev_stats {
 248         uint64_t enqueued_count;  /**< Count of all operations enqueued */
 249         uint64_t dequeued_count;  /**< Count of all operations dequeued */
 250         /** Total error count on operations enqueued */
 251         uint64_t enqueue_err_count;
 252         /** Total error count on operations dequeued */
 253         uint64_t dequeue_err_count;
 254         /** CPU cycles consumed by the (HW/SW) accelerator device to offload
 255          *  the enqueue request to its internal queues.
 256          *  - For a HW device this is the cycles consumed in MMIO write
 257          *  - For a SW (vdev) device, this is the processing time of the
 258          *     bbdev operation
 259          */
 260         uint64_t acc_offload_cycles;
 261 };
 262
 263 /**
 264  * Retrieve the general I/O statistics of a device.
 265  *
 266  * @param dev_id
 267  *   The identifier of the device.
 268  * @param stats
 269  *   Pointer to structure to where statistics will be copied. On error, this
 270  *   location may or may not have been modified.
 271  *
 272  * @return
 273  *   - 0 on success
 274  *   - EINVAL if invalid parameter pointer is provided
 275  */
 276 __rte_experimental
 277 int
 278 rte_bbdev_stats_get(uint16_t dev_id, struct rte_bbdev_stats *stats);
 279
 280 /**
 281  * Reset the statistics of a device.
 282  *
 283  * @param dev_id
 284  *   The identifier of the device.
 285  * @return
 286  *   - 0 on success
 287  */
 288 __rte_experimental
 289 int
 290 rte_bbdev_stats_reset(uint16_t dev_id);
 291
 292 /** Device information supplied by the device's driver */
 293 struct rte_bbdev_driver_info {
 294         /** Driver name */
 295         const char *driver_name;
 296
 297         /** Maximum number of queues supported by the device */
 298         unsigned int max_num_queues;
 299         /** Queue size limit (queue size must also be power of 2) */
 300         uint32_t queue_size_lim;
 301         /** Set if device off-loads operation to hardware  */
 302         bool hardware_accelerated;
 303         /** Max value supported by queue priority for DL */
 304         uint8_t max_dl_queue_priority;
 305         /** Max value supported by queue priority for UL */
 306         uint8_t max_ul_queue_priority;
 307         /** Set if device supports per-queue interrupts */
 308         bool queue_intr_supported;
 309         /** Minimum alignment of buffers, in bytes */
 310         uint16_t min_alignment;
 311         /** HARQ memory available in kB */
 312         uint32_t harq_buffer_size;
 313         /** Default queue configuration used if none is supplied  */
 314         struct rte_bbdev_queue_conf default_queue_conf;
 315         /** Device operation capabilities */
 316         const struct rte_bbdev_op_cap *capabilities;
 317         /** Device cpu_flag requirements */
 318         const enum rte_cpu_flag_t *cpu_flag_reqs;
 319 };
 320
 321 /** Macro used at end of bbdev PMD list */
 322 #define RTE_BBDEV_END_OF_CAPABILITIES_LIST() \
 323         { RTE_BBDEV_OP_NONE }
 324
 325 /**
 326  * Device information structure used by an application to discover a devices
 327  * capabilities and current configuration
 328  */
 329 struct rte_bbdev_info {
 330         int socket_id;  /**< NUMA socket that device is on */
 331         const char *dev_name;  /**< Unique device name */
 332         const struct rte_device *device; /**< Device Information */
 333         uint16_t num_queues;  /**< Number of queues currently configured */
 334         bool started;  /**< Set if device is currently started */
 335         struct rte_bbdev_driver_info drv;  /**< Info from device driver */
 336 };
 337
 338 /**
 339  * Retrieve information about a device.
 340  *
 341  * @param dev_id
 342  *   The identifier of the device.
 343  * @param dev_info
 344  *   Pointer to structure to where information will be copied. On error, this
 345  *   location may or may not have been modified.
 346  *
 347  * @return
 348  *   - 0 on success
 349  *   - EINVAL if invalid parameter pointer is provided
 350  */
 351 __rte_experimental
 352 int
 353 rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info);
 354
 355 /** Queue information */
 356 struct rte_bbdev_queue_info {
 357         /** Current device configuration */
 358         struct rte_bbdev_queue_conf conf;
 359         /** Set if queue is currently started */
 360         bool started;
 361 };
 362
 363 /**
 364  * Retrieve information about a specific queue on a device.
 365  *
 366  * @param dev_id
 367  *   The identifier of the device.
 368  * @param queue_id
 369  *   The index of the queue.
 370  * @param queue_info
 371  *   Pointer to structure to where information will be copied. On error, this
 372  *   location may or may not have been modified.
 373  *
 374  * @return
 375  *   - 0 on success
 376  *   - EINVAL if invalid parameter pointer is provided
 377  */
 378 __rte_experimental
 379 int
 380 rte_bbdev_queue_info_get(uint16_t dev_id, uint16_t queue_id,
 381                 struct rte_bbdev_queue_info *queue_info);
 382
 383 /** @internal The data structure associated with each queue of a device. */
 384 struct rte_bbdev_queue_data {
 385         void *queue_private;  /**< Driver-specific per-queue data */
 386         struct rte_bbdev_queue_conf conf;  /**< Current configuration */
 387         struct rte_bbdev_stats queue_stats;  /**< Queue statistics */
 388         bool started;  /**< Queue state */
 389 };
 390
 391 /** @internal Enqueue encode operations for processing on queue of a device. */
 392 typedef uint16_t (*rte_bbdev_enqueue_enc_ops_t)(
 393                 struct rte_bbdev_queue_data *q_data,
 394                 struct rte_bbdev_enc_op **ops,
 395                 uint16_t num);
 396
 397 /** @internal Enqueue decode operations for processing on queue of a device. */
 398 typedef uint16_t (*rte_bbdev_enqueue_dec_ops_t)(
 399                 struct rte_bbdev_queue_data *q_data,
 400                 struct rte_bbdev_dec_op **ops,
 401                 uint16_t num);
 402
 403 /** @internal Dequeue encode operations from a queue of a device. */
 404 typedef uint16_t (*rte_bbdev_dequeue_enc_ops_t)(
 405                 struct rte_bbdev_queue_data *q_data,
 406                 struct rte_bbdev_enc_op **ops, uint16_t num);
 407
 408 /** @internal Dequeue decode operations from a queue of a device. */
 409 typedef uint16_t (*rte_bbdev_dequeue_dec_ops_t)(
 410                 struct rte_bbdev_queue_data *q_data,
 411                 struct rte_bbdev_dec_op **ops, uint16_t num);
 412
 413 #define RTE_BBDEV_NAME_MAX_LEN  64  /**< Max length of device name */
 414
 415 /**
 416  * @internal The data associated with a device, with no function pointers.
 417  * This structure is safe to place in shared memory to be common among
 418  * different processes in a multi-process configuration. Drivers can access
 419  * these fields, but should never write to them!
 420  */
 421 struct rte_bbdev_data {
 422         char name[RTE_BBDEV_NAME_MAX_LEN]; /**< Unique identifier name */
 423         void *dev_private;  /**< Driver-specific private data */
 424         uint16_t num_queues;  /**< Number of currently configured queues */
 425         struct rte_bbdev_queue_data *queues;  /**< Queue structures */
 426         uint16_t dev_id;  /**< Device ID */
 427         int socket_id;  /**< NUMA socket that device is on */
 428         bool started;  /**< Device run-time state */
 429         /** Counter of processes using the device */
 430         rte_atomic16_t process_cnt;
 431 };
 432
 433 /* Forward declarations */
 434 struct rte_bbdev_ops;
 435 struct rte_bbdev_callback;
 436 struct rte_intr_handle;
 437
 438 /** Structure to keep track of registered callbacks */
 439 TAILQ_HEAD(rte_bbdev_cb_list, rte_bbdev_callback);
 440
 441 /**
 442  * @internal The data structure associated with a device. Drivers can access
 443  * these fields, but should only write to the *_ops fields.
 444  */
 445 struct __rte_cache_aligned rte_bbdev {
 446         /** Enqueue encode function */
 447         rte_bbdev_enqueue_enc_ops_t enqueue_enc_ops;
 448         /** Enqueue decode function */
 449         rte_bbdev_enqueue_dec_ops_t enqueue_dec_ops;
 450         /** Dequeue encode function */
 451         rte_bbdev_dequeue_enc_ops_t dequeue_enc_ops;
 452         /** Dequeue decode function */
 453         rte_bbdev_dequeue_dec_ops_t dequeue_dec_ops;
 454         /** Enqueue encode function */
 455         rte_bbdev_enqueue_enc_ops_t enqueue_ldpc_enc_ops;
 456         /** Enqueue decode function */
 457         rte_bbdev_enqueue_dec_ops_t enqueue_ldpc_dec_ops;
 458         /** Dequeue encode function */
 459         rte_bbdev_dequeue_enc_ops_t dequeue_ldpc_enc_ops;
 460         /** Dequeue decode function */
 461         rte_bbdev_dequeue_dec_ops_t dequeue_ldpc_dec_ops;
 462         const struct rte_bbdev_ops *dev_ops;  /**< Functions exported by PMD */
 463         struct rte_bbdev_data *data;  /**< Pointer to device data */
 464         enum rte_bbdev_state state;  /**< If device is currently used or not */
 465         struct rte_device *device; /**< Backing device */
 466         /** User application callback for interrupts if present */
 467         struct rte_bbdev_cb_list list_cbs;
 468         struct rte_intr_handle *intr_handle; /**< Device interrupt handle */
 469 };
 470
 471 /** @internal array of all devices */
 472 extern struct rte_bbdev rte_bbdev_devices[];
 473
 474 /**
 475  * Enqueue a burst of processed encode operations to a queue of the device.
 476  * This functions only enqueues as many operations as currently possible and
 477  * does not block until @p num_ops entries in the queue are available.
 478  * This function does not provide any error notification to avoid the
 479  * corresponding overhead.
 480  *
 481  * @param dev_id
 482  *   The identifier of the device.
 483  * @param queue_id
 484  *   The index of the queue.
 485  * @param ops
 486  *   Pointer array containing operations to be enqueued Must have at least
 487  *   @p num_ops entries
 488  * @param num_ops
 489  *   The maximum number of operations to enqueue.
 490  *
 491  * @return
 492  *   The number of operations actually enqueued (this is the number of processed
 493  *   entries in the @p ops array).
 494  */
 495 __rte_experimental
 496 static inline uint16_t
 497 rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id,
 498                 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 499 {
 500         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 501         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 502         return dev->enqueue_enc_ops(q_data, ops, num_ops);
 503 }
 504
 505 /**
 506  * Enqueue a burst of processed decode operations to a queue of the device.
 507  * This functions only enqueues as many operations as currently possible and
 508  * does not block until @p num_ops entries in the queue are available.
 509  * This function does not provide any error notification to avoid the
 510  * corresponding overhead.
 511  *
 512  * @param dev_id
 513  *   The identifier of the device.
 514  * @param queue_id
 515  *   The index of the queue.
 516  * @param ops
 517  *   Pointer array containing operations to be enqueued Must have at least
 518  *   @p num_ops entries
 519  * @param num_ops
 520  *   The maximum number of operations to enqueue.
 521  *
 522  * @return
 523  *   The number of operations actually enqueued (this is the number of processed
 524  *   entries in the @p ops array).
 525  */
 526 __rte_experimental
 527 static inline uint16_t
 528 rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id,
 529                 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 530 {
 531         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 532         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 533         return dev->enqueue_dec_ops(q_data, ops, num_ops);
 534 }
 535
 536 /**
 537  * Enqueue a burst of processed encode operations to a queue of the device.
 538  * This functions only enqueues as many operations as currently possible and
 539  * does not block until @p num_ops entries in the queue are available.
 540  * This function does not provide any error notification to avoid the
 541  * corresponding overhead.
 542  *
 543  * @param dev_id
 544  *   The identifier of the device.
 545  * @param queue_id
 546  *   The index of the queue.
 547  * @param ops
 548  *   Pointer array containing operations to be enqueued Must have at least
 549  *   @p num_ops entries
 550  * @param num_ops
 551  *   The maximum number of operations to enqueue.
 552  *
 553  * @return
 554  *   The number of operations actually enqueued (this is the number of processed
 555  *   entries in the @p ops array).
 556  */
 557 __rte_experimental
 558 static inline uint16_t
 559 rte_bbdev_enqueue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id,
 560                 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 561 {
 562         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 563         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 564         return dev->enqueue_ldpc_enc_ops(q_data, ops, num_ops);
 565 }
 566
 567 /**
 568  * Enqueue a burst of processed decode operations to a queue of the device.
 569  * This functions only enqueues as many operations as currently possible and
 570  * does not block until @p num_ops entries in the queue are available.
 571  * This function does not provide any error notification to avoid the
 572  * corresponding overhead.
 573  *
 574  * @param dev_id
 575  *   The identifier of the device.
 576  * @param queue_id
 577  *   The index of the queue.
 578  * @param ops
 579  *   Pointer array containing operations to be enqueued Must have at least
 580  *   @p num_ops entries
 581  * @param num_ops
 582  *   The maximum number of operations to enqueue.
 583  *
 584  * @return
 585  *   The number of operations actually enqueued (this is the number of processed
 586  *   entries in the @p ops array).
 587  */
 588 __rte_experimental
 589 static inline uint16_t
 590 rte_bbdev_enqueue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id,
 591                 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 592 {
 593         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 594         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 595         return dev->enqueue_ldpc_dec_ops(q_data, ops, num_ops);
 596 }
 597
 598
 599 /**
 600  * Dequeue a burst of processed encode operations from a queue of the device.
 601  * This functions returns only the current contents of the queue, and does not
 602  * block until @ num_ops is available.
 603  * This function does not provide any error notification to avoid the
 604  * corresponding overhead.
 605  *
 606  * @param dev_id
 607  *   The identifier of the device.
 608  * @param queue_id
 609  *   The index of the queue.
 610  * @param ops
 611  *   Pointer array where operations will be dequeued to. Must have at least
 612  *   @p num_ops entries
 613  *   ie. A pointer to a table of void * pointers (ops) that will be filled.
 614  * @param num_ops
 615  *   The maximum number of operations to dequeue.
 616  *
 617  * @return
 618  *   The number of operations actually dequeued (this is the number of entries
 619  *   copied into the @p ops array).
 620  */
 621 __rte_experimental
 622 static inline uint16_t
 623 rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id,
 624                 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 625 {
 626         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 627         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 628         return dev->dequeue_enc_ops(q_data, ops, num_ops);
 629 }
 630
 631 /**
 632  * Dequeue a burst of processed decode operations from a queue of the device.
 633  * This functions returns only the current contents of the queue, and does not
 634  * block until @ num_ops is available.
 635  * This function does not provide any error notification to avoid the
 636  * corresponding overhead.
 637  *
 638  * @param dev_id
 639  *   The identifier of the device.
 640  * @param queue_id
 641  *   The index of the queue.
 642  * @param ops
 643  *   Pointer array where operations will be dequeued to. Must have at least
 644  *   @p num_ops entries
 645  *   ie. A pointer to a table of void * pointers (ops) that will be filled.
 646  * @param num_ops
 647  *   The maximum number of operations to dequeue.
 648  *
 649  * @return
 650  *   The number of operations actually dequeued (this is the number of entries
 651  *   copied into the @p ops array).
 652  */
 653
 654 __rte_experimental
 655 static inline uint16_t
 656 rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id,
 657                 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 658 {
 659         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 660         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 661         return dev->dequeue_dec_ops(q_data, ops, num_ops);
 662 }
 663
 664
 665 /**
 666  * Dequeue a burst of processed encode operations from a queue of the device.
 667  * This functions returns only the current contents of the queue, and does not
 668  * block until @ num_ops is available.
 669  * This function does not provide any error notification to avoid the
 670  * corresponding overhead.
 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 where operations will be dequeued to. Must have at least
 678  *   @p num_ops entries
 679  * @param num_ops
 680  *   The maximum number of operations to dequeue.
 681  *
 682  * @return
 683  *   The number of operations actually dequeued (this is the number of entries
 684  *   copied into the @p ops array).
 685  */
 686 __rte_experimental
 687 static inline uint16_t
 688 rte_bbdev_dequeue_ldpc_enc_ops(uint16_t dev_id, uint16_t queue_id,
 689                 struct rte_bbdev_enc_op **ops, uint16_t num_ops)
 690 {
 691         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 692         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 693         return dev->dequeue_ldpc_enc_ops(q_data, ops, num_ops);
 694 }
 695
 696 /**
 697  * Dequeue a burst of processed decode operations from a queue of the device.
 698  * This functions returns only the current contents of the queue, and does not
 699  * block until @ num_ops is available.
 700  * This function does not provide any error notification to avoid the
 701  * corresponding overhead.
 702  *
 703  * @param dev_id
 704  *   The identifier of the device.
 705  * @param queue_id
 706  *   The index of the queue.
 707  * @param ops
 708  *   Pointer array where operations will be dequeued to. Must have at least
 709  *   @p num_ops entries
 710  * @param num_ops
 711  *   The maximum number of operations to dequeue.
 712  *
 713  * @return
 714  *   The number of operations actually dequeued (this is the number of entries
 715  *   copied into the @p ops array).
 716  */
 717 __rte_experimental
 718 static inline uint16_t
 719 rte_bbdev_dequeue_ldpc_dec_ops(uint16_t dev_id, uint16_t queue_id,
 720                 struct rte_bbdev_dec_op **ops, uint16_t num_ops)
 721 {
 722         struct rte_bbdev *dev = &rte_bbdev_devices[dev_id];
 723         struct rte_bbdev_queue_data *q_data = &dev->data->queues[queue_id];
 724         return dev->dequeue_ldpc_dec_ops(q_data, ops, num_ops);
 725 }
 726
 727 /** Definitions of device event types */
 728 enum rte_bbdev_event_type {
 729         RTE_BBDEV_EVENT_UNKNOWN,  /**< unknown event type */
 730         RTE_BBDEV_EVENT_ERROR,  /**< error interrupt event */
 731         RTE_BBDEV_EVENT_DEQUEUE,  /**< dequeue event */
 732         RTE_BBDEV_EVENT_MAX  /**< max value of this enum */
 733 };
 734
 735 /**
 736  * Typedef for application callback function registered by application
 737  * software for notification of device events
 738  *
 739  * @param dev_id
 740  *   Device identifier
 741  * @param event
 742  *   Device event to register for notification of.
 743  * @param cb_arg
 744  *   User specified parameter to be passed to user's callback function.
 745  * @param ret_param
 746  *   To pass data back to user application.
 747  */
 748 typedef void (*rte_bbdev_cb_fn)(uint16_t dev_id,
 749                 enum rte_bbdev_event_type event, void *cb_arg,
 750                 void *ret_param);
 751
 752 /**
 753  * Register a callback function for specific device id. Multiple callbacks can
 754  * be added and will be called in the order they are added when an event is
 755  * triggered. Callbacks are called in a separate thread created by the DPDK EAL.
 756  *
 757  * @param dev_id
 758  *   Device id.
 759  * @param event
 760  *   The event that the callback will be registered for.
 761  * @param cb_fn
 762  *   User supplied callback function to be called.
 763  * @param cb_arg
 764  *   Pointer to parameter that will be passed to the callback.
 765  *
 766  * @return
 767  *   Zero on success, negative value on failure.
 768  */
 769 __rte_experimental
 770 int
 771 rte_bbdev_callback_register(uint16_t dev_id, enum rte_bbdev_event_type event,
 772                 rte_bbdev_cb_fn cb_fn, void *cb_arg);
 773
 774 /**
 775  * Unregister a callback function for specific device id.
 776  *
 777  * @param dev_id
 778  *   The device identifier.
 779  * @param event
 780  *   The event that the callback will be unregistered for.
 781  * @param cb_fn
 782  *   User supplied callback function to be unregistered.
 783  * @param cb_arg
 784  *   Pointer to the parameter supplied when registering the callback.
 785  *   (void *)-1 means to remove all registered callbacks with the specified
 786  *   function address.
 787  *
 788  * @return
 789  *   - 0 on success
 790  *   - EINVAL if invalid parameter pointer is provided
 791  *   - EAGAIN if the provided callback pointer does not exist
 792  */
 793 __rte_experimental
 794 int
 795 rte_bbdev_callback_unregister(uint16_t dev_id, enum rte_bbdev_event_type event,
 796                 rte_bbdev_cb_fn cb_fn, void *cb_arg);
 797
 798 /**
 799  * Enable a one-shot interrupt on the next operation enqueued to a particular
 800  * queue. The interrupt will be triggered when the operation is ready to be
 801  * dequeued. To handle the interrupt, an epoll file descriptor must be
 802  * registered using rte_bbdev_queue_intr_ctl(), and then an application
 803  * thread/lcore can wait for the interrupt using rte_epoll_wait().
 804  *
 805  * @param dev_id
 806  *   The device identifier.
 807  * @param queue_id
 808  *   The index of the queue.
 809  *
 810  * @return
 811  *   - 0 on success
 812  *   - negative value on failure - as returned from PMD driver
 813  */
 814 __rte_experimental
 815 int
 816 rte_bbdev_queue_intr_enable(uint16_t dev_id, uint16_t queue_id);
 817
 818 /**
 819  * Disable a one-shot interrupt on the next operation enqueued to a particular
 820  * queue (if it has been enabled).
 821  *
 822  * @param dev_id
 823  *   The device identifier.
 824  * @param queue_id
 825  *   The index of the queue.
 826  *
 827  * @return
 828  *   - 0 on success
 829  *   - negative value on failure - as returned from PMD driver
 830  */
 831 __rte_experimental
 832 int
 833 rte_bbdev_queue_intr_disable(uint16_t dev_id, uint16_t queue_id);
 834
 835 /**
 836  * Control interface for per-queue interrupts.
 837  *
 838  * @param dev_id
 839  *   The device identifier.
 840  * @param queue_id
 841  *   The index of the queue.
 842  * @param epfd
 843  *   Epoll file descriptor that will be associated with the interrupt source.
 844  *   If the special value RTE_EPOLL_PER_THREAD is provided, a per thread epoll
 845  *   file descriptor created by the EAL is used (RTE_EPOLL_PER_THREAD can also
 846  *   be used when calling rte_epoll_wait()).
 847  * @param op
 848  *   The operation be performed for the vector.RTE_INTR_EVENT_ADD or
 849  *   RTE_INTR_EVENT_DEL.
 850  * @param data
 851  *   User context, that will be returned in the epdata.data field of the
 852  *   rte_epoll_event structure filled in by rte_epoll_wait().
 853  *
 854  * @return
 855  *   - 0 on success
 856  *   - ENOTSUP if interrupts are not supported by the identified device
 857  *   - negative value on failure - as returned from PMD driver
 858  */
 859 __rte_experimental
 860 int
 861 rte_bbdev_queue_intr_ctl(uint16_t dev_id, uint16_t queue_id, int epfd, int op,
 862                 void *data);
 863
 864 #ifdef __cplusplus
 865 }
 866 #endif
 867
 868 #endif /* _RTE_BBDEV_H_ */