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