lib/librte_eventdev/rte_eventdev_pmd.h

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