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 /** Global structure used for maintaining state of allocated event devices */
  96 struct rte_eventdev_global {
  97         uint8_t nb_devs;        /**< Number of devices found */
  98         uint8_t max_devs;       /**< Max number of devices */
  99 };
 100
 101 extern struct rte_eventdev_global *rte_eventdev_globals;
 102 /** Pointer to global event devices data structure. */
 103 extern struct rte_eventdev *rte_eventdevs;
 104 /** The pool of rte_eventdev structures. */
 105
 106 /**
 107  * Get the rte_eventdev structure device pointer for the named device.
 108  *
 109  * @param name
 110  *   device name to select the device structure.
 111  *
 112  * @return
 113  *   - The rte_eventdev structure pointer for the given device ID.
 114  */
 115 static inline struct rte_eventdev *
 116 rte_event_pmd_get_named_dev(const char *name)
 117 {
 118         struct rte_eventdev *dev;
 119         unsigned int i;
 120
 121         if (name == NULL)
 122                 return NULL;
 123
 124         for (i = 0, dev = &rte_eventdevs[i];
 125                         i < rte_eventdev_globals->max_devs; i++) {
 126                 if ((dev->attached == RTE_EVENTDEV_ATTACHED) &&
 127                                 (strcmp(dev->data->name, name) == 0))
 128                         return dev;
 129         }
 130
 131         return NULL;
 132 }
 133
 134 /**
 135  * Validate if the event device index is valid attached event device.
 136  *
 137  * @param dev_id
 138  *   Event device index.
 139  *
 140  * @return
 141  *   - If the device index is valid (1) or not (0).
 142  */
 143 static inline unsigned
 144 rte_event_pmd_is_valid_dev(uint8_t dev_id)
 145 {
 146         struct rte_eventdev *dev;
 147
 148         if (dev_id >= rte_eventdev_globals->nb_devs)
 149                 return 0;
 150
 151         dev = &rte_eventdevs[dev_id];
 152         if (dev->attached != RTE_EVENTDEV_ATTACHED)
 153                 return 0;
 154         else
 155                 return 1;
 156 }
 157
 158 /**
 159  * Definitions of all functions exported by a driver through the
 160  * the generic structure of type *event_dev_ops* supplied in the
 161  * *rte_eventdev* structure associated with a device.
 162  */
 163
 164 /**
 165  * Get device information of a device.
 166  *
 167  * @param dev
 168  *   Event device pointer
 169  * @param dev_info
 170  *   Event device information structure
 171  *
 172  * @return
 173  *   Returns 0 on success
 174  */
 175 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev,
 176                 struct rte_event_dev_info *dev_info);
 177
 178 /**
 179  * Configure a device.
 180  *
 181  * @param dev
 182  *   Event device pointer
 183  *
 184  * @return
 185  *   Returns 0 on success
 186  */
 187 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev);
 188
 189 /**
 190  * Start a configured device.
 191  *
 192  * @param dev
 193  *   Event device pointer
 194  *
 195  * @return
 196  *   Returns 0 on success
 197  */
 198 typedef int (*eventdev_start_t)(struct rte_eventdev *dev);
 199
 200 /**
 201  * Stop a configured device.
 202  *
 203  * @param dev
 204  *   Event device pointer
 205  */
 206 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev);
 207
 208 /**
 209  * Close a configured device.
 210  *
 211  * @param dev
 212  *   Event device pointer
 213  *
 214  * @return
 215  * - 0 on success
 216  * - (-EAGAIN) if can't close as device is busy
 217  */
 218 typedef int (*eventdev_close_t)(struct rte_eventdev *dev);
 219
 220 /**
 221  * Retrieve the default event queue configuration.
 222  *
 223  * @param dev
 224  *   Event device pointer
 225  * @param queue_id
 226  *   Event queue index
 227  * @param[out] queue_conf
 228  *   Event queue configuration structure
 229  *
 230  */
 231 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev,
 232                 uint8_t queue_id, struct rte_event_queue_conf *queue_conf);
 233
 234 /**
 235  * Setup an event queue.
 236  *
 237  * @param dev
 238  *   Event device pointer
 239  * @param queue_id
 240  *   Event queue index
 241  * @param queue_conf
 242  *   Event queue configuration structure
 243  *
 244  * @return
 245  *   Returns 0 on success.
 246  */
 247 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev,
 248                 uint8_t queue_id,
 249                 const struct rte_event_queue_conf *queue_conf);
 250
 251 /**
 252  * Release resources allocated by given event queue.
 253  *
 254  * @param dev
 255  *   Event device pointer
 256  * @param queue_id
 257  *   Event queue index
 258  *
 259  */
 260 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev,
 261                 uint8_t queue_id);
 262
 263 /**
 264  * Retrieve the default event port configuration.
 265  *
 266  * @param dev
 267  *   Event device pointer
 268  * @param port_id
 269  *   Event port index
 270  * @param[out] port_conf
 271  *   Event port configuration structure
 272  *
 273  */
 274 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev,
 275                 uint8_t port_id, struct rte_event_port_conf *port_conf);
 276
 277 /**
 278  * Setup an event port.
 279  *
 280  * @param dev
 281  *   Event device pointer
 282  * @param port_id
 283  *   Event port index
 284  * @param port_conf
 285  *   Event port configuration structure
 286  *
 287  * @return
 288  *   Returns 0 on success.
 289  */
 290 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
 291                 uint8_t port_id,
 292                 const struct rte_event_port_conf *port_conf);
 293
 294 /**
 295  * Release memory resources allocated by given event port.
 296  *
 297  * @param port
 298  *   Event port pointer
 299  *
 300  */
 301 typedef void (*eventdev_port_release_t)(void *port);
 302
 303 /**
 304  * Link multiple source event queues to destination event port.
 305  *
 306  * @param port
 307  *   Event port pointer
 308  * @param link
 309  *   Points to an array of *nb_links* event queues to be linked
 310  *   to the event port.
 311  * @param priorities
 312  *   Points to an array of *nb_links* service priorities associated with each
 313  *   event queue link to event port.
 314  * @param nb_links
 315  *   The number of links to establish
 316  *
 317  * @return
 318  *   Returns 0 on success.
 319  *
 320  */
 321 typedef int (*eventdev_port_link_t)(void *port,
 322                 const uint8_t queues[], const uint8_t priorities[],
 323                 uint16_t nb_links);
 324
 325 /**
 326  * Unlink multiple source event queues from destination event port.
 327  *
 328  * @param port
 329  *   Event port pointer
 330  * @param queues
 331  *   An array of *nb_unlinks* event queues to be unlinked from the event port.
 332  * @param nb_unlinks
 333  *   The number of unlinks to establish
 334  *
 335  * @return
 336  *   Returns 0 on success.
 337  *
 338  */
 339 typedef int (*eventdev_port_unlink_t)(void *port,
 340                 uint8_t queues[], uint16_t nb_unlinks);
 341
 342 /**
 343  * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue()
 344  *
 345  * @param dev
 346  *   Event device pointer
 347  * @param ns
 348  *   Wait time in nanosecond
 349  * @param[out] timeout_ticks
 350  *   Value for the *timeout_ticks* parameter in rte_event_dequeue() function
 351  *
 352  */
 353 typedef void (*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 /** Event device operations function pointer table */
 368 struct rte_eventdev_ops {
 369         eventdev_info_get_t dev_infos_get;      /**< Get device info. */
 370         eventdev_configure_t dev_configure;     /**< Configure device. */
 371         eventdev_start_t dev_start;             /**< Start device. */
 372         eventdev_stop_t dev_stop;               /**< Stop device. */
 373         eventdev_close_t dev_close;             /**< Close device. */
 374
 375         eventdev_queue_default_conf_get_t queue_def_conf;
 376         /**< Get default queue configuration. */
 377         eventdev_queue_setup_t queue_setup;
 378         /**< Set up an event queue. */
 379         eventdev_queue_release_t queue_release;
 380         /**< Release an event queue. */
 381
 382         eventdev_port_default_conf_get_t port_def_conf;
 383         /**< Get default port configuration. */
 384         eventdev_port_setup_t port_setup;
 385         /**< Set up an event port. */
 386         eventdev_port_release_t port_release;
 387         /**< Release an event port. */
 388
 389         eventdev_port_link_t port_link;
 390         /**< Link event queues to an event port. */
 391         eventdev_port_unlink_t port_unlink;
 392         /**< Unlink event queues from an event port. */
 393         eventdev_dequeue_timeout_ticks_t timeout_ticks;
 394         /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
 395         eventdev_dump_t dump;
 396         /* Dump internal information */
 397 };
 398
 399 #ifdef __cplusplus
 400 }
 401 #endif
 402
 403 #endif /* _RTE_EVENTDEV_PMD_H_ */