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 /**
 268  * Get an attribute value from implementation.
 269  * Attribute is an opaque handle agreed upon between application and PMD.
 270  *
 271  * @param dev
 272  *   Raw device pointer
 273  * @param attr_name
 274  *   Opaque object representing an attribute in implementation.
 275  * @param attr_value [out]
 276  *   Opaque response to the attribute value. In case of error, this remains
 277  *   untouched. This is double pointer of void type.
 278  * @return
 279  *   0 for success
 280  *  !0 Error; attr_value remains untouched in case of error.
 281  */
 282 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
 283                                  const char *attr_name,
 284                                  uint64_t *attr_value);
 285
 286 /**
 287  * Set an attribute value.
 288  * Attribute is an opaque handle agreed upon between application and PMD.
 289  *
 290  * @param dev
 291  *   Raw device pointer
 292  * @param attr_name
 293  *   Opaque object representing an attribute in implementation.
 294  * @param attr_value
 295  *   Value of the attribute represented by attr_name
 296  * @return
 297  *   0 for success
 298  *  !0 Error
 299  */
 300 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
 301                                  const char *attr_name,
 302                                  const uint64_t attr_value);
 303
 304 /** Rawdevice operations function pointer table */
 305 struct rte_rawdev_ops {
 306         /**< Get device info. */
 307         rawdev_info_get_t dev_info_get;
 308         /**< Configure device. */
 309         rawdev_configure_t dev_configure;
 310         /**< Start device. */
 311         rawdev_start_t dev_start;
 312         /**< Stop device. */
 313         rawdev_stop_t dev_stop;
 314         /**< Close device. */
 315         rawdev_close_t dev_close;
 316         /**< Reset device. */
 317         rawdev_reset_t dev_reset;
 318
 319         /**< Get raw queue configuration. */
 320         rawdev_queue_conf_get_t queue_def_conf;
 321         /**< Set up an raw queue. */
 322         rawdev_queue_setup_t queue_setup;
 323         /**< Release an raw queue. */
 324         rawdev_queue_release_t queue_release;
 325
 326         /* Dump internal information */
 327         rawdev_dump_t dump;
 328
 329         /**< Get an attribute managed by the implementation */
 330         rawdev_get_attr_t attr_get;
 331         /**< Set an attribute managed by the implementation */
 332         rawdev_set_attr_t attr_set;
 333 };
 334
 335 /**
 336  * Allocates a new rawdev slot for an raw device and returns the pointer
 337  * to that slot for the driver to use.
 338  *
 339  * @param name
 340  *   Unique identifier name for each device
 341  * @param dev_private_size
 342  *   Private data allocated within rte_rawdev object.
 343  * @param socket_id
 344  *   Socket to allocate resources on.
 345  * @return
 346  *   - Slot in the rte_dev_devices array for a new device;
 347  */
 348 struct rte_rawdev * __rte_experimental
 349 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
 350                         int socket_id);
 351
 352 /**
 353  * Release the specified rawdev device.
 354  *
 355  * @param rawdev
 356  * The *rawdev* pointer is the address of the *rte_rawdev* structure.
 357  * @return
 358  *   - 0 on success, negative on error
 359  */
 360 int __rte_experimental
 361 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
 362
 363 /**
 364  * Creates a new raw device and returns the pointer to that device.
 365  *
 366  * @param name
 367  *   Pointer to a character array containing name of the device
 368  * @param dev_private_size
 369  *   Size of raw PMDs private data
 370  * @param socket_id
 371  *   Socket to allocate resources on.
 372  *
 373  * @return
 374  *   - Raw device pointer if device is successfully created.
 375  *   - NULL if device cannot be created.
 376  */
 377 struct rte_rawdev * __rte_experimental
 378 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
 379                     int socket_id);
 380
 381 /**
 382  * Destroy a raw device
 383  *
 384  * @param name
 385  *   Name of the device
 386  * @return
 387  *   - 0 on success, negative on error
 388  */
 389 int __rte_experimental
 390 rte_rawdev_pmd_uninit(const char *name);
 391
 392 #ifdef __cplusplus
 393 }
 394 #endif
 395
 396 #endif /* _RTE_RAWDEV_PMD_H_ */