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