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