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