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
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 #include <string.h>
  21
  22 #include <rte_dev.h>
  23 #include <rte_malloc.h>
  24 #include <rte_log.h>
  25 #include <rte_common.h>
  26
  27 #include "rte_rawdev.h"
  28
  29 extern int librawdev_logtype;
  30
  31 /* Logging Macros */
  32 #define RTE_RDEV_LOG(level, fmt, args...) \
  33         rte_log(RTE_LOG_ ## level, librawdev_logtype, "%s(): " fmt "\n", \
  34                 __func__, ##args)
  35
  36 #define RTE_RDEV_ERR(fmt, args...) \
  37         RTE_RDEV_LOG(ERR, fmt, ## args)
  38 #define RTE_RDEV_DEBUG(fmt, args...) \
  39         RTE_RDEV_LOG(DEBUG, fmt, ## args)
  40 #define RTE_RDEV_INFO(fmt, args...) \
  41         RTE_RDEV_LOG(INFO, fmt, ## args)
  42
  43
  44 /* Macros to check for valid device */
  45 #define RTE_RAWDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
  46         if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
  47                 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
  48                 return retval; \
  49         } \
  50 } while (0)
  51
  52 #define RTE_RAWDEV_VALID_DEVID_OR_RET(dev_id) do { \
  53         if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
  54                 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
  55                 return; \
  56         } \
  57 } while (0)
  58
  59 #define RTE_RAWDEV_DETACHED  (0)
  60 #define RTE_RAWDEV_ATTACHED  (1)
  61
  62 /* Global structure used for maintaining state of allocated raw devices.
  63  *
  64  * TODO: Can be expanded to <type of raw device>:<count> in future.
  65  *       Applications should be able to select from a number of type of raw
  66  *       devices which were detected or attached to this DPDK instance.
  67  */
  68 struct rte_rawdev_global {
  69         /**< Number of devices found */
  70         uint16_t nb_devs;
  71 };
  72
  73 extern struct rte_rawdev *rte_rawdevs;
  74 /** The pool of rte_rawdev structures. */
  75
  76 /**
  77  * Get the rte_rawdev structure device pointer for the named device.
  78  *
  79  * @param name
  80  *   device name to select the device structure.
  81  *
  82  * @return
  83  *   - The rte_rawdev structure pointer for the given device ID.
  84  */
  85 static inline struct rte_rawdev *
  86 rte_rawdev_pmd_get_named_dev(const char *name)
  87 {
  88         struct rte_rawdev *dev;
  89         unsigned int i;
  90
  91         if (name == NULL)
  92                 return NULL;
  93
  94         for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) {
  95                 dev = &rte_rawdevs[i];
  96                 if ((dev->attached == RTE_RAWDEV_ATTACHED) &&
  97                    (strcmp(dev->name, name) == 0))
  98                         return dev;
  99         }
 100
 101         return NULL;
 102 }
 103
 104 /**
 105  * Validate if the raw device index is a valid attached raw device.
 106  *
 107  * @param dev_id
 108  *   raw device index.
 109  *
 110  * @return
 111  *   - If the device index is valid (1) or not (0).
 112  */
 113 static inline unsigned
 114 rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)
 115 {
 116         struct rte_rawdev *dev;
 117
 118         if (dev_id >= RTE_RAWDEV_MAX_DEVS)
 119                 return 0;
 120
 121         dev = &rte_rawdevs[dev_id];
 122         if (dev->attached != RTE_RAWDEV_ATTACHED)
 123                 return 0;
 124         else
 125                 return 1;
 126 }
 127
 128 /**
 129  * Definitions of all functions exported by a driver through the
 130  * the generic structure of type *rawdev_ops* supplied in the
 131  * *rte_rawdev* structure associated with a device.
 132  */
 133
 134 /**
 135  * Get device information of a device.
 136  *
 137  * @param dev
 138  *   Raw device pointer
 139  * @param dev_info
 140  *   Raw device information structure
 141  *
 142  * @return
 143  *   Returns 0 on success
 144  */
 145 typedef void (*rawdev_info_get_t)(struct rte_rawdev *dev,
 146                                   rte_rawdev_obj_t dev_info);
 147
 148 /**
 149  * Configure a device.
 150  *
 151  * @param dev
 152  *   Raw device pointer
 153  * @param config
 154  *   Void object containing device specific configuration
 155  *
 156  * @return
 157  *   Returns 0 on success
 158  */
 159 typedef int (*rawdev_configure_t)(const struct rte_rawdev *dev,
 160                                   rte_rawdev_obj_t config);
 161
 162 /**
 163  * Start a configured device.
 164  *
 165  * @param dev
 166  *   Raw device pointer
 167  *
 168  * @return
 169  *   Returns 0 on success
 170  */
 171 typedef int (*rawdev_start_t)(struct rte_rawdev *dev);
 172
 173 /**
 174  * Stop a configured device.
 175  *
 176  * @param dev
 177  *   Raw device pointer
 178  */
 179 typedef void (*rawdev_stop_t)(struct rte_rawdev *dev);
 180
 181 /**
 182  * Close a configured device.
 183  *
 184  * @param dev
 185  *   Raw device pointer
 186  *
 187  * @return
 188  * - 0 on success
 189  * - (-EAGAIN) if can't close as device is busy
 190  */
 191 typedef int (*rawdev_close_t)(struct rte_rawdev *dev);
 192
 193 /**
 194  * Reset a configured device.
 195  *
 196  * @param dev
 197  *   Raw device pointer
 198  * @return
 199  *   0 for success
 200  *   !0 for failure
 201  */
 202 typedef int (*rawdev_reset_t)(struct rte_rawdev *dev);
 203
 204 /**
 205  * Retrieve the current raw queue configuration.
 206  *
 207  * @param dev
 208  *   Raw device pointer
 209  * @param queue_id
 210  *   Raw device queue index
 211  * @param[out] queue_conf
 212  *   Raw device queue configuration structure
 213  *
 214  */
 215 typedef void (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
 216                                         uint16_t queue_id,
 217                                         rte_rawdev_obj_t queue_conf);
 218
 219 /**
 220  * Setup an raw queue.
 221  *
 222  * @param dev
 223  *   Raw device pointer
 224  * @param queue_id
 225  *   Rawqueue index
 226  * @param queue_conf
 227  *   Rawqueue configuration structure
 228  *
 229  * @return
 230  *   Returns 0 on success.
 231  */
 232 typedef int (*rawdev_queue_setup_t)(struct rte_rawdev *dev,
 233                                     uint16_t queue_id,
 234                                     rte_rawdev_obj_t queue_conf);
 235
 236 /**
 237  * Release resources allocated by given raw queue.
 238  *
 239  * @param dev
 240  *   Raw device pointer
 241  * @param queue_id
 242  *   Raw queue index
 243  *
 244  */
 245 typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
 246                                       uint16_t queue_id);
 247
 248 /**
 249  * Get the count of number of queues configured on this device.
 250  *
 251  * Another way to fetch this information is to fetch the device configuration.
 252  * But, that assumes that the device configuration managed by the driver has
 253  * that kind of information.
 254  *
 255  * This function helps in getting queue count supported, independently. It
 256  * can help in cases where iterator needs to be implemented.
 257  *
 258  * @param
 259  *   Raw device pointer
 260  * @return
 261  *   Number of queues; 0 is assumed to be a valid response.
 262  *
 263  */
 264 typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
 265
 266 /**
 267  * Enqueue an array of raw buffers to the device.
 268  *
 269  * Buffer being used is opaque - it can be obtained from mempool or from
 270  * any other source. Interpretation of buffer is responsibility of driver.
 271  *
 272  * @param dev
 273  *   Raw device pointer
 274  * @param bufs
 275  *   array of buffers
 276  * @param count
 277  *   number of buffers passed
 278  * @param context
 279  *   an opaque object representing context of the call; for example, an
 280  *   application can pass information about the queues on which enqueue needs
 281  *   to be done. Or, the enqueue operation might be passed reference to an
 282  *   object containing a callback (agreed upon between application and driver).
 283  *
 284  * @return
 285  *   >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
 286  *   <0 Error count in case of error
 287  */
 288 typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
 289                                      struct rte_rawdev_buf **buffers,
 290                                      unsigned int count,
 291                                      rte_rawdev_obj_t context);
 292
 293 /**
 294  * Dequeue an array of raw buffers from the device.
 295  *
 296  * @param dev
 297  *   Raw device pointer
 298  * @param bufs
 299  *   array of buffers
 300  * @param count
 301  *   Max buffers expected to be dequeued
 302  * @param context
 303  *   an opaque object representing context of the call. Based on this object,
 304  *   the application and driver can coordinate for dequeue operation involving
 305  *   agreed upon semantics. For example, queue information/id on which Dequeue
 306  *   needs to be performed.
 307  * @return
 308  *   >0, ~0: Count of buffers returned
 309  *   <0: Error
 310  *   Whether short dequeue is success or failure is decided between app and
 311  *   driver.
 312  */
 313 typedef int (*rawdev_dequeue_bufs_t)(struct rte_rawdev *dev,
 314                                      struct rte_rawdev_buf **buffers,
 315                                      unsigned int count,
 316                                      rte_rawdev_obj_t context);
 317
 318 /**
 319  * Dump internal information
 320  *
 321  * @param dev
 322  *   Raw device pointer
 323  * @param f
 324  *   A pointer to a file for output
 325  * @return
 326  *   0 for success,
 327  *   !0 Error
 328  *
 329  */
 330 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
 331
 332 /**
 333  * Get an attribute value from implementation.
 334  * Attribute is an opaque handle agreed upon between application and PMD.
 335  *
 336  * @param dev
 337  *   Raw device pointer
 338  * @param attr_name
 339  *   Opaque object representing an attribute in implementation.
 340  * @param attr_value [out]
 341  *   Opaque response to the attribute value. In case of error, this remains
 342  *   untouched. This is double pointer of void type.
 343  * @return
 344  *   0 for success
 345  *  !0 Error; attr_value remains untouched in case of error.
 346  */
 347 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
 348                                  const char *attr_name,
 349                                  uint64_t *attr_value);
 350
 351 /**
 352  * Set an attribute value.
 353  * Attribute is an opaque handle agreed upon between application and PMD.
 354  *
 355  * @param dev
 356  *   Raw device pointer
 357  * @param attr_name
 358  *   Opaque object representing an attribute in implementation.
 359  * @param attr_value
 360  *   Value of the attribute represented by attr_name
 361  * @return
 362  *   0 for success
 363  *  !0 Error
 364  */
 365 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
 366                                  const char *attr_name,
 367                                  const uint64_t attr_value);
 368
 369 /**
 370  * Retrieve a set of statistics from device.
 371  * Note: Being a raw device, the stats are specific to the device being
 372  * implemented thus represented as xstats.
 373  *
 374  * @param dev
 375  *   Raw device pointer
 376  * @param ids
 377  *   The stat ids to retrieve
 378  * @param values
 379  *   The returned stat values
 380  * @param n
 381  *   The number of id values and entries in the values array
 382  * @return
 383  *   The number of stat values successfully filled into the values array
 384  */
 385 typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev,
 386                 const unsigned int ids[], uint64_t values[], unsigned int n);
 387
 388 /**
 389  * Resets the statistic values in xstats for the device.
 390  */
 391 typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev,
 392                 const uint32_t ids[],
 393                 uint32_t nb_ids);
 394
 395 /**
 396  * Get names of extended stats of an raw device
 397  *
 398  * @param dev
 399  *   Raw device pointer
 400  * @param xstats_names
 401  *   Array of name values to be filled in
 402  * @param size
 403  *   Number of values in the xstats_names array
 404  * @return
 405  *   When size >= the number of stats, return the number of stat values filled
 406  *   into the array.
 407  *   When size < the number of available stats, return the number of stats
 408  *   values, and do not fill in any data into xstats_names.
 409  */
 410 typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev,
 411                 struct rte_rawdev_xstats_name *xstats_names,
 412                 unsigned int size);
 413
 414 /**
 415  * Get value of one stats and optionally return its id
 416  *
 417  * @param dev
 418  *   Raw device pointer
 419  * @param name
 420  *   The name of the stat to retrieve
 421  * @param id
 422  *   Pointer to an unsigned int where we store the stat-id.
 423  *   This pointer may be null if the id is not required.
 424  * @return
 425  *   The value of the stat, or (uint64_t)-1 if the stat is not found.
 426  *   If the stat is not found, the id value will be returned as (unsigned)-1,
 427  *   if id pointer is non-NULL
 428  */
 429 typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
 430                                                 const char *name,
 431                                                 unsigned int *id);
 432
 433 /**
 434  * Get firmware/device-stack status.
 435  * Implementation to allocate buffer for returning information.
 436  *
 437  * @param dev
 438  *   Raw device pointer
 439  * @param status
 440  *   void block containing device specific status information
 441  * @return
 442  *   0 for success,
 443  *   !0 for failure, with undefined value in `status_info`
 444  */
 445 typedef int (*rawdev_firmware_status_get_t)(struct rte_rawdev *dev,
 446                                             rte_rawdev_obj_t status_info);
 447
 448 /**
 449  * Get firmware version information
 450  *
 451  * @param dev
 452  *   Raw device pointer
 453  * @param version_info
 454  *   void pointer to version information returned by device
 455  * @return
 456  *   0 for success,
 457  *   !0 for failure, with undefined value in `version_info`
 458  */
 459 typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
 460                                              rte_rawdev_obj_t version_info);
 461
 462 /**
 463  * Load firmware from a buffer (DMA'able)
 464  *
 465  * @param dev
 466  *   Raw device pointer
 467  * @param firmware_file
 468  *   file pointer to firmware area
 469  * @return
 470  *   >0, ~0: for successful load
 471  *   <0: for failure
 472  *
 473  * @see Application may use 'firmware_version_get` for ascertaining successful
 474  * load
 475  */
 476 typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev,
 477                                       rte_rawdev_obj_t firmware_buf);
 478
 479 /**
 480  * Unload firmware
 481  *
 482  * @param dev
 483  *   Raw device pointer
 484  * @return
 485  *   >0, ~0 for successful unloading
 486  *   <0 for failure in unloading
 487  *
 488  * Note: Application can use the `firmware_status_get` or
 489  * `firmware_version_get` to get result of unload.
 490  */
 491 typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev);
 492
 493 /**
 494  * Start rawdev selftest
 495  *
 496  * @return
 497  *   Return 0 on success
 498  */
 499 typedef int (*rawdev_selftest_t)(uint16_t dev_id);
 500
 501 /** Rawdevice operations function pointer table */
 502 struct rte_rawdev_ops {
 503         /**< Get device info. */
 504         rawdev_info_get_t dev_info_get;
 505         /**< Configure device. */
 506         rawdev_configure_t dev_configure;
 507         /**< Start device. */
 508         rawdev_start_t dev_start;
 509         /**< Stop device. */
 510         rawdev_stop_t dev_stop;
 511         /**< Close device. */
 512         rawdev_close_t dev_close;
 513         /**< Reset device. */
 514         rawdev_reset_t dev_reset;
 515
 516         /**< Get raw queue configuration. */
 517         rawdev_queue_conf_get_t queue_def_conf;
 518         /**< Set up an raw queue. */
 519         rawdev_queue_setup_t queue_setup;
 520         /**< Release an raw queue. */
 521         rawdev_queue_release_t queue_release;
 522         /**< Get the number of queues attached to the device */
 523         rawdev_queue_count_t queue_count;
 524
 525         /**< Enqueue an array of raw buffers to device. */
 526         rawdev_enqueue_bufs_t enqueue_bufs;
 527         /**< Dequeue an array of raw buffers from device. */
 528         /** TODO: Callback based enqueue and dequeue support */
 529         rawdev_dequeue_bufs_t dequeue_bufs;
 530
 531         /* Dump internal information */
 532         rawdev_dump_t dump;
 533
 534         /**< Get an attribute managed by the implementation */
 535         rawdev_get_attr_t attr_get;
 536         /**< Set an attribute managed by the implementation */
 537         rawdev_set_attr_t attr_set;
 538
 539         /**< Get extended device statistics. */
 540         rawdev_xstats_get_t xstats_get;
 541         /**< Get names of extended stats. */
 542         rawdev_xstats_get_names_t xstats_get_names;
 543         /**< Get one value by name. */
 544         rawdev_xstats_get_by_name_t xstats_get_by_name;
 545         /**< Reset the statistics values in xstats. */
 546         rawdev_xstats_reset_t xstats_reset;
 547
 548         /**< Obtain firmware status */
 549         rawdev_firmware_status_get_t firmware_status_get;
 550         /**< Obtain firmware version information */
 551         rawdev_firmware_version_get_t firmware_version_get;
 552         /**< Load firmware */
 553         rawdev_firmware_load_t firmware_load;
 554         /**< Unload firmware */
 555         rawdev_firmware_unload_t firmware_unload;
 556
 557         /**< Device selftest function */
 558         rawdev_selftest_t dev_selftest;
 559 };
 560
 561 /**
 562  * Allocates a new rawdev slot for an raw device and returns the pointer
 563  * to that slot for the driver to use.
 564  *
 565  * @param name
 566  *   Unique identifier name for each device
 567  * @param dev_private_size
 568  *   Size of private data memory allocated within rte_rawdev object.
 569  *   Set to 0 to disable internal memory allocation and allow for
 570  *   self-allocation.
 571  * @param socket_id
 572  *   Socket to allocate resources on.
 573  * @return
 574  *   - Slot in the rte_dev_devices array for a new device;
 575  */
 576 struct rte_rawdev *
 577 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
 578                         int socket_id);
 579
 580 /**
 581  * Release the specified rawdev device.
 582  *
 583  * @param rawdev
 584  * The *rawdev* pointer is the address of the *rte_rawdev* structure.
 585  * @return
 586  *   - 0 on success, negative on error
 587  */
 588 int
 589 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
 590
 591 /**
 592  * Creates a new raw device and returns the pointer to that device.
 593  *
 594  * @param name
 595  *   Pointer to a character array containing name of the device
 596  * @param dev_private_size
 597  *   Size of raw PMDs private data
 598  * @param socket_id
 599  *   Socket to allocate resources on.
 600  *
 601  * @return
 602  *   - Raw device pointer if device is successfully created.
 603  *   - NULL if device cannot be created.
 604  */
 605 struct rte_rawdev *
 606 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
 607                     int socket_id);
 608
 609 /**
 610  * Destroy a raw device
 611  *
 612  * @param name
 613  *   Name of the device
 614  * @return
 615  *   - 0 on success, negative on error
 616  */
 617 int
 618 rte_rawdev_pmd_uninit(const char *name);
 619
 620 #ifdef __cplusplus
 621 }
 622 #endif
 623
 624 #endif /* _RTE_RAWDEV_PMD_H_ */