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  * Enqueue an array of raw buffers to the device.
 255  *
 256  * Buffer being used is opaque - it can be obtained from mempool or from
 257  * any other source. Interpretation of buffer is responsibility of driver.
 258  *
 259  * @param dev
 260  *   Raw device pointer
 261  * @param bufs
 262  *   array of buffers
 263  * @param count
 264  *   number of buffers passed
 265  * @param context
 266  *   an opaque object representing context of the call; for example, an
 267  *   application can pass information about the queues on which enqueue needs
 268  *   to be done. Or, the enqueue operation might be passed reference to an
 269  *   object containing a callback (agreed upon between applicatio and driver).
 270  *
 271  * @return
 272  *   >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
 273  *   <0 Error count in case of error
 274  */
 275 typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
 276                                      struct rte_rawdev_buf **buffers,
 277                                      unsigned int count,
 278                                      rte_rawdev_obj_t context);
 279
 280 /**
 281  * Dequeue an array of raw buffers from the device.
 282  *
 283  * @param dev
 284  *   Raw device pointer
 285  * @param bufs
 286  *   array of buffers
 287  * @param count
 288  *   Max buffers expected to be dequeued
 289  * @param context
 290  *   an opaque object representing context of the call. Based on this object,
 291  *   the application and driver can coordinate for dequeue operation involving
 292  *   agreed upon semantics. For example, queue information/id on which Dequeue
 293  *   needs to be performed.
 294  * @return
 295  *   >0, ~0: Count of buffers returned
 296  *   <0: Error
 297  *   Whether short dequeue is success or failure is decided between app and
 298  *   driver.
 299  */
 300 typedef int (*rawdev_dequeue_bufs_t)(struct rte_rawdev *dev,
 301                                      struct rte_rawdev_buf **buffers,
 302                                      unsigned int count,
 303                                      rte_rawdev_obj_t context);
 304
 305 /**
 306  * Dump internal information
 307  *
 308  * @param dev
 309  *   Raw device pointer
 310  * @param f
 311  *   A pointer to a file for output
 312  * @return
 313  *   0 for success,
 314  *   !0 Error
 315  *
 316  */
 317 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
 318
 319 /**
 320  * Get an attribute value from implementation.
 321  * Attribute is an opaque handle agreed upon between application and PMD.
 322  *
 323  * @param dev
 324  *   Raw device pointer
 325  * @param attr_name
 326  *   Opaque object representing an attribute in implementation.
 327  * @param attr_value [out]
 328  *   Opaque response to the attribute value. In case of error, this remains
 329  *   untouched. This is double pointer of void type.
 330  * @return
 331  *   0 for success
 332  *  !0 Error; attr_value remains untouched in case of error.
 333  */
 334 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
 335                                  const char *attr_name,
 336                                  uint64_t *attr_value);
 337
 338 /**
 339  * Set an attribute value.
 340  * Attribute is an opaque handle agreed upon between application and PMD.
 341  *
 342  * @param dev
 343  *   Raw device pointer
 344  * @param attr_name
 345  *   Opaque object representing an attribute in implementation.
 346  * @param attr_value
 347  *   Value of the attribute represented by attr_name
 348  * @return
 349  *   0 for success
 350  *  !0 Error
 351  */
 352 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
 353                                  const char *attr_name,
 354                                  const uint64_t attr_value);
 355
 356 /**
 357  * Retrieve a set of statistics from device.
 358  * Note: Being a raw device, the stats are specific to the device being
 359  * implemented thus represented as xstats.
 360  *
 361  * @param dev
 362  *   Raw device pointer
 363  * @param ids
 364  *   The stat ids to retrieve
 365  * @param values
 366  *   The returned stat values
 367  * @param n
 368  *   The number of id values and entries in the values array
 369  * @return
 370  *   The number of stat values successfully filled into the values array
 371  */
 372 typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev,
 373                 const unsigned int ids[], uint64_t values[], unsigned int n);
 374
 375 /**
 376  * Resets the statistic values in xstats for the device.
 377  */
 378 typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev,
 379                 const uint32_t ids[],
 380                 uint32_t nb_ids);
 381
 382 /**
 383  * Get names of extended stats of an raw device
 384  *
 385  * @param dev
 386  *   Raw device pointer
 387  * @param xstats_names
 388  *   Array of name values to be filled in
 389  * @param size
 390  *   Number of values in the xstats_names array
 391  * @return
 392  *   When size >= the number of stats, return the number of stat values filled
 393  *   into the array.
 394  *   When size < the number of available stats, return the number of stats
 395  *   values, and do not fill in any data into xstats_names.
 396  */
 397 typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev,
 398                 struct rte_rawdev_xstats_name *xstats_names,
 399                 unsigned int size);
 400
 401 /**
 402  * Get value of one stats and optionally return its id
 403  *
 404  * @param dev
 405  *   Raw device pointer
 406  * @param name
 407  *   The name of the stat to retrieve
 408  * @param id
 409  *   Pointer to an unsigned int where we store the stat-id.
 410  *   This pointer may be null if the id is not required.
 411  * @return
 412  *   The value of the stat, or (uint64_t)-1 if the stat is not found.
 413  *   If the stat is not found, the id value will be returned as (unsigned)-1,
 414  *   if id pointer is non-NULL
 415  */
 416 typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
 417                                                 const char *name,
 418                                                 unsigned int *id);
 419
 420 /**
 421  * Get firmware/device-stack status.
 422  * Implementation to allocate buffer for returning information.
 423  *
 424  * @param dev
 425  *   Raw device pointer
 426  * @param status
 427  *   void block containing device specific status information
 428  * @return
 429  *   0 for success,
 430  *   !0 for failure, with undefined value in `status_info`
 431  */
 432 typedef int (*rawdev_firmware_status_get_t)(struct rte_rawdev *dev,
 433                                             rte_rawdev_obj_t status_info);
 434
 435 /**
 436  * Get firmware version information
 437  *
 438  * @param dev
 439  *   Raw device pointer
 440  * @param version_info
 441  *   void pointer to version information returned by device
 442  * @return
 443  *   0 for success,
 444  *   !0 for failure, with undefined value in `version_info`
 445  */
 446 typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
 447                                              rte_rawdev_obj_t version_info);
 448
 449 /**
 450  * Load firwmare from a buffer (DMA'able)
 451  *
 452  * @param dev
 453  *   Raw device pointer
 454  * @param firmware_file
 455  *   file pointer to firmware area
 456  * @return
 457  *   >0, ~0: for successful load
 458  *   <0: for failure
 459  *
 460  * @see Application may use 'firmware_version_get` for ascertaining successful
 461  * load
 462  */
 463 typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev,
 464                                       rte_rawdev_obj_t firmware_buf);
 465
 466 /**
 467  * Unload firwmare
 468  *
 469  * @param dev
 470  *   Raw device pointer
 471  * @return
 472  *   >0, ~0 for successful unloading
 473  *   <0 for failure in unloading
 474  *
 475  * Note: Application can use the `firmware_status_get` or
 476  * `firmware_version_get` to get result of unload.
 477  */
 478 typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev);
 479
 480 /**
 481  * Start rawdev selftest
 482  *
 483  * @return
 484  *   Return 0 on success
 485  */
 486 typedef int (*rawdev_selftest_t)(void);
 487
 488 /** Rawdevice operations function pointer table */
 489 struct rte_rawdev_ops {
 490         /**< Get device info. */
 491         rawdev_info_get_t dev_info_get;
 492         /**< Configure device. */
 493         rawdev_configure_t dev_configure;
 494         /**< Start device. */
 495         rawdev_start_t dev_start;
 496         /**< Stop device. */
 497         rawdev_stop_t dev_stop;
 498         /**< Close device. */
 499         rawdev_close_t dev_close;
 500         /**< Reset device. */
 501         rawdev_reset_t dev_reset;
 502
 503         /**< Get raw queue configuration. */
 504         rawdev_queue_conf_get_t queue_def_conf;
 505         /**< Set up an raw queue. */
 506         rawdev_queue_setup_t queue_setup;
 507         /**< Release an raw queue. */
 508         rawdev_queue_release_t queue_release;
 509
 510         /**< Enqueue an array of raw buffers to device. */
 511         rawdev_enqueue_bufs_t enqueue_bufs;
 512         /**< Dequeue an array of raw buffers from device. */
 513         /** TODO: Callback based enqueue and dequeue support */
 514         rawdev_dequeue_bufs_t dequeue_bufs;
 515
 516         /* Dump internal information */
 517         rawdev_dump_t dump;
 518
 519         /**< Get an attribute managed by the implementation */
 520         rawdev_get_attr_t attr_get;
 521         /**< Set an attribute managed by the implementation */
 522         rawdev_set_attr_t attr_set;
 523
 524         /**< Get extended device statistics. */
 525         rawdev_xstats_get_t xstats_get;
 526         /**< Get names of extended stats. */
 527         rawdev_xstats_get_names_t xstats_get_names;
 528         /**< Get one value by name. */
 529         rawdev_xstats_get_by_name_t xstats_get_by_name;
 530         /**< Reset the statistics values in xstats. */
 531         rawdev_xstats_reset_t xstats_reset;
 532
 533         /**< Obtainer firmware status */
 534         rawdev_firmware_status_get_t firmware_status_get;
 535         /**< Obtain firmware version information */
 536         rawdev_firmware_version_get_t firmware_version_get;
 537         /**< Load firmware */
 538         rawdev_firmware_load_t firmware_load;
 539         /**< Unload firmware */
 540         rawdev_firmware_unload_t firmware_unload;
 541
 542         /**< Device selftest function */
 543         rawdev_selftest_t dev_selftest;
 544 };
 545
 546 /**
 547  * Allocates a new rawdev slot for an raw device and returns the pointer
 548  * to that slot for the driver to use.
 549  *
 550  * @param name
 551  *   Unique identifier name for each device
 552  * @param dev_private_size
 553  *   Private data allocated within rte_rawdev object.
 554  * @param socket_id
 555  *   Socket to allocate resources on.
 556  * @return
 557  *   - Slot in the rte_dev_devices array for a new device;
 558  */
 559 struct rte_rawdev * __rte_experimental
 560 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
 561                         int socket_id);
 562
 563 /**
 564  * Release the specified rawdev device.
 565  *
 566  * @param rawdev
 567  * The *rawdev* pointer is the address of the *rte_rawdev* structure.
 568  * @return
 569  *   - 0 on success, negative on error
 570  */
 571 int __rte_experimental
 572 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
 573
 574 /**
 575  * Creates a new raw device and returns the pointer to that device.
 576  *
 577  * @param name
 578  *   Pointer to a character array containing name of the device
 579  * @param dev_private_size
 580  *   Size of raw PMDs private data
 581  * @param socket_id
 582  *   Socket to allocate resources on.
 583  *
 584  * @return
 585  *   - Raw device pointer if device is successfully created.
 586  *   - NULL if device cannot be created.
 587  */
 588 struct rte_rawdev * __rte_experimental
 589 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
 590                     int socket_id);
 591
 592 /**
 593  * Destroy a raw device
 594  *
 595  * @param name
 596  *   Name of the device
 597  * @return
 598  *   - 0 on success, negative on error
 599  */
 600 int __rte_experimental
 601 rte_rawdev_pmd_uninit(const char *name);
 602
 603 #ifdef __cplusplus
 604 }
 605 #endif
 606
 607 #endif /* _RTE_RAWDEV_PMD_H_ */