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