lib/librte_eventdev/rte_eventdev_pmd.h

   1 /*
   2  *
   3  *   Copyright(c) 2016 Cavium networks. All rights reserved.
   4  *
   5  *   Redistribution and use in source and binary forms, with or without
   6  *   modification, are permitted provided that the following conditions
   7  *   are met:
   8  *
   9  *     * Redistributions of source code must retain the above copyright
  10  *       notice, this list of conditions and the following disclaimer.
  11  *     * Redistributions in binary form must reproduce the above copyright
  12  *       notice, this list of conditions and the following disclaimer in
  13  *       the documentation and/or other materials provided with the
  14  *       distribution.
  15  *     * Neither the name of Cavium networks nor the names of its
  16  *       contributors may be used to endorse or promote products derived
  17  *       from this software without specific prior written permission.
  18  *
  19  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef _RTE_EVENTDEV_PMD_H_
  33 #define _RTE_EVENTDEV_PMD_H_
  34
  35 /** @file
  36  * RTE Event PMD APIs
  37  *
  38  * @note
  39  * These API are from event PMD only and user applications should not call
  40  * them directly.
  41  */
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 #include <string.h>
  48
  49 #include <rte_dev.h>
  50 #include <rte_pci.h>
  51 #include <rte_malloc.h>
  52 #include <rte_log.h>
  53 #include <rte_common.h>
  54
  55 #include "rte_eventdev.h"
  56
  57 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
  58 #define RTE_PMD_DEBUG_TRACE(...) \
  59         rte_pmd_debug_trace(__func__, __VA_ARGS__)
  60 #else
  61 #define RTE_PMD_DEBUG_TRACE(...)
  62 #endif
  63
  64 /* Logging Macros */
  65 #define RTE_EDEV_LOG_ERR(fmt, args...) \
  66         RTE_LOG(ERR, EVENTDEV, "%s() line %u: " fmt "\n",  \
  67                         __func__, __LINE__, ## args)
  68
  69 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
  70 #define RTE_EDEV_LOG_DEBUG(fmt, args...) \
  71         RTE_LOG(DEBUG, EVENTDEV, "%s() line %u: " fmt "\n",  \
  72                         __func__, __LINE__, ## args)
  73 #else
  74 #define RTE_EDEV_LOG_DEBUG(fmt, args...) (void)0
  75 #endif
  76
  77 /* Macros to check for valid device */
  78 #define RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
  79         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
  80                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
  81                 return retval; \
  82         } \
  83 } while (0)
  84
  85 #define RTE_EVENTDEV_VALID_DEVID_OR_RET(dev_id) do { \
  86         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
  87                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
  88                 return; \
  89         } \
  90 } while (0)
  91
  92 #define RTE_EVENTDEV_DETACHED  (0)
  93 #define RTE_EVENTDEV_ATTACHED  (1)
  94
  95 /**
  96  * Initialisation function of a event driver invoked for each matching
  97  * event PCI device detected during the PCI probing phase.
  98  *
  99  * @param dev
 100  *   The dev pointer is the address of the *rte_eventdev* structure associated
 101  *   with the matching device and which has been [automatically] allocated in
 102  *   the *rte_event_devices* array.
 103  *
 104  * @return
 105  *   - 0: Success, the device is properly initialised by the driver.
 106  *        In particular, the driver MUST have set up the *dev_ops* pointer
 107  *        of the *dev* structure.
 108  *   - <0: Error code of the device initialisation failure.
 109  */
 110 typedef int (*eventdev_init_t)(struct rte_eventdev *dev);
 111
 112 /**
 113  * Finalisation function of a driver invoked for each matching
 114  * PCI device detected during the PCI closing phase.
 115  *
 116  * @param dev
 117  *   The dev pointer is the address of the *rte_eventdev* structure associated
 118  *   with the matching device and which has been [automatically] allocated in
 119  *   the *rte_event_devices* array.
 120  *
 121  * @return
 122  *   - 0: Success, the device is properly finalised by the driver.
 123  *        In particular, the driver MUST free the *dev_ops* pointer
 124  *        of the *dev* structure.
 125  *   - <0: Error code of the device initialisation failure.
 126  */
 127 typedef int (*eventdev_uninit_t)(struct rte_eventdev *dev);
 128
 129 /**
 130  * The structure associated with a PMD driver.
 131  *
 132  * Each driver acts as a PCI driver and is represented by a generic
 133  * *event_driver* structure that holds:
 134  *
 135  * - An *rte_pci_driver* structure (which must be the first field).
 136  *
 137  * - The *eventdev_init* function invoked for each matching PCI device.
 138  *
 139  * - The size of the private data to allocate for each matching device.
 140  */
 141 struct rte_eventdev_driver {
 142         struct rte_pci_driver pci_drv;  /**< The PMD is also a PCI driver. */
 143         unsigned int dev_private_size;  /**< Size of device private data. */
 144
 145         eventdev_init_t eventdev_init;  /**< Device init function. */
 146         eventdev_uninit_t eventdev_uninit; /**< Device uninit function. */
 147 };
 148
 149 /** Global structure used for maintaining state of allocated event devices */
 150 struct rte_eventdev_global {
 151         uint8_t nb_devs;        /**< Number of devices found */
 152 };
 153
 154 extern struct rte_eventdev_global *rte_eventdev_globals;
 155 /** Pointer to global event devices data structure. */
 156 extern struct rte_eventdev *rte_eventdevs;
 157 /** The pool of rte_eventdev structures. */
 158
 159 /**
 160  * Get the rte_eventdev structure device pointer for the named device.
 161  *
 162  * @param name
 163  *   device name to select the device structure.
 164  *
 165  * @return
 166  *   - The rte_eventdev structure pointer for the given device ID.
 167  */
 168 static inline struct rte_eventdev *
 169 rte_event_pmd_get_named_dev(const char *name)
 170 {
 171         struct rte_eventdev *dev;
 172         unsigned int i;
 173
 174         if (name == NULL)
 175                 return NULL;
 176
 177         for (i = 0; i < RTE_EVENT_MAX_DEVS; i++) {
 178                 dev = &rte_eventdevs[i];
 179                 if ((dev->attached == RTE_EVENTDEV_ATTACHED) &&
 180                                 (strcmp(dev->data->name, name) == 0))
 181                         return dev;
 182         }
 183
 184         return NULL;
 185 }
 186
 187 /**
 188  * Validate if the event device index is valid attached event device.
 189  *
 190  * @param dev_id
 191  *   Event device index.
 192  *
 193  * @return
 194  *   - If the device index is valid (1) or not (0).
 195  */
 196 static inline unsigned
 197 rte_event_pmd_is_valid_dev(uint8_t dev_id)
 198 {
 199         struct rte_eventdev *dev;
 200
 201         if (dev_id >= RTE_EVENT_MAX_DEVS)
 202                 return 0;
 203
 204         dev = &rte_eventdevs[dev_id];
 205         if (dev->attached != RTE_EVENTDEV_ATTACHED)
 206                 return 0;
 207         else
 208                 return 1;
 209 }
 210
 211 /**
 212  * Definitions of all functions exported by a driver through the
 213  * the generic structure of type *event_dev_ops* supplied in the
 214  * *rte_eventdev* structure associated with a device.
 215  */
 216
 217 /**
 218  * Get device information of a device.
 219  *
 220  * @param dev
 221  *   Event device pointer
 222  * @param dev_info
 223  *   Event device information structure
 224  *
 225  * @return
 226  *   Returns 0 on success
 227  */
 228 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev,
 229                 struct rte_event_dev_info *dev_info);
 230
 231 /**
 232  * Configure a device.
 233  *
 234  * @param dev
 235  *   Event device pointer
 236  *
 237  * @return
 238  *   Returns 0 on success
 239  */
 240 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev);
 241
 242 /**
 243  * Start a configured device.
 244  *
 245  * @param dev
 246  *   Event device pointer
 247  *
 248  * @return
 249  *   Returns 0 on success
 250  */
 251 typedef int (*eventdev_start_t)(struct rte_eventdev *dev);
 252
 253 /**
 254  * Stop a configured device.
 255  *
 256  * @param dev
 257  *   Event device pointer
 258  */
 259 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev);
 260
 261 /**
 262  * Close a configured device.
 263  *
 264  * @param dev
 265  *   Event device pointer
 266  *
 267  * @return
 268  * - 0 on success
 269  * - (-EAGAIN) if can't close as device is busy
 270  */
 271 typedef int (*eventdev_close_t)(struct rte_eventdev *dev);
 272
 273 /**
 274  * Retrieve the default event queue configuration.
 275  *
 276  * @param dev
 277  *   Event device pointer
 278  * @param queue_id
 279  *   Event queue index
 280  * @param[out] queue_conf
 281  *   Event queue configuration structure
 282  *
 283  */
 284 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev,
 285                 uint8_t queue_id, struct rte_event_queue_conf *queue_conf);
 286
 287 /**
 288  * Setup an event queue.
 289  *
 290  * @param dev
 291  *   Event device pointer
 292  * @param queue_id
 293  *   Event queue index
 294  * @param queue_conf
 295  *   Event queue configuration structure
 296  *
 297  * @return
 298  *   Returns 0 on success.
 299  */
 300 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev,
 301                 uint8_t queue_id,
 302                 const struct rte_event_queue_conf *queue_conf);
 303
 304 /**
 305  * Release resources allocated by given event queue.
 306  *
 307  * @param dev
 308  *   Event device pointer
 309  * @param queue_id
 310  *   Event queue index
 311  *
 312  */
 313 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev,
 314                 uint8_t queue_id);
 315
 316 /**
 317  * Retrieve the default event port configuration.
 318  *
 319  * @param dev
 320  *   Event device pointer
 321  * @param port_id
 322  *   Event port index
 323  * @param[out] port_conf
 324  *   Event port configuration structure
 325  *
 326  */
 327 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev,
 328                 uint8_t port_id, struct rte_event_port_conf *port_conf);
 329
 330 /**
 331  * Setup an event port.
 332  *
 333  * @param dev
 334  *   Event device pointer
 335  * @param port_id
 336  *   Event port index
 337  * @param port_conf
 338  *   Event port configuration structure
 339  *
 340  * @return
 341  *   Returns 0 on success.
 342  */
 343 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
 344                 uint8_t port_id,
 345                 const struct rte_event_port_conf *port_conf);
 346
 347 /**
 348  * Release memory resources allocated by given event port.
 349  *
 350  * @param port
 351  *   Event port pointer
 352  *
 353  */
 354 typedef void (*eventdev_port_release_t)(void *port);
 355
 356 /**
 357  * Link multiple source event queues to destination event port.
 358  *
 359  * @param dev
 360  *   Event device pointer
 361  * @param port
 362  *   Event port pointer
 363  * @param link
 364  *   Points to an array of *nb_links* event queues to be linked
 365  *   to the event port.
 366  * @param priorities
 367  *   Points to an array of *nb_links* service priorities associated with each
 368  *   event queue link to event port.
 369  * @param nb_links
 370  *   The number of links to establish
 371  *
 372  * @return
 373  *   Returns 0 on success.
 374  *
 375  */
 376 typedef int (*eventdev_port_link_t)(struct rte_eventdev *dev, void *port,
 377                 const uint8_t queues[], const uint8_t priorities[],
 378                 uint16_t nb_links);
 379
 380 /**
 381  * Unlink multiple source event queues from destination event port.
 382  *
 383  * @param dev
 384  *   Event device pointer
 385  * @param port
 386  *   Event port pointer
 387  * @param queues
 388  *   An array of *nb_unlinks* event queues to be unlinked from the event port.
 389  * @param nb_unlinks
 390  *   The number of unlinks to establish
 391  *
 392  * @return
 393  *   Returns 0 on success.
 394  *
 395  */
 396 typedef int (*eventdev_port_unlink_t)(struct rte_eventdev *dev, void *port,
 397                 uint8_t queues[], uint16_t nb_unlinks);
 398
 399 /**
 400  * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue()
 401  *
 402  * @param dev
 403  *   Event device pointer
 404  * @param ns
 405  *   Wait time in nanosecond
 406  * @param[out] timeout_ticks
 407  *   Value for the *timeout_ticks* parameter in rte_event_dequeue() function
 408  *
 409  * @return
 410  *   Returns 0 on success.
 411  *
 412  */
 413 typedef int (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev,
 414                 uint64_t ns, uint64_t *timeout_ticks);
 415
 416 /**
 417  * Dump internal information
 418  *
 419  * @param dev
 420  *   Event device pointer
 421  * @param f
 422  *   A pointer to a file for output
 423  *
 424  */
 425 typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
 426
 427 /**
 428  * Retrieve a set of statistics from device
 429  *
 430  * @param dev
 431  *   Event device pointer
 432  * @param ids
 433  *   The stat ids to retrieve
 434  * @param values
 435  *   The returned stat values
 436  * @param n
 437  *   The number of id values and entries in the values array
 438  * @return
 439  *   The number of stat values successfully filled into the values array
 440  */
 441 typedef int (*eventdev_xstats_get_t)(const struct rte_eventdev *dev,
 442                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
 443                 const unsigned int ids[], uint64_t values[], unsigned int n);
 444
 445 /**
 446  * Resets the statistic values in xstats for the device, based on mode.
 447  */
 448 typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev,
 449                 enum rte_event_dev_xstats_mode mode,
 450                 int16_t queue_port_id,
 451                 const uint32_t ids[],
 452                 uint32_t nb_ids);
 453
 454 /**
 455  * Get names of extended stats of an event device
 456  *
 457  * @param dev
 458  *   Event device pointer
 459  * @param xstats_names
 460  *   Array of name values to be filled in
 461  * @param size
 462  *   Number of values in the xstats_names array
 463  * @return
 464  *   When size >= the number of stats, return the number of stat values filled
 465  *   into the array.
 466  *   When size < the number of available stats, return the number of stats
 467  *   values, and do not fill in any data into xstats_names.
 468  */
 469 typedef int (*eventdev_xstats_get_names_t)(const struct rte_eventdev *dev,
 470                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
 471                 struct rte_event_dev_xstats_name *xstats_names,
 472                 unsigned int *ids, unsigned int size);
 473
 474 /**
 475  * Get value of one stats and optionally return its id
 476  *
 477  * @param dev
 478  *   Event device pointer
 479  * @param name
 480  *   The name of the stat to retrieve
 481  * @param id
 482  *   Pointer to an unsigned int where we store the stat-id for future reference.
 483  *   This pointer may be null if the id is not required.
 484  * @return
 485  *   The value of the stat, or (uint64_t)-1 if the stat is not found.
 486  *   If the stat is not found, the id value will be returned as (unsigned)-1,
 487  *   if id pointer is non-NULL
 488  */
 489 typedef uint64_t (*eventdev_xstats_get_by_name)(const struct rte_eventdev *dev,
 490                 const char *name, unsigned int *id);
 491
 492 /** Event device operations function pointer table */
 493 struct rte_eventdev_ops {
 494         eventdev_info_get_t dev_infos_get;      /**< Get device info. */
 495         eventdev_configure_t dev_configure;     /**< Configure device. */
 496         eventdev_start_t dev_start;             /**< Start device. */
 497         eventdev_stop_t dev_stop;               /**< Stop device. */
 498         eventdev_close_t dev_close;             /**< Close device. */
 499
 500         eventdev_queue_default_conf_get_t queue_def_conf;
 501         /**< Get default queue configuration. */
 502         eventdev_queue_setup_t queue_setup;
 503         /**< Set up an event queue. */
 504         eventdev_queue_release_t queue_release;
 505         /**< Release an event queue. */
 506
 507         eventdev_port_default_conf_get_t port_def_conf;
 508         /**< Get default port configuration. */
 509         eventdev_port_setup_t port_setup;
 510         /**< Set up an event port. */
 511         eventdev_port_release_t port_release;
 512         /**< Release an event port. */
 513
 514         eventdev_port_link_t port_link;
 515         /**< Link event queues to an event port. */
 516         eventdev_port_unlink_t port_unlink;
 517         /**< Unlink event queues from an event port. */
 518         eventdev_dequeue_timeout_ticks_t timeout_ticks;
 519         /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
 520         eventdev_dump_t dump;
 521         /* Dump internal information */
 522
 523         eventdev_xstats_get_t xstats_get;
 524         /**< Get extended device statistics. */
 525         eventdev_xstats_get_names_t xstats_get_names;
 526         /**< Get names of extended stats. */
 527         eventdev_xstats_get_by_name xstats_get_by_name;
 528         /**< Get one value by name. */
 529         eventdev_xstats_reset_t xstats_reset;
 530         /**< Reset the statistics values in xstats. */
 531 };
 532
 533 /**
 534  * Allocates a new eventdev slot for an event device and returns the pointer
 535  * to that slot for the driver to use.
 536  *
 537  * @param name
 538  *   Unique identifier name for each device
 539  * @param socket_id
 540  *   Socket to allocate resources on.
 541  * @return
 542  *   - Slot in the rte_dev_devices array for a new device;
 543  */
 544 struct rte_eventdev *
 545 rte_event_pmd_allocate(const char *name, int socket_id);
 546
 547 /**
 548  * Release the specified eventdev device.
 549  *
 550  * @param eventdev
 551  * The *eventdev* pointer is the address of the *rte_eventdev* structure.
 552  * @return
 553  *   - 0 on success, negative on error
 554  */
 555 int
 556 rte_event_pmd_release(struct rte_eventdev *eventdev);
 557
 558 /**
 559  * Creates a new virtual event device and returns the pointer to that device.
 560  *
 561  * @param name
 562  *   PMD type name
 563  * @param dev_private_size
 564  *   Size of event PMDs private data
 565  * @param socket_id
 566  *   Socket to allocate resources on.
 567  *
 568  * @return
 569  *   - Eventdev pointer if device is successfully created.
 570  *   - NULL if device cannot be created.
 571  */
 572 struct rte_eventdev *
 573 rte_event_pmd_vdev_init(const char *name, size_t dev_private_size,
 574                 int socket_id);
 575
 576 /**
 577  * Destroy the given virtual event device
 578  *
 579  * @param name
 580  *   PMD type name
 581  * @return
 582  *   - 0 on success, negative on error
 583  */
 584 int
 585 rte_event_pmd_vdev_uninit(const char *name);
 586
 587 /**
 588  * Wrapper for use by pci drivers as a .probe function to attach to a event
 589  * interface.
 590  */
 591 int rte_event_pmd_pci_probe(struct rte_pci_driver *pci_drv,
 592                             struct rte_pci_device *pci_dev);
 593
 594 /**
 595  * Wrapper for use by pci drivers as a .remove function to detach a event
 596  * interface.
 597  */
 598 int rte_event_pmd_pci_remove(struct rte_pci_device *pci_dev);
 599
 600 #ifdef __cplusplus
 601 }
 602 #endif
 603
 604 #endif /* _RTE_EVENTDEV_PMD_H_ */