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         uint8_t max_devs;       /**< Max number of devices */
 153 };
 154
 155 extern struct rte_eventdev_global *rte_eventdev_globals;
 156 /** Pointer to global event devices data structure. */
 157 extern struct rte_eventdev *rte_eventdevs;
 158 /** The pool of rte_eventdev structures. */
 159
 160 /**
 161  * Get the rte_eventdev structure device pointer for the named device.
 162  *
 163  * @param name
 164  *   device name to select the device structure.
 165  *
 166  * @return
 167  *   - The rte_eventdev structure pointer for the given device ID.
 168  */
 169 static inline struct rte_eventdev *
 170 rte_event_pmd_get_named_dev(const char *name)
 171 {
 172         struct rte_eventdev *dev;
 173         unsigned int i;
 174
 175         if (name == NULL)
 176                 return NULL;
 177
 178         for (i = 0, dev = &rte_eventdevs[i];
 179                         i < rte_eventdev_globals->max_devs; i++) {
 180                 if ((dev->attached == RTE_EVENTDEV_ATTACHED) &&
 181                                 (strcmp(dev->data->name, name) == 0))
 182                         return dev;
 183         }
 184
 185         return NULL;
 186 }
 187
 188 /**
 189  * Validate if the event device index is valid attached event device.
 190  *
 191  * @param dev_id
 192  *   Event device index.
 193  *
 194  * @return
 195  *   - If the device index is valid (1) or not (0).
 196  */
 197 static inline unsigned
 198 rte_event_pmd_is_valid_dev(uint8_t dev_id)
 199 {
 200         struct rte_eventdev *dev;
 201
 202         if (dev_id >= rte_eventdev_globals->nb_devs)
 203                 return 0;
 204
 205         dev = &rte_eventdevs[dev_id];
 206         if (dev->attached != RTE_EVENTDEV_ATTACHED)
 207                 return 0;
 208         else
 209                 return 1;
 210 }
 211
 212 /**
 213  * Definitions of all functions exported by a driver through the
 214  * the generic structure of type *event_dev_ops* supplied in the
 215  * *rte_eventdev* structure associated with a device.
 216  */
 217
 218 /**
 219  * Get device information of a device.
 220  *
 221  * @param dev
 222  *   Event device pointer
 223  * @param dev_info
 224  *   Event device information structure
 225  *
 226  * @return
 227  *   Returns 0 on success
 228  */
 229 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev,
 230                 struct rte_event_dev_info *dev_info);
 231
 232 /**
 233  * Configure a device.
 234  *
 235  * @param dev
 236  *   Event device pointer
 237  *
 238  * @return
 239  *   Returns 0 on success
 240  */
 241 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev);
 242
 243 /**
 244  * Start a configured device.
 245  *
 246  * @param dev
 247  *   Event device pointer
 248  *
 249  * @return
 250  *   Returns 0 on success
 251  */
 252 typedef int (*eventdev_start_t)(struct rte_eventdev *dev);
 253
 254 /**
 255  * Stop a configured device.
 256  *
 257  * @param dev
 258  *   Event device pointer
 259  */
 260 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev);
 261
 262 /**
 263  * Close a configured device.
 264  *
 265  * @param dev
 266  *   Event device pointer
 267  *
 268  * @return
 269  * - 0 on success
 270  * - (-EAGAIN) if can't close as device is busy
 271  */
 272 typedef int (*eventdev_close_t)(struct rte_eventdev *dev);
 273
 274 /**
 275  * Retrieve the default event queue configuration.
 276  *
 277  * @param dev
 278  *   Event device pointer
 279  * @param queue_id
 280  *   Event queue index
 281  * @param[out] queue_conf
 282  *   Event queue configuration structure
 283  *
 284  */
 285 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev,
 286                 uint8_t queue_id, struct rte_event_queue_conf *queue_conf);
 287
 288 /**
 289  * Setup an event queue.
 290  *
 291  * @param dev
 292  *   Event device pointer
 293  * @param queue_id
 294  *   Event queue index
 295  * @param queue_conf
 296  *   Event queue configuration structure
 297  *
 298  * @return
 299  *   Returns 0 on success.
 300  */
 301 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev,
 302                 uint8_t queue_id,
 303                 const struct rte_event_queue_conf *queue_conf);
 304
 305 /**
 306  * Release resources allocated by given event queue.
 307  *
 308  * @param dev
 309  *   Event device pointer
 310  * @param queue_id
 311  *   Event queue index
 312  *
 313  */
 314 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev,
 315                 uint8_t queue_id);
 316
 317 /**
 318  * Retrieve the default event port configuration.
 319  *
 320  * @param dev
 321  *   Event device pointer
 322  * @param port_id
 323  *   Event port index
 324  * @param[out] port_conf
 325  *   Event port configuration structure
 326  *
 327  */
 328 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev,
 329                 uint8_t port_id, struct rte_event_port_conf *port_conf);
 330
 331 /**
 332  * Setup an event port.
 333  *
 334  * @param dev
 335  *   Event device pointer
 336  * @param port_id
 337  *   Event port index
 338  * @param port_conf
 339  *   Event port configuration structure
 340  *
 341  * @return
 342  *   Returns 0 on success.
 343  */
 344 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
 345                 uint8_t port_id,
 346                 const struct rte_event_port_conf *port_conf);
 347
 348 /**
 349  * Release memory resources allocated by given event port.
 350  *
 351  * @param port
 352  *   Event port pointer
 353  *
 354  */
 355 typedef void (*eventdev_port_release_t)(void *port);
 356
 357 /**
 358  * Link multiple source event queues to destination event port.
 359  *
 360  * @param port
 361  *   Event port pointer
 362  * @param link
 363  *   Points to an array of *nb_links* event queues to be linked
 364  *   to the event port.
 365  * @param priorities
 366  *   Points to an array of *nb_links* service priorities associated with each
 367  *   event queue link to event port.
 368  * @param nb_links
 369  *   The number of links to establish
 370  *
 371  * @return
 372  *   Returns 0 on success.
 373  *
 374  */
 375 typedef int (*eventdev_port_link_t)(void *port,
 376                 const uint8_t queues[], const uint8_t priorities[],
 377                 uint16_t nb_links);
 378
 379 /**
 380  * Unlink multiple source event queues from destination event port.
 381  *
 382  * @param port
 383  *   Event port pointer
 384  * @param queues
 385  *   An array of *nb_unlinks* event queues to be unlinked from the event port.
 386  * @param nb_unlinks
 387  *   The number of unlinks to establish
 388  *
 389  * @return
 390  *   Returns 0 on success.
 391  *
 392  */
 393 typedef int (*eventdev_port_unlink_t)(void *port,
 394                 uint8_t queues[], uint16_t nb_unlinks);
 395
 396 /**
 397  * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue()
 398  *
 399  * @param dev
 400  *   Event device pointer
 401  * @param ns
 402  *   Wait time in nanosecond
 403  * @param[out] timeout_ticks
 404  *   Value for the *timeout_ticks* parameter in rte_event_dequeue() function
 405  *
 406  */
 407 typedef void (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev,
 408                 uint64_t ns, uint64_t *timeout_ticks);
 409
 410 /**
 411  * Dump internal information
 412  *
 413  * @param dev
 414  *   Event device pointer
 415  * @param f
 416  *   A pointer to a file for output
 417  *
 418  */
 419 typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
 420
 421 /** Event device operations function pointer table */
 422 struct rte_eventdev_ops {
 423         eventdev_info_get_t dev_infos_get;      /**< Get device info. */
 424         eventdev_configure_t dev_configure;     /**< Configure device. */
 425         eventdev_start_t dev_start;             /**< Start device. */
 426         eventdev_stop_t dev_stop;               /**< Stop device. */
 427         eventdev_close_t dev_close;             /**< Close device. */
 428
 429         eventdev_queue_default_conf_get_t queue_def_conf;
 430         /**< Get default queue configuration. */
 431         eventdev_queue_setup_t queue_setup;
 432         /**< Set up an event queue. */
 433         eventdev_queue_release_t queue_release;
 434         /**< Release an event queue. */
 435
 436         eventdev_port_default_conf_get_t port_def_conf;
 437         /**< Get default port configuration. */
 438         eventdev_port_setup_t port_setup;
 439         /**< Set up an event port. */
 440         eventdev_port_release_t port_release;
 441         /**< Release an event port. */
 442
 443         eventdev_port_link_t port_link;
 444         /**< Link event queues to an event port. */
 445         eventdev_port_unlink_t port_unlink;
 446         /**< Unlink event queues from an event port. */
 447         eventdev_dequeue_timeout_ticks_t timeout_ticks;
 448         /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
 449         eventdev_dump_t dump;
 450         /* Dump internal information */
 451 };
 452
 453 /**
 454  * Allocates a new eventdev slot for an event device and returns the pointer
 455  * to that slot for the driver to use.
 456  *
 457  * @param name
 458  *   Unique identifier name for each device
 459  * @param socket_id
 460  *   Socket to allocate resources on.
 461  * @return
 462  *   - Slot in the rte_dev_devices array for a new device;
 463  */
 464 struct rte_eventdev *
 465 rte_event_pmd_allocate(const char *name, int socket_id);
 466
 467 /**
 468  * Release the specified eventdev device.
 469  *
 470  * @param eventdev
 471  * The *eventdev* pointer is the address of the *rte_eventdev* structure.
 472  * @return
 473  *   - 0 on success, negative on error
 474  */
 475 int
 476 rte_event_pmd_release(struct rte_eventdev *eventdev);
 477
 478 /**
 479  * Creates a new virtual event device and returns the pointer to that device.
 480  *
 481  * @param name
 482  *   PMD type name
 483  * @param dev_private_size
 484  *   Size of event PMDs private data
 485  * @param socket_id
 486  *   Socket to allocate resources on.
 487  *
 488  * @return
 489  *   - Eventdev pointer if device is successfully created.
 490  *   - NULL if device cannot be created.
 491  */
 492 struct rte_eventdev *
 493 rte_event_pmd_vdev_init(const char *name, size_t dev_private_size,
 494                 int socket_id);
 495
 496
 497 /**
 498  * Wrapper for use by pci drivers as a .probe function to attach to a event
 499  * interface.
 500  */
 501 int rte_event_pmd_pci_probe(struct rte_pci_driver *pci_drv,
 502                             struct rte_pci_device *pci_dev);
 503
 504 /**
 505  * Wrapper for use by pci drivers as a .remove function to detach a event
 506  * interface.
 507  */
 508 int rte_event_pmd_pci_remove(struct rte_pci_device *pci_dev);
 509
 510 #ifdef __cplusplus
 511 }
 512 #endif
 513
 514 #endif /* _RTE_EVENTDEV_PMD_H_ */