lib/librte_rawdev/rte_rawdev_pmd.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2017 NXP
   3  */
   4
   5 #ifndef _RTE_RAWDEV_PMD_H_
   6 #define _RTE_RAWDEV_PMD_H_
   7
   8 /** @file
   9  * RTE RAW PMD APIs
  10  *
  11  * @note
  12  * Driver facing APIs for a raw device. These are not to be called directly by
  13  * any application.
  14  *
  15  * @warning
  16  * @b EXPERIMENTAL: this API may change without prior notice
  17  */
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 #include <string.h>
  24
  25 #include <rte_dev.h>
  26 #include <rte_malloc.h>
  27 #include <rte_log.h>
  28 #include <rte_common.h>
  29
  30 #include "rte_rawdev.h"
  31
  32 extern int librawdev_logtype;
  33
  34 /* Logging Macros */
  35 #define RTE_RDEV_LOG(level, fmt, args...) \
  36         rte_log(RTE_LOG_ ## level, librawdev_logtype, "%s(): " fmt "\n", \
  37                 __func__, ##args)
  38
  39 #define RTE_RDEV_ERR(fmt, args...) \
  40         RTE_RDEV_LOG(ERR, fmt, ## args)
  41 #define RTE_RDEV_DEBUG(fmt, args...) \
  42         RTE_RDEV_LOG(DEBUG, fmt, ## args)
  43 #define RTE_RDEV_INFO(fmt, args...) \
  44         RTE_RDEV_LOG(INFO, fmt, ## args)
  45
  46
  47 /* Macros to check for valid device */
  48 #define RTE_RAWDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
  49         if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
  50                 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
  51                 return retval; \
  52         } \
  53 } while (0)
  54
  55 #define RTE_RAWDEV_VALID_DEVID_OR_RET(dev_id) do { \
  56         if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
  57                 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
  58                 return; \
  59         } \
  60 } while (0)
  61
  62 #define RTE_RAWDEV_DETACHED  (0)
  63 #define RTE_RAWDEV_ATTACHED  (1)
  64
  65 /* Global structure used for maintaining state of allocated raw devices.
  66  *
  67  * TODO: Can be expanded to <type of raw device>:<count> in future.
  68  *       Applications should be able to select from a number of type of raw
  69  *       devices which were detected or attached to this DPDK instance.
  70  */
  71 struct rte_rawdev_global {
  72         /**< Number of devices found */
  73         uint16_t nb_devs;
  74 };
  75
  76 extern struct rte_rawdev_global *rte_rawdev_globals;
  77 /** Pointer to global raw devices data structure. */
  78 extern struct rte_rawdev *rte_rawdevs;
  79 /** The pool of rte_rawdev structures. */
  80
  81 /**
  82  * Get the rte_rawdev structure device pointer for the named device.
  83  *
  84  * @param name
  85  *   device name to select the device structure.
  86  *
  87  * @return
  88  *   - The rte_rawdev structure pointer for the given device ID.
  89  */
  90 static inline struct rte_rawdev *
  91 rte_rawdev_pmd_get_named_dev(const char *name)
  92 {
  93         struct rte_rawdev *dev;
  94         unsigned int i;
  95
  96         if (name == NULL)
  97                 return NULL;
  98
  99         for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) {
 100                 dev = &rte_rawdevs[i];
 101                 if ((dev->attached == RTE_RAWDEV_ATTACHED) &&
 102                    (strcmp(dev->name, name) == 0))
 103                         return dev;
 104         }
 105
 106         return NULL;
 107 }
 108
 109 /**
 110  * Validate if the raw device index is a valid attached raw device.
 111  *
 112  * @param dev_id
 113  *   raw device index.
 114  *
 115  * @return
 116  *   - If the device index is valid (1) or not (0).
 117  */
 118 static inline unsigned
 119 rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)
 120 {
 121         struct rte_rawdev *dev;
 122
 123         if (dev_id >= RTE_RAWDEV_MAX_DEVS)
 124                 return 0;
 125
 126         dev = &rte_rawdevs[dev_id];
 127         if (dev->attached != RTE_RAWDEV_ATTACHED)
 128                 return 0;
 129         else
 130                 return 1;
 131 }
 132
 133 /**
 134  * Definitions of all functions exported by a driver through the
 135  * the generic structure of type *rawdev_ops* supplied in the
 136  * *rte_rawdev* structure associated with a device.
 137  */
 138
 139 /**
 140  * Get device information of a device.
 141  *
 142  * @param dev
 143  *   Raw device pointer
 144  * @param dev_info
 145  *   Raw device information structure
 146  *
 147  * @return
 148  *   Returns 0 on success
 149  */
 150 typedef void (*rawdev_info_get_t)(struct rte_rawdev *dev,
 151                                   rte_rawdev_obj_t dev_info);
 152
 153 /**
 154  * Configure a device.
 155  *
 156  * @param dev
 157  *   Raw device pointer
 158  * @param config
 159  *   Void object containing device specific configuration
 160  *
 161  * @return
 162  *   Returns 0 on success
 163  */
 164 typedef int (*rawdev_configure_t)(const struct rte_rawdev *dev,
 165                                   rte_rawdev_obj_t config);
 166
 167 /**
 168  * Start a configured device.
 169  *
 170  * @param dev
 171  *   Raw device pointer
 172  *
 173  * @return
 174  *   Returns 0 on success
 175  */
 176 typedef int (*rawdev_start_t)(struct rte_rawdev *dev);
 177
 178 /**
 179  * Stop a configured device.
 180  *
 181  * @param dev
 182  *   Raw device pointer
 183  */
 184 typedef void (*rawdev_stop_t)(struct rte_rawdev *dev);
 185
 186 /**
 187  * Close a configured device.
 188  *
 189  * @param dev
 190  *   Raw device pointer
 191  *
 192  * @return
 193  * - 0 on success
 194  * - (-EAGAIN) if can't close as device is busy
 195  */
 196 typedef int (*rawdev_close_t)(struct rte_rawdev *dev);
 197
 198 /**
 199  * Reset a configured device.
 200  *
 201  * @param dev
 202  *   Raw device pointer
 203  * @return
 204  *   0 for success
 205  *   !0 for failure
 206  */
 207 typedef int (*rawdev_reset_t)(struct rte_rawdev *dev);
 208
 209 /**
 210  * Retrieve the current raw queue configuration.
 211  *
 212  * @param dev
 213  *   Raw device pointer
 214  * @param queue_id
 215  *   Raw device queue index
 216  * @param[out] queue_conf
 217  *   Raw device queue configuration structure
 218  *
 219  */
 220 typedef void (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
 221                                         uint16_t queue_id,
 222                                         rte_rawdev_obj_t queue_conf);
 223
 224 /**
 225  * Setup an raw queue.
 226  *
 227  * @param dev
 228  *   Raw device pointer
 229  * @param queue_id
 230  *   Rawqueue index
 231  * @param queue_conf
 232  *   Rawqueue configuration structure
 233  *
 234  * @return
 235  *   Returns 0 on success.
 236  */
 237 typedef int (*rawdev_queue_setup_t)(struct rte_rawdev *dev,
 238                                     uint16_t queue_id,
 239                                     rte_rawdev_obj_t queue_conf);
 240
 241 /**
 242  * Release resources allocated by given raw queue.
 243  *
 244  * @param dev
 245  *   Raw device pointer
 246  * @param queue_id
 247  *   Raw queue index
 248  *
 249  */
 250 typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
 251                                       uint16_t queue_id);
 252
 253 /**
 254  * Dump internal information
 255  *
 256  * @param dev
 257  *   Raw device pointer
 258  * @param f
 259  *   A pointer to a file for output
 260  * @return
 261  *   0 for success,
 262  *   !0 Error
 263  *
 264  */
 265 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
 266
 267 /** Rawdevice operations function pointer table */
 268 struct rte_rawdev_ops {
 269         /**< Get device info. */
 270         rawdev_info_get_t dev_info_get;
 271         /**< Configure device. */
 272         rawdev_configure_t dev_configure;
 273         /**< Start device. */
 274         rawdev_start_t dev_start;
 275         /**< Stop device. */
 276         rawdev_stop_t dev_stop;
 277         /**< Close device. */
 278         rawdev_close_t dev_close;
 279         /**< Reset device. */
 280         rawdev_reset_t dev_reset;
 281
 282         /**< Get raw queue configuration. */
 283         rawdev_queue_conf_get_t queue_def_conf;
 284         /**< Set up an raw queue. */
 285         rawdev_queue_setup_t queue_setup;
 286         /**< Release an raw queue. */
 287         rawdev_queue_release_t queue_release;
 288
 289         /* Dump internal information */
 290         rawdev_dump_t dump;
 291 };
 292
 293 /**
 294  * Allocates a new rawdev slot for an raw device and returns the pointer
 295  * to that slot for the driver to use.
 296  *
 297  * @param name
 298  *   Unique identifier name for each device
 299  * @param dev_private_size
 300  *   Private data allocated within rte_rawdev object.
 301  * @param socket_id
 302  *   Socket to allocate resources on.
 303  * @return
 304  *   - Slot in the rte_dev_devices array for a new device;
 305  */
 306 struct rte_rawdev * __rte_experimental
 307 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
 308                         int socket_id);
 309
 310 /**
 311  * Release the specified rawdev device.
 312  *
 313  * @param rawdev
 314  * The *rawdev* pointer is the address of the *rte_rawdev* structure.
 315  * @return
 316  *   - 0 on success, negative on error
 317  */
 318 int __rte_experimental
 319 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
 320
 321 /**
 322  * Creates a new raw device and returns the pointer to that device.
 323  *
 324  * @param name
 325  *   Pointer to a character array containing name of the device
 326  * @param dev_private_size
 327  *   Size of raw PMDs private data
 328  * @param socket_id
 329  *   Socket to allocate resources on.
 330  *
 331  * @return
 332  *   - Raw device pointer if device is successfully created.
 333  *   - NULL if device cannot be created.
 334  */
 335 struct rte_rawdev * __rte_experimental
 336 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
 337                     int socket_id);
 338
 339 /**
 340  * Destroy a raw device
 341  *
 342  * @param name
 343  *   Name of the device
 344  * @return
 345  *   - 0 on success, negative on error
 346  */
 347 int __rte_experimental
 348 rte_rawdev_pmd_uninit(const char *name);
 349
 350 #ifdef __cplusplus
 351 }
 352 #endif
 353
 354 #endif /* _RTE_RAWDEV_PMD_H_ */