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