lib/librte_eventdev/rte_eventdev_pmd.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2016 Cavium, Inc
   3  */
   4
   5 #ifndef _RTE_EVENTDEV_PMD_H_
   6 #define _RTE_EVENTDEV_PMD_H_
   7
   8 /** @file
   9  * RTE Event PMD APIs
  10  *
  11  * @note
  12  * These API are from event PMD only and user applications should not call
  13  * them directly.
  14  */
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 #include <string.h>
  21
  22 #include <rte_common.h>
  23 #include <rte_config.h>
  24 #include <rte_dev.h>
  25 #include <rte_log.h>
  26 #include <rte_malloc.h>
  27
  28 #include "rte_eventdev.h"
  29
  30 /* Logging Macros */
  31 #define RTE_EDEV_LOG_ERR(...) \
  32         RTE_LOG(ERR, EVENTDEV, \
  33                 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \
  34                         __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,)))
  35
  36 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
  37 #define RTE_EDEV_LOG_DEBUG(...) \
  38         RTE_LOG(DEBUG, EVENTDEV, \
  39                 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \
  40                         __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,)))
  41 #else
  42 #define RTE_EDEV_LOG_DEBUG(...) (void)0
  43 #endif
  44
  45 /* Macros to check for valid device */
  46 #define RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
  47         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
  48                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
  49                 return retval; \
  50         } \
  51 } while (0)
  52
  53 #define RTE_EVENTDEV_VALID_DEVID_OR_RET(dev_id) do { \
  54         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
  55                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
  56                 return; \
  57         } \
  58 } while (0)
  59
  60 #define RTE_EVENT_ETH_RX_ADAPTER_SW_CAP \
  61                 ((RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) | \
  62                         (RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ))
  63
  64 /**< Ethernet Rx adapter cap to return If the packet transfers from
  65  * the ethdev to eventdev use a SW service function
  66  */
  67
  68 #define RTE_EVENTDEV_DETACHED  (0)
  69 #define RTE_EVENTDEV_ATTACHED  (1)
  70
  71 struct rte_eth_dev;
  72
  73 /** Global structure used for maintaining state of allocated event devices */
  74 struct rte_eventdev_global {
  75         uint8_t nb_devs;        /**< Number of devices found */
  76 };
  77
  78 extern struct rte_eventdev_global *rte_eventdev_globals;
  79 /** Pointer to global event devices data structure. */
  80 extern struct rte_eventdev *rte_eventdevs;
  81 /** The pool of rte_eventdev structures. */
  82
  83 /**
  84  * Get the rte_eventdev structure device pointer for the named device.
  85  *
  86  * @param name
  87  *   device name to select the device structure.
  88  *
  89  * @return
  90  *   - The rte_eventdev structure pointer for the given device ID.
  91  */
  92 static inline struct rte_eventdev *
  93 rte_event_pmd_get_named_dev(const char *name)
  94 {
  95         struct rte_eventdev *dev;
  96         unsigned int i;
  97
  98         if (name == NULL)
  99                 return NULL;
 100
 101         for (i = 0; i < RTE_EVENT_MAX_DEVS; i++) {
 102                 dev = &rte_eventdevs[i];
 103                 if ((dev->attached == RTE_EVENTDEV_ATTACHED) &&
 104                                 (strcmp(dev->data->name, name) == 0))
 105                         return dev;
 106         }
 107
 108         return NULL;
 109 }
 110
 111 /**
 112  * Validate if the event device index is valid attached event device.
 113  *
 114  * @param dev_id
 115  *   Event device index.
 116  *
 117  * @return
 118  *   - If the device index is valid (1) or not (0).
 119  */
 120 static inline unsigned
 121 rte_event_pmd_is_valid_dev(uint8_t dev_id)
 122 {
 123         struct rte_eventdev *dev;
 124
 125         if (dev_id >= RTE_EVENT_MAX_DEVS)
 126                 return 0;
 127
 128         dev = &rte_eventdevs[dev_id];
 129         if (dev->attached != RTE_EVENTDEV_ATTACHED)
 130                 return 0;
 131         else
 132                 return 1;
 133 }
 134
 135 /**
 136  * Definitions of all functions exported by a driver through the
 137  * the generic structure of type *event_dev_ops* supplied in the
 138  * *rte_eventdev* structure associated with a device.
 139  */
 140
 141 /**
 142  * Get device information of a device.
 143  *
 144  * @param dev
 145  *   Event device pointer
 146  * @param dev_info
 147  *   Event device information structure
 148  *
 149  * @return
 150  *   Returns 0 on success
 151  */
 152 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev,
 153                 struct rte_event_dev_info *dev_info);
 154
 155 /**
 156  * Configure a device.
 157  *
 158  * @param dev
 159  *   Event device pointer
 160  *
 161  * @return
 162  *   Returns 0 on success
 163  */
 164 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev);
 165
 166 /**
 167  * Start a configured device.
 168  *
 169  * @param dev
 170  *   Event device pointer
 171  *
 172  * @return
 173  *   Returns 0 on success
 174  */
 175 typedef int (*eventdev_start_t)(struct rte_eventdev *dev);
 176
 177 /**
 178  * Stop a configured device.
 179  *
 180  * @param dev
 181  *   Event device pointer
 182  */
 183 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev);
 184
 185 /**
 186  * Close a configured device.
 187  *
 188  * @param dev
 189  *   Event device pointer
 190  *
 191  * @return
 192  * - 0 on success
 193  * - (-EAGAIN) if can't close as device is busy
 194  */
 195 typedef int (*eventdev_close_t)(struct rte_eventdev *dev);
 196
 197 /**
 198  * Retrieve the default event queue configuration.
 199  *
 200  * @param dev
 201  *   Event device pointer
 202  * @param queue_id
 203  *   Event queue index
 204  * @param[out] queue_conf
 205  *   Event queue configuration structure
 206  *
 207  */
 208 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev,
 209                 uint8_t queue_id, struct rte_event_queue_conf *queue_conf);
 210
 211 /**
 212  * Setup an event queue.
 213  *
 214  * @param dev
 215  *   Event device pointer
 216  * @param queue_id
 217  *   Event queue index
 218  * @param queue_conf
 219  *   Event queue configuration structure
 220  *
 221  * @return
 222  *   Returns 0 on success.
 223  */
 224 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev,
 225                 uint8_t queue_id,
 226                 const struct rte_event_queue_conf *queue_conf);
 227
 228 /**
 229  * Release resources allocated by given event queue.
 230  *
 231  * @param dev
 232  *   Event device pointer
 233  * @param queue_id
 234  *   Event queue index
 235  *
 236  */
 237 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev,
 238                 uint8_t queue_id);
 239
 240 /**
 241  * Retrieve the default event port configuration.
 242  *
 243  * @param dev
 244  *   Event device pointer
 245  * @param port_id
 246  *   Event port index
 247  * @param[out] port_conf
 248  *   Event port configuration structure
 249  *
 250  */
 251 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev,
 252                 uint8_t port_id, struct rte_event_port_conf *port_conf);
 253
 254 /**
 255  * Setup an event port.
 256  *
 257  * @param dev
 258  *   Event device pointer
 259  * @param port_id
 260  *   Event port index
 261  * @param port_conf
 262  *   Event port configuration structure
 263  *
 264  * @return
 265  *   Returns 0 on success.
 266  */
 267 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
 268                 uint8_t port_id,
 269                 const struct rte_event_port_conf *port_conf);
 270
 271 /**
 272  * Release memory resources allocated by given event port.
 273  *
 274  * @param port
 275  *   Event port pointer
 276  *
 277  */
 278 typedef void (*eventdev_port_release_t)(void *port);
 279
 280 /**
 281  * Link multiple source event queues to destination event port.
 282  *
 283  * @param dev
 284  *   Event device pointer
 285  * @param port
 286  *   Event port pointer
 287  * @param link
 288  *   Points to an array of *nb_links* event queues to be linked
 289  *   to the event port.
 290  * @param priorities
 291  *   Points to an array of *nb_links* service priorities associated with each
 292  *   event queue link to event port.
 293  * @param nb_links
 294  *   The number of links to establish
 295  *
 296  * @return
 297  *   Returns 0 on success.
 298  *
 299  */
 300 typedef int (*eventdev_port_link_t)(struct rte_eventdev *dev, void *port,
 301                 const uint8_t queues[], const uint8_t priorities[],
 302                 uint16_t nb_links);
 303
 304 /**
 305  * Unlink multiple source event queues from destination event port.
 306  *
 307  * @param dev
 308  *   Event device pointer
 309  * @param port
 310  *   Event port pointer
 311  * @param queues
 312  *   An array of *nb_unlinks* event queues to be unlinked from the event port.
 313  * @param nb_unlinks
 314  *   The number of unlinks to establish
 315  *
 316  * @return
 317  *   Returns 0 on success.
 318  *
 319  */
 320 typedef int (*eventdev_port_unlink_t)(struct rte_eventdev *dev, void *port,
 321                 uint8_t queues[], uint16_t nb_unlinks);
 322
 323 /**
 324  * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue()
 325  *
 326  * @param dev
 327  *   Event device pointer
 328  * @param ns
 329  *   Wait time in nanosecond
 330  * @param[out] timeout_ticks
 331  *   Value for the *timeout_ticks* parameter in rte_event_dequeue() function
 332  *
 333  * @return
 334  *   Returns 0 on success.
 335  *
 336  */
 337 typedef int (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev,
 338                 uint64_t ns, uint64_t *timeout_ticks);
 339
 340 /**
 341  * Dump internal information
 342  *
 343  * @param dev
 344  *   Event device pointer
 345  * @param f
 346  *   A pointer to a file for output
 347  *
 348  */
 349 typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
 350
 351 /**
 352  * Retrieve a set of statistics from device
 353  *
 354  * @param dev
 355  *   Event device pointer
 356  * @param ids
 357  *   The stat ids to retrieve
 358  * @param values
 359  *   The returned stat values
 360  * @param n
 361  *   The number of id values and entries in the values array
 362  * @return
 363  *   The number of stat values successfully filled into the values array
 364  */
 365 typedef int (*eventdev_xstats_get_t)(const struct rte_eventdev *dev,
 366                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
 367                 const unsigned int ids[], uint64_t values[], unsigned int n);
 368
 369 /**
 370  * Resets the statistic values in xstats for the device, based on mode.
 371  */
 372 typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev,
 373                 enum rte_event_dev_xstats_mode mode,
 374                 int16_t queue_port_id,
 375                 const uint32_t ids[],
 376                 uint32_t nb_ids);
 377
 378 /**
 379  * Get names of extended stats of an event device
 380  *
 381  * @param dev
 382  *   Event device pointer
 383  * @param xstats_names
 384  *   Array of name values to be filled in
 385  * @param size
 386  *   Number of values in the xstats_names array
 387  * @return
 388  *   When size >= the number of stats, return the number of stat values filled
 389  *   into the array.
 390  *   When size < the number of available stats, return the number of stats
 391  *   values, and do not fill in any data into xstats_names.
 392  */
 393 typedef int (*eventdev_xstats_get_names_t)(const struct rte_eventdev *dev,
 394                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
 395                 struct rte_event_dev_xstats_name *xstats_names,
 396                 unsigned int *ids, unsigned int size);
 397
 398 /**
 399  * Get value of one stats and optionally return its id
 400  *
 401  * @param dev
 402  *   Event device pointer
 403  * @param name
 404  *   The name of the stat to retrieve
 405  * @param id
 406  *   Pointer to an unsigned int where we store the stat-id for future reference.
 407  *   This pointer may be null if the id is not required.
 408  * @return
 409  *   The value of the stat, or (uint64_t)-1 if the stat is not found.
 410  *   If the stat is not found, the id value will be returned as (unsigned)-1,
 411  *   if id pointer is non-NULL
 412  */
 413 typedef uint64_t (*eventdev_xstats_get_by_name)(const struct rte_eventdev *dev,
 414                 const char *name, unsigned int *id);
 415
 416
 417 /**
 418  * Retrieve the event device's ethdev Rx adapter capabilities for the
 419  * specified ethernet port
 420  *
 421  * @param dev
 422  *   Event device pointer
 423  *
 424  * @param eth_dev
 425  *   Ethernet device pointer
 426  *
 427  * @param[out] caps
 428  *   A pointer to memory filled with Rx event adapter capabilities.
 429  *
 430  * @return
 431  *   - 0: Success, driver provides Rx event adapter capabilities for the
 432  *      ethernet device.
 433  *   - <0: Error code returned by the driver function.
 434  *
 435  */
 436 typedef int (*eventdev_eth_rx_adapter_caps_get_t)
 437                                         (const struct rte_eventdev *dev,
 438                                         const struct rte_eth_dev *eth_dev,
 439                                         uint32_t *caps);
 440
 441 struct rte_event_eth_rx_adapter_queue_conf *queue_conf;
 442
 443 /**
 444  * Add ethernet Rx queues to event device. This callback is invoked if
 445  * the caps returned from rte_eventdev_eth_rx_adapter_caps_get(, eth_port_id)
 446  * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set.
 447  *
 448  * @param dev
 449  *   Event device pointer
 450  *
 451  * @param eth_dev
 452  *   Ethernet device pointer
 453  *
 454  * @param rx_queue_id
 455  *   Ethernet device receive queue index
 456  *
 457  * @param queue_conf
 458  *  Additional configuration structure
 459
 460  * @return
 461  *   - 0: Success, ethernet receive queue added successfully.
 462  *   - <0: Error code returned by the driver function.
 463  *
 464  */
 465 typedef int (*eventdev_eth_rx_adapter_queue_add_t)(
 466                 const struct rte_eventdev *dev,
 467                 const struct rte_eth_dev *eth_dev,
 468                 int32_t rx_queue_id,
 469                 const struct rte_event_eth_rx_adapter_queue_conf *queue_conf);
 470
 471 /**
 472  * Delete ethernet Rx queues from event device. This callback is invoked if
 473  * the caps returned from eventdev_eth_rx_adapter_caps_get(, eth_port_id)
 474  * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set.
 475  *
 476  * @param dev
 477  *   Event device pointer
 478  *
 479  * @param eth_dev
 480  *   Ethernet device pointer
 481  *
 482  * @param rx_queue_id
 483  *   Ethernet device receive queue index
 484  *
 485  * @return
 486  *   - 0: Success, ethernet receive queue deleted successfully.
 487  *   - <0: Error code returned by the driver function.
 488  *
 489  */
 490 typedef int (*eventdev_eth_rx_adapter_queue_del_t)
 491                                         (const struct rte_eventdev *dev,
 492                                         const struct rte_eth_dev *eth_dev,
 493                                         int32_t rx_queue_id);
 494
 495 /**
 496  * Start ethernet Rx adapter. This callback is invoked if
 497  * the caps returned from eventdev_eth_rx_adapter_caps_get(.., eth_port_id)
 498  * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set and Rx queues
 499  * from eth_port_id have been added to the event device.
 500  *
 501  * @param dev
 502  *   Event device pointer
 503  *
 504  * @param eth_dev
 505  *   Ethernet device pointer
 506  *
 507  * @return
 508  *   - 0: Success, ethernet Rx adapter started successfully.
 509  *   - <0: Error code returned by the driver function.
 510  */
 511 typedef int (*eventdev_eth_rx_adapter_start_t)
 512                                         (const struct rte_eventdev *dev,
 513                                         const struct rte_eth_dev *eth_dev);
 514
 515 /**
 516  * Stop ethernet Rx adapter. This callback is invoked if
 517  * the caps returned from eventdev_eth_rx_adapter_caps_get(..,eth_port_id)
 518  * has RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT set and Rx queues
 519  * from eth_port_id have been added to the event device.
 520  *
 521  * @param dev
 522  *   Event device pointer
 523  *
 524  * @param eth_dev
 525  *   Ethernet device pointer
 526  *
 527  * @return
 528  *   - 0: Success, ethernet Rx adapter stopped successfully.
 529  *   - <0: Error code returned by the driver function.
 530  */
 531 typedef int (*eventdev_eth_rx_adapter_stop_t)
 532                                         (const struct rte_eventdev *dev,
 533                                         const struct rte_eth_dev *eth_dev);
 534
 535 struct rte_event_eth_rx_adapter_stats *stats;
 536
 537 /**
 538  * Retrieve ethernet Rx adapter statistics.
 539  *
 540  * @param dev
 541  *   Event device pointer
 542  *
 543  * @param eth_dev
 544  *   Ethernet device pointer
 545  *
 546  * @param[out] stats
 547  *   Pointer to stats structure
 548  *
 549  * @return
 550  *   Return 0 on success.
 551  */
 552
 553 typedef int (*eventdev_eth_rx_adapter_stats_get)
 554                         (const struct rte_eventdev *dev,
 555                         const struct rte_eth_dev *eth_dev,
 556                         struct rte_event_eth_rx_adapter_stats *stats);
 557 /**
 558  * Reset ethernet Rx adapter statistics.
 559  *
 560  * @param dev
 561  *   Event device pointer
 562  *
 563  * @param eth_dev
 564  *   Ethernet device pointer
 565  *
 566  * @return
 567  *   Return 0 on success.
 568  */
 569 typedef int (*eventdev_eth_rx_adapter_stats_reset)
 570                         (const struct rte_eventdev *dev,
 571                         const struct rte_eth_dev *eth_dev);
 572
 573 /** Event device operations function pointer table */
 574 struct rte_eventdev_ops {
 575         eventdev_info_get_t dev_infos_get;      /**< Get device info. */
 576         eventdev_configure_t dev_configure;     /**< Configure device. */
 577         eventdev_start_t dev_start;             /**< Start device. */
 578         eventdev_stop_t dev_stop;               /**< Stop device. */
 579         eventdev_close_t dev_close;             /**< Close device. */
 580
 581         eventdev_queue_default_conf_get_t queue_def_conf;
 582         /**< Get default queue configuration. */
 583         eventdev_queue_setup_t queue_setup;
 584         /**< Set up an event queue. */
 585         eventdev_queue_release_t queue_release;
 586         /**< Release an event queue. */
 587
 588         eventdev_port_default_conf_get_t port_def_conf;
 589         /**< Get default port configuration. */
 590         eventdev_port_setup_t port_setup;
 591         /**< Set up an event port. */
 592         eventdev_port_release_t port_release;
 593         /**< Release an event port. */
 594
 595         eventdev_port_link_t port_link;
 596         /**< Link event queues to an event port. */
 597         eventdev_port_unlink_t port_unlink;
 598         /**< Unlink event queues from an event port. */
 599         eventdev_dequeue_timeout_ticks_t timeout_ticks;
 600         /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
 601         eventdev_dump_t dump;
 602         /* Dump internal information */
 603
 604         eventdev_xstats_get_t xstats_get;
 605         /**< Get extended device statistics. */
 606         eventdev_xstats_get_names_t xstats_get_names;
 607         /**< Get names of extended stats. */
 608         eventdev_xstats_get_by_name xstats_get_by_name;
 609         /**< Get one value by name. */
 610         eventdev_xstats_reset_t xstats_reset;
 611         /**< Reset the statistics values in xstats. */
 612
 613         eventdev_eth_rx_adapter_caps_get_t eth_rx_adapter_caps_get;
 614         /**< Get ethernet Rx adapter capabilities */
 615         eventdev_eth_rx_adapter_queue_add_t eth_rx_adapter_queue_add;
 616         /**< Add Rx queues to ethernet Rx adapter */
 617         eventdev_eth_rx_adapter_queue_del_t eth_rx_adapter_queue_del;
 618         /**< Delete Rx queues from ethernet Rx adapter */
 619         eventdev_eth_rx_adapter_start_t eth_rx_adapter_start;
 620         /**< Start ethernet Rx adapter */
 621         eventdev_eth_rx_adapter_stop_t eth_rx_adapter_stop;
 622         /**< Stop ethernet Rx adapter */
 623         eventdev_eth_rx_adapter_stats_get eth_rx_adapter_stats_get;
 624         /**< Get ethernet Rx stats */
 625         eventdev_eth_rx_adapter_stats_reset eth_rx_adapter_stats_reset;
 626         /**< Reset ethernet Rx stats */
 627 };
 628
 629 /**
 630  * Allocates a new eventdev slot for an event device and returns the pointer
 631  * to that slot for the driver to use.
 632  *
 633  * @param name
 634  *   Unique identifier name for each device
 635  * @param socket_id
 636  *   Socket to allocate resources on.
 637  * @return
 638  *   - Slot in the rte_dev_devices array for a new device;
 639  */
 640 struct rte_eventdev *
 641 rte_event_pmd_allocate(const char *name, int socket_id);
 642
 643 /**
 644  * Release the specified eventdev device.
 645  *
 646  * @param eventdev
 647  * The *eventdev* pointer is the address of the *rte_eventdev* structure.
 648  * @return
 649  *   - 0 on success, negative on error
 650  */
 651 int
 652 rte_event_pmd_release(struct rte_eventdev *eventdev);
 653
 654 #ifdef __cplusplus
 655 }
 656 #endif
 657
 658 #endif /* _RTE_EVENTDEV_PMD_H_ */