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