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