lib/bbdev/rte_bbdev_pmd.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_BBDEV_PMD_H_
   6 #define _RTE_BBDEV_PMD_H_
   7
   8 /**
   9  * @file rte_bbdev_pmd.h
  10  *
  11  * Wireless base band driver-facing APIs.
  12  *
  13  * @warning
  14  * @b EXPERIMENTAL: this API may change without prior notice
  15  *
  16  * This API provides the mechanism for device drivers to register with the
  17  * bbdev interface. User applications should not use this API.
  18  */
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 #include <stdint.h>
  25 #include <rte_log.h>
  26
  27 #include "rte_bbdev.h"
  28
  29 /** Suggested value for SW based devices */
  30 #define RTE_BBDEV_DEFAULT_MAX_NB_QUEUES RTE_MAX_LCORE
  31
  32 /** Suggested value for SW based devices */
  33 #define RTE_BBDEV_QUEUE_SIZE_LIMIT 16384
  34
  35 /**
  36  * @internal
  37  * Allocates a new slot for a bbdev and returns the pointer to that slot
  38  * for the driver to use.
  39  *
  40  * @param name
  41  *   Unique identifier name for each bbdev device
  42  *
  43  * @return
  44  *   - Slot in the rte_bbdev array for a new device;
  45  */
  46 __rte_experimental
  47 struct rte_bbdev *
  48 rte_bbdev_allocate(const char *name);
  49
  50 /**
  51  * @internal
  52  * Release the specified bbdev.
  53  *
  54  * @param bbdev
  55  *   The *bbdev* pointer is the address of the *rte_bbdev* structure.
  56  * @return
  57  *   - 0 on success, negative on error
  58  */
  59 __rte_experimental
  60 int
  61 rte_bbdev_release(struct rte_bbdev *bbdev);
  62
  63 /**
  64  * Get the device structure for a named device.
  65  *
  66  * @param name
  67  *   Name of the device
  68  *
  69  * @return
  70  *   - The device structure pointer, or
  71  *   - NULL otherwise
  72  *
  73  */
  74 __rte_experimental
  75 struct rte_bbdev *
  76 rte_bbdev_get_named_dev(const char *name);
  77
  78 /**
  79  * Definitions of all functions exported by a driver through the the generic
  80  * structure of type *rte_bbdev_ops* supplied in the *rte_bbdev* structure
  81  * associated with a device.
  82  */
  83
  84 /** @internal Function used to configure device memory. */
  85 typedef int (*rte_bbdev_setup_queues_t)(struct rte_bbdev *dev,
  86                 uint16_t num_queues, int socket_id);
  87
  88 /** @internal Function used to configure interrupts for a device. */
  89 typedef int (*rte_bbdev_intr_enable_t)(struct rte_bbdev *dev);
  90
  91 /** @internal Function to allocate and configure a device queue. */
  92 typedef int (*rte_bbdev_queue_setup_t)(struct rte_bbdev *dev,
  93                 uint16_t queue_id, const struct rte_bbdev_queue_conf *conf);
  94
  95 /*
  96  * @internal
  97  * Function to release memory resources allocated for a device queue.
  98  */
  99 typedef int (*rte_bbdev_queue_release_t)(struct rte_bbdev *dev,
 100                 uint16_t queue_id);
 101
 102 /** @internal Function to start a configured device. */
 103 typedef int (*rte_bbdev_start_t)(struct rte_bbdev *dev);
 104
 105 /** @internal Function to stop a device. */
 106 typedef void (*rte_bbdev_stop_t)(struct rte_bbdev *dev);
 107
 108 /** @internal Function to close a device. */
 109 typedef int (*rte_bbdev_close_t)(struct rte_bbdev *dev);
 110
 111 /** @internal Function to start a device queue. */
 112 typedef int (*rte_bbdev_queue_start_t)(struct rte_bbdev *dev,
 113                 uint16_t queue_id);
 114
 115 /** @internal Function to stop a device queue. */
 116 typedef int (*rte_bbdev_queue_stop_t)(struct rte_bbdev *dev, uint16_t queue_id);
 117
 118 /** @internal Function to read stats from a device. */
 119 typedef void (*rte_bbdev_stats_get_t)(struct rte_bbdev *dev,
 120                 struct rte_bbdev_stats *stats);
 121
 122 /** @internal Function to reset stats on a device. */
 123 typedef void (*rte_bbdev_stats_reset_t)(struct rte_bbdev *dev);
 124
 125 /** @internal Function to retrieve specific information of a device. */
 126 typedef void (*rte_bbdev_info_get_t)(struct rte_bbdev *dev,
 127                 struct rte_bbdev_driver_info *dev_info);
 128
 129 /*
 130  * @internal
 131  * Function to enable interrupt for next op on a queue of a device.
 132  */
 133 typedef int (*rte_bbdev_queue_intr_enable_t)(struct rte_bbdev *dev,
 134                                     uint16_t queue_id);
 135
 136 /*
 137  * @internal
 138  * Function to disable interrupt for next op on a queue of a device.
 139  */
 140 typedef int (*rte_bbdev_queue_intr_disable_t)(struct rte_bbdev *dev,
 141                                     uint16_t queue_id);
 142
 143 /**
 144  * Operations implemented by drivers. Fields marked as "Required" must be
 145  * provided by a driver for a device to have basic functionality. "Optional"
 146  * fields are for non-vital operations
 147  */
 148 struct rte_bbdev_ops {
 149         /** Allocate and configure device memory. Optional. */
 150         rte_bbdev_setup_queues_t setup_queues;
 151         /** Configure interrupts. Optional. */
 152         rte_bbdev_intr_enable_t intr_enable;
 153         /** Start device. Optional. */
 154         rte_bbdev_start_t start;
 155         /** Stop device. Optional. */
 156         rte_bbdev_stop_t stop;
 157         /** Close device. Optional. */
 158         rte_bbdev_close_t close;
 159
 160         /** Get device info. Required. */
 161         rte_bbdev_info_get_t info_get;
 162         /** Get device statistics. Optional. */
 163         rte_bbdev_stats_get_t stats_get;
 164         /** Reset device statistics. Optional. */
 165         rte_bbdev_stats_reset_t stats_reset;
 166
 167         /** Set up a device queue. Required. */
 168         rte_bbdev_queue_setup_t queue_setup;
 169         /** Release a queue. Required. */
 170         rte_bbdev_queue_release_t queue_release;
 171         /** Start a queue. Optional. */
 172         rte_bbdev_queue_start_t queue_start;
 173         /** Stop a queue pair. Optional. */
 174         rte_bbdev_queue_stop_t queue_stop;
 175
 176         /** Enable queue interrupt. Optional */
 177         rte_bbdev_queue_intr_enable_t queue_intr_enable;
 178         /** Disable queue interrupt. Optional */
 179         rte_bbdev_queue_intr_disable_t queue_intr_disable;
 180 };
 181
 182 /**
 183  * Executes all the user application registered callbacks for the specific
 184  * device and event type.
 185  *
 186  * @param dev
 187  *   Pointer to the device structure.
 188  * @param event
 189  *   Event type.
 190  * @param ret_param
 191  *   To pass data back to user application.
 192  */
 193 __rte_experimental
 194 void
 195 rte_bbdev_pmd_callback_process(struct rte_bbdev *dev,
 196         enum rte_bbdev_event_type event, void *ret_param);
 197
 198 #ifdef __cplusplus
 199 }
 200 #endif
 201
 202 #endif /* _RTE_BBDEV_PMD_H_ */