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