lib/librte_eventdev/rte_event_timer_adapter.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Cavium, Inc.
   3  * Copyright(c) 2017-2018 Intel Corporation.
   4  * All rights reserved.
   5  */
   6
   7 #ifndef __RTE_EVENT_TIMER_ADAPTER_H__
   8 #define __RTE_EVENT_TIMER_ADAPTER_H__
   9
  10 /**
  11  * @file
  12  *
  13  * RTE Event Timer Adapter
  14  *
  15  * An event timer adapter has the following abstract working model:
  16  *
  17  *                               timer_tick_ns
  18  *                                   +
  19  *                      +-------+    |
  20  *                      |       |    |
  21  *              +-------+ bkt 0 +----v---+
  22  *              |       |       |        |
  23  *              |       +-------+        |
  24  *          +---+---+                +---+---+  +---+---+---+---+
  25  *          |       |                |       |  |   |   |   |   |
  26  *          | bkt n |                | bkt 1 |<-> t0| t1| t2| tn|
  27  *          |       |                |       |  |   |   |   |   |
  28  *          +---+---+                +---+---+  +---+---+---+---+
  29  *              |     Timer adapter      |
  30  *          +---+---+                +---+---+
  31  *          |       |                |       |
  32  *          | bkt 4 |                | bkt 2 |<--- Current bucket
  33  *          |       |                |       |
  34  *          +---+---+                +---+---+
  35  *               |      +-------+       |
  36  *               |      |       |       |
  37  *               +------+ bkt 3 +-------+
  38  *                      |       |
  39  *                      +-------+
  40  *
  41  * - It has a virtual monotonically increasing 64-bit timer adapter clock based
  42  *   on *enum rte_event_timer_adapter_clk_src* clock source. The clock source
  43  *   could be a CPU clock, or a platform dependent external clock.
  44  *
  45  * - The application creates a timer adapter instance with given the clock
  46  *   source, the total number of event timers, and a resolution(expressed in ns)
  47  *   to traverse between the buckets.
  48  *
  49  * - Each timer adapter may have 0 to n buckets based on the configured
  50  *   max timeout(max_tmo_ns) and resolution(timer_tick_ns). Upon starting the
  51  *   timer adapter, the adapter starts ticking at *timer_tick_ns* resolution.
  52  *
  53  * - The application arms an event timer that will expire *timer_tick_ns*
  54  *   from now.
  55  *
  56  * - The application can cancel an armed timer and no timer expiry event will be
  57  *   generated.
  58  *
  59  * - If a timer expires then the library injects the timer expiry event in
  60  *   the designated event queue.
  61  *
  62  * - The timer expiry event will be received through *rte_event_dequeue_burst*.
  63  *
  64  * - The application frees the timer adapter instance.
  65  *
  66  * Multiple timer adapters can be created with a varying level of resolution
  67  * for various expiry use cases that run in parallel.
  68  *
  69  * Before using the timer adapter, the application has to create and configure
  70  * an event device along with the event port. Based on the event device
  71  * capability it might require creating an additional event port to be used
  72  * by the timer adapter.
  73  *
  74  * The application creates the event timer adapter using the
  75  * ``rte_event_timer_adapter_create()``. The event device id is passed to this
  76  * function, inside this function the event device capability is checked,
  77  * and if an in-built port is absent the application uses the default
  78  * function to create a new producer port.
  79  *
  80  * The application may also use the function
  81  * ``rte_event_timer_adapter_create_ext()`` to have granular control over
  82  * producer port creation in a case where the in-built port is absent.
  83  *
  84  * After creating the timer adapter, the application has to start it
  85  * using ``rte_event_timer_adapter_start()``. The buckets are traversed from
  86  * 0 to n; when the adapter ticks, the next bucket is visited. Each time,
  87  * the list per bucket is processed, and timer expiry events are sent to the
  88  * designated event queue.
  89  *
  90  * The application can arm one or more event timers using the
  91  * ``rte_event_timer_arm_burst()``. The *timeout_ticks* represents the number
  92  * of *timer_tick_ns* after which the timer has to expire. The timeout at
  93  * which the timers expire can be grouped or be independent of each
  94  * event timer instance. ``rte_event_timer_arm_tmo_tick_burst()`` addresses the
  95  * former case and ``rte_event_timer_arm_burst()`` addresses the latter case.
  96  *
  97  * The application can cancel the timers from expiring using the
  98  * ``rte_event_timer_cancel_burst()``.
  99  *
 100  * On the secondary process, ``rte_event_timer_adapter_lookup()`` can be used
 101  * to get the timer adapter pointer from its id and use it to invoke fastpath
 102  * operations such as arm and cancel.
 103  *
 104  * Some of the use cases of event timer adapter are Beacon Timers,
 105  * Generic SW Timeout, Wireless MAC Scheduling, 3G Frame Protocols,
 106  * Packet Scheduling, Protocol Retransmission Timers, Supervision Timers.
 107  * All these use cases require high resolution and low time drift.
 108  */
 109
 110 #ifdef __cplusplus
 111 extern "C" {
 112 #endif
 113
 114 #include <rte_spinlock.h>
 115 #include <rte_memory.h>
 116
 117 #include "rte_eventdev.h"
 118
 119 /**
 120  * @warning
 121  * @b EXPERIMENTAL: this enum may change without prior notice
 122  *
 123  * Timer adapter clock source
 124  */
 125 enum rte_event_timer_adapter_clk_src {
 126         RTE_EVENT_TIMER_ADAPTER_CPU_CLK,
 127         /**< Use CPU clock as the clock source. */
 128         RTE_EVENT_TIMER_ADAPTER_EXT_CLK0,
 129         /**< Platform dependent external clock source 0. */
 130         RTE_EVENT_TIMER_ADAPTER_EXT_CLK1,
 131         /**< Platform dependent external clock source 1. */
 132         RTE_EVENT_TIMER_ADAPTER_EXT_CLK2,
 133         /**< Platform dependent external clock source 2. */
 134         RTE_EVENT_TIMER_ADAPTER_EXT_CLK3,
 135         /**< Platform dependent external clock source 3. */
 136 };
 137
 138 #define RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES    (1ULL << 0)
 139 /**< The event timer adapter implementation may have constraints on the
 140  * resolution (timer_tick_ns) and maximum timer expiry timeout(max_tmo_ns)
 141  * based on the given timer adapter or system. If this flag is set, the
 142  * implementation adjusts the resolution and maximum timeout to the best
 143  * possible configuration. On successful timer adapter creation, the
 144  * application can get the configured resolution and max timeout with
 145  * ``rte_event_timer_adapter_get_info()``.
 146  *
 147  * @see struct rte_event_timer_adapter_info::min_resolution_ns
 148  * @see struct rte_event_timer_adapter_info::max_tmo_ns
 149  */
 150 #define RTE_EVENT_TIMER_ADAPTER_F_SP_PUT        (1ULL << 1)
 151 /**< ``rte_event_timer_arm_burst()`` API to be used in single producer mode.
 152  *
 153  * @see struct rte_event_timer_adapter_conf::flags
 154  */
 155
 156 /**
 157  * @warning
 158  * @b EXPERIMENTAL: this structure may change without prior notice
 159  *
 160  * Timer adapter configuration structure
 161  */
 162 struct rte_event_timer_adapter_conf {
 163         uint8_t event_dev_id;
 164         /**< Event device identifier */
 165         uint16_t timer_adapter_id;
 166         /**< Event timer adapter identifier */
 167         uint32_t socket_id;
 168         /**< Identifier of socket from which to allocate memory for adapter */
 169         enum rte_event_timer_adapter_clk_src clk_src;
 170         /**< Clock source for timer adapter */
 171         uint64_t timer_tick_ns;
 172         /**< Timer adapter resolution in ns */
 173         uint64_t max_tmo_ns;
 174         /**< Maximum timer timeout(expiry) in ns */
 175         uint64_t nb_timers;
 176         /**< Total number of timers per adapter */
 177         uint64_t flags;
 178         /**< Timer adapter config flags (RTE_EVENT_TIMER_ADAPTER_F_*) */
 179 };
 180
 181 /**
 182  * @warning
 183  * @b EXPERIMENTAL: this structure may change without prior notice
 184  *
 185  * Event timer adapter stats structure
 186  */
 187 struct rte_event_timer_adapter_stats {
 188         uint64_t evtim_exp_count;
 189         /**< Number of event timers that have expired. */
 190         uint64_t ev_enq_count;
 191         /**< Eventdev enqueue count */
 192         uint64_t ev_inv_count;
 193         /**< Invalid expiry event count */
 194         uint64_t evtim_retry_count;
 195         /**< Event timer retry count */
 196         uint64_t adapter_tick_count;
 197         /**< Tick count for the adapter, at its resolution */
 198 };
 199
 200 struct rte_event_timer_adapter;
 201
 202 /**
 203  * @warning
 204  * @b EXPERIMENTAL: this API may change without prior notice
 205  *
 206  * Callback function type for producer port creation.
 207  */
 208 typedef int (*rte_event_timer_adapter_port_conf_cb_t)(uint16_t id,
 209                                                       uint8_t event_dev_id,
 210                                                       uint8_t *event_port_id,
 211                                                       void *conf_arg);
 212
 213 /**
 214  * @warning
 215  * @b EXPERIMENTAL: this API may change without prior notice
 216  *
 217  * Create an event timer adapter.
 218  *
 219  * This function must be invoked first before any other function in the API.
 220  *
 221  * @param conf
 222  *   The event timer adapter configuration structure.
 223  *
 224  * @return
 225  *   A pointer to the new allocated event timer adapter on success.
 226  *   NULL on error with rte_errno set appropriately.
 227  *   Possible rte_errno values include:
 228  *   - ERANGE: timer_tick_ns is not in supported range.
 229  *   - ENOMEM: unable to allocate sufficient memory for adapter instances
 230  *   - EINVAL: invalid event device identifier specified in config
 231  *   - ENOSPC: maximum number of adapters already created
 232  *   - EIO: event device reconfiguration and restart error.  The adapter
 233  *   reconfigures the event device with an additional port by default if it is
 234  *   required to use a service to manage timers. If the device had been started
 235  *   before this call, this error code indicates an error in restart following
 236  *   an error in reconfiguration, i.e., a combination of the two error codes.
 237  */
 238 struct rte_event_timer_adapter * __rte_experimental
 239 rte_event_timer_adapter_create(const struct rte_event_timer_adapter_conf *conf);
 240
 241 /**
 242  * @warning
 243  * @b EXPERIMENTAL: this API may change without prior notice
 244  *
 245  * Create a timer adapter with the supplied callback.
 246  *
 247  * This function can be used to have a more granular control over the timer
 248  * adapter creation.  If a built-in port is absent, then the function uses the
 249  * callback provided to create and get the port id to be used as a producer
 250  * port.
 251  *
 252  * @param conf
 253  *   The timer adapter configuration structure
 254  * @param conf_cb
 255  *   The port config callback function.
 256  * @param conf_arg
 257  *   Opaque pointer to the argument for the callback function
 258  *
 259  * @return
 260  *   A pointer to the new allocated event timer adapter on success.
 261  *   NULL on error with rte_errno set appropriately.
 262  *   Possible rte_errno values include:
 263  *   - ERANGE: timer_tick_ns is not in supported range.
 264  *   - ENOMEM: unable to allocate sufficient memory for adapter instances
 265  *   - EINVAL: invalid event device identifier specified in config
 266  *   - ENOSPC: maximum number of adapters already created
 267  */
 268 struct rte_event_timer_adapter * __rte_experimental
 269 rte_event_timer_adapter_create_ext(
 270                 const struct rte_event_timer_adapter_conf *conf,
 271                 rte_event_timer_adapter_port_conf_cb_t conf_cb,
 272                 void *conf_arg);
 273
 274 /**
 275  * @warning
 276  * @b EXPERIMENTAL: this structure may change without prior notice
 277  *
 278  * Timer adapter info structure.
 279  */
 280 struct rte_event_timer_adapter_info {
 281         uint64_t min_resolution_ns;
 282         /**< Minimum timer adapter resolution in ns */
 283         uint64_t max_tmo_ns;
 284         /**< Maximum timer timeout(expire) in ns */
 285         struct rte_event_timer_adapter_conf conf;
 286         /**< Configured timer adapter attributes */
 287         uint32_t caps;
 288         /**< Event timer adapter capabilities */
 289         int16_t event_dev_port_id;
 290         /**< Event device port ID, if applicable */
 291 };
 292
 293 /**
 294  * @warning
 295  * @b EXPERIMENTAL: this API may change without prior notice
 296  *
 297  * Retrieve the contextual information of an event timer adapter.
 298  *
 299  * @param adapter
 300  *   A pointer to the event timer adapter structure.
 301  *
 302  * @param[out] adapter_info
 303  *   A pointer to a structure of type *rte_event_timer_adapter_info* to be
 304  *   filled with the contextual information of the adapter.
 305  *
 306  * @return
 307  *   - 0: Success, driver updates the contextual information of the
 308  *   timer adapter
 309  *   - <0: Error code returned by the driver info get function.
 310  *   - -EINVAL: adapter identifier invalid
 311  *
 312  * @see RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES,
 313  *   struct rte_event_timer_adapter_info
 314  *
 315  */
 316 int __rte_experimental
 317 rte_event_timer_adapter_get_info(
 318                 const struct rte_event_timer_adapter *adapter,
 319                 struct rte_event_timer_adapter_info *adapter_info);
 320
 321 /**
 322  * @warning
 323  * @b EXPERIMENTAL: this API may change without prior notice
 324  *
 325  * Start a timer adapter.
 326  *
 327  * The adapter start step is the last one and consists of setting the timer
 328  * adapter to start accepting the timers and schedules to event queues.
 329  *
 330  * On success, all basic functions exported by the API (timer arm,
 331  * timer cancel and so on) can be invoked.
 332  *
 333  * @param adapter
 334  *   A pointer to the event timer adapter structure.
 335  *
 336  * @return
 337  *   - 0: Success, adapter started.
 338  *   - <0: Error code returned by the driver start function.
 339  *   - -EINVAL if adapter identifier invalid
 340  *   - -ENOENT if software adapter but no service core mapped
 341  *   - -ENOTSUP if software adapter and more than one service core mapped
 342  */
 343 int __rte_experimental
 344 rte_event_timer_adapter_start(
 345                 const struct rte_event_timer_adapter *adapter);
 346
 347 /**
 348  * @warning
 349  * @b EXPERIMENTAL: this API may change without prior notice
 350  *
 351  * Stop an event timer adapter.
 352  *
 353  * The adapter can be restarted with a call to
 354  * ``rte_event_timer_adapter_start()``.
 355  *
 356  * @param adapter
 357  *   A pointer to the event timer adapter structure.
 358  *
 359  * @return
 360  *   - 0: Success, adapter stopped.
 361  *   - <0: Error code returned by the driver stop function.
 362  *   - -EINVAL if adapter identifier invalid
 363  */
 364 int __rte_experimental
 365 rte_event_timer_adapter_stop(const struct rte_event_timer_adapter *adapter);
 366
 367 /**
 368  * @warning
 369  * @b EXPERIMENTAL: this API may change without prior notice
 370  *
 371  * Lookup an event timer adapter using its identifier.
 372  *
 373  * If an event timer adapter was created in another process with the same
 374  * identifier, this function will locate its state and set up access to it
 375  * so that it can be used in this process.
 376  *
 377  * @param adapter_id
 378  *  The event timer adapter identifier.
 379  *
 380  * @return
 381  *  A pointer to the event timer adapter matching the identifier on success.
 382  *  NULL on error with rte_errno set appropriately.
 383  *  Possible rte_errno values include:
 384  *   - ENOENT - requested entry not available to return.
 385  */
 386 struct rte_event_timer_adapter * __rte_experimental
 387 rte_event_timer_adapter_lookup(uint16_t adapter_id);
 388
 389 /**
 390  * @warning
 391  * @b EXPERIMENTAL: this API may change without prior notice
 392  *
 393  * Free an event timer adapter.
 394  *
 395  * Destroy an event timer adapter, freeing all resources.
 396  *
 397  * Before invoking this function, the application must wait for all the
 398  * armed timers to expire or cancel the outstanding armed timers.
 399  *
 400  * @param adapter
 401  *   A pointer to an event timer adapter structure.
 402  *
 403  * @return
 404  *   - 0: Successfully freed the event timer adapter resources.
 405  *   - <0: Failed to free the event timer adapter resources.
 406  *   - -EAGAIN:  adapter is busy; timers outstanding
 407  *   - -EBUSY: stop hasn't been called for this adapter yet
 408  *   - -EINVAL: adapter id invalid, or adapter invalid
 409  */
 410 int __rte_experimental
 411 rte_event_timer_adapter_free(struct rte_event_timer_adapter *adapter);
 412
 413 /**
 414  * Retrieve the service ID of the event timer adapter. If the adapter doesn't
 415  * use an rte_service function, this function returns -ESRCH.
 416  *
 417  * @param adapter
 418  *   A pointer to an event timer adapter.
 419  *
 420  * @param [out] service_id
 421  *   A pointer to a uint32_t, to be filled in with the service id.
 422  *
 423  * @return
 424  *   - 0: Success
 425  *   - <0: Error code on failure
 426  *   - -ESRCH: the adapter does not require a service to operate
 427  */
 428 int __rte_experimental
 429 rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter,
 430                                        uint32_t *service_id);
 431
 432 /**
 433  * @warning
 434  * @b EXPERIMENTAL: this API may change without prior notice
 435  *
 436  * Retrieve statistics for an event timer adapter instance.
 437  *
 438  * @param adapter
 439  *   A pointer to an event timer adapter structure.
 440  * @param[out] stats
 441  *   A pointer to a structure to fill with statistics.
 442  *
 443  * @return
 444  *   - 0: Successfully retrieved.
 445  *   - <0: Failure; error code returned.
 446  */
 447 int __rte_experimental
 448 rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter,
 449                 struct rte_event_timer_adapter_stats *stats);
 450
 451 /**
 452  * @warning
 453  * @b EXPERIMENTAL: this API may change without prior notice
 454  *
 455  * Reset statistics for an event timer adapter instance.
 456  *
 457  * @param adapter
 458  *   A pointer to an event timer adapter structure.
 459  *
 460  * @return
 461  *   - 0: Successfully reset;
 462  *   - <0: Failure; error code returned.
 463  */
 464 int __rte_experimental rte_event_timer_adapter_stats_reset(
 465                 struct rte_event_timer_adapter *adapter);
 466
 467 /**
 468  * Retrieve the service ID of the event timer adapter. If the adapter doesn't
 469  * use an rte_service function, this function returns -ESRCH.
 470  *
 471  * @param adapter
 472  *   A pointer to an event timer adapter.
 473  *
 474  * @param [out] service_id
 475  *   A pointer to a uint32_t, to be filled in with the service id.
 476  *
 477  * @return
 478  *   - 0: Success
 479  *   - <0: Error code on failure, if the event dev doesn't use a rte_service
 480  *   function, this function returns -ESRCH.
 481  */
 482 int
 483 rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter,
 484                                        uint32_t *service_id);
 485
 486 /**
 487  * @warning
 488  * @b EXPERIMENTAL: this API may change without prior notice
 489  *
 490  * Retrieve statistics for an event timer adapter instance.
 491  *
 492  * @param adapter
 493  *   A pointer to an event timer adapter structure.
 494  * @param[out] stats
 495  *   A pointer to a structure to fill with statistics.
 496  *
 497  * @return
 498  *   - 0: Successfully retrieved.
 499  *   - <0: Failure; error code returned.
 500  */
 501 int rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter,
 502                                 struct rte_event_timer_adapter_stats *stats);
 503
 504 /**
 505  * @warning
 506  * @b EXPERIMENTAL: this API may change without prior notice
 507  *
 508  * Reset statistics for an event timer adapter instance.
 509  *
 510  * @param adapter
 511  *   A pointer to an event timer adapter structure.
 512  *
 513  * @return
 514  *   - 0: Successfully reset;
 515  *   - <0: Failure; error code returned.
 516  */
 517 int rte_event_timer_adapter_stats_reset(
 518                                 struct rte_event_timer_adapter *adapter);
 519
 520 /**
 521  * @warning
 522  * @b EXPERIMENTAL: this structure may change without prior notice
 523  *
 524  * Event timer state.
 525  */
 526 enum rte_event_timer_state {
 527         RTE_EVENT_TIMER_NOT_ARMED       = 0,
 528         /**< Event timer not armed. */
 529         RTE_EVENT_TIMER_ARMED           = 1,
 530         /**< Event timer successfully armed. */
 531         RTE_EVENT_TIMER_CANCELED        = 2,
 532         /**< Event timer successfully canceled. */
 533         RTE_EVENT_TIMER_ERROR           = -1,
 534         /**< Generic event timer error. */
 535         RTE_EVENT_TIMER_ERROR_TOOEARLY  = -2,
 536         /**< Event timer timeout tick value is too small for the adapter to
 537          * handle, given its configured resolution.
 538          */
 539         RTE_EVENT_TIMER_ERROR_TOOLATE   = -3,
 540         /**< Event timer timeout tick is greater than the maximum timeout.*/
 541 };
 542
 543 /**
 544  * @warning
 545  * @b EXPERIMENTAL: this structure may change without prior notice
 546  *
 547  * The generic *rte_event_timer* structure to hold the event timer attributes
 548  * for arm and cancel operations.
 549  */
 550 RTE_STD_C11
 551 struct rte_event_timer {
 552         struct rte_event ev;
 553         /**<
 554          * Expiry event attributes.  On successful event timer timeout,
 555          * the following attributes will be used to inject the expiry event to
 556          * the eventdev:
 557          *  - event_queue_id: Targeted event queue id for expiry events.
 558          *  - event_priority: Event priority of the event expiry event in the
 559          *  event queue relative to other events.
 560          *  - sched_type: Scheduling type of the expiry event.
 561          *  - flow_id: Flow id of the expiry event.
 562          *  - op: RTE_EVENT_OP_NEW
 563          *  - event_type: RTE_EVENT_TYPE_TIMER
 564          */
 565         volatile enum rte_event_timer_state state;
 566         /**< State of the event timer. */
 567         uint64_t timeout_ticks;
 568         /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from
 569          * now.
 570          * @see struct rte_event_timer_adapter_info::adapter_conf::timer_tick_ns
 571          */
 572         uint64_t impl_opaque[2];
 573         /**< Implementation-specific opaque data.
 574          * An event timer adapter implementation use this field to hold
 575          * implementation specific values to share between the arm and cancel
 576          * operations.  The application should not modify this field.
 577          */
 578         uint8_t user_meta[0];
 579         /**< Memory to store user specific metadata.
 580          * The event timer adapter implementation should not modify this area.
 581          */
 582 } __rte_cache_aligned;
 583
 584 typedef uint16_t (*rte_event_timer_arm_burst_t)(
 585                 const struct rte_event_timer_adapter *adapter,
 586                 struct rte_event_timer **tims,
 587                 uint16_t nb_tims);
 588 /**< @internal Enable event timers to enqueue timer events upon expiry */
 589 typedef uint16_t (*rte_event_timer_arm_tmo_tick_burst_t)(
 590                 const struct rte_event_timer_adapter *adapter,
 591                 struct rte_event_timer **tims,
 592                 uint64_t timeout_tick,
 593                 uint16_t nb_tims);
 594 /**< @internal Enable event timers with common expiration time */
 595 typedef uint16_t (*rte_event_timer_cancel_burst_t)(
 596                 const struct rte_event_timer_adapter *adapter,
 597                 struct rte_event_timer **tims,
 598                 uint16_t nb_tims);
 599 /**< @internal Prevent event timers from enqueuing timer events */
 600
 601 /**
 602  * @internal Data structure associated with each event timer adapter.
 603  */
 604 struct rte_event_timer_adapter {
 605         rte_event_timer_arm_burst_t arm_burst;
 606         /**< Pointer to driver arm_burst function. */
 607         rte_event_timer_arm_tmo_tick_burst_t arm_tmo_tick_burst;
 608         /**< Pointer to driver arm_tmo_tick_burst function. */
 609         rte_event_timer_cancel_burst_t cancel_burst;
 610         /**< Pointer to driver cancel function. */
 611         struct rte_event_timer_adapter_data *data;
 612         /**< Pointer to shared adapter data */
 613         const struct rte_event_timer_adapter_ops *ops;
 614         /**< Functions exported by adapter driver */
 615
 616         RTE_STD_C11
 617         uint8_t allocated : 1;
 618         /**< Flag to indicate that this adapter has been allocated */
 619 } __rte_cache_aligned;
 620
 621 #define ADAPTER_VALID_OR_ERR_RET(adapter, retval) do {          \
 622         if (adapter == NULL || !adapter->allocated)             \
 623                 return retval;                                  \
 624 } while (0)
 625
 626 #define FUNC_PTR_OR_ERR_RET(func, errval) do {                  \
 627         if ((func) == NULL)                                     \
 628                 return errval;                                  \
 629 } while (0)
 630
 631 #define FUNC_PTR_OR_NULL_RET_WITH_ERRNO(func, errval) do {      \
 632         if ((func) == NULL) {                                   \
 633                 rte_errno = errval;                             \
 634                 return NULL;                                    \
 635         }                                                       \
 636 } while (0)
 637
 638 /**
 639  * @warning
 640  * @b EXPERIMENTAL: this API may change without prior notice
 641  *
 642  * Arm a burst of event timers with separate expiration timeout tick for each
 643  * event timer.
 644  *
 645  * Before calling this function, the application allocates
 646  * ``struct rte_event_timer`` objects from mempool or huge page backed
 647  * application buffers of desired size. On successful allocation,
 648  * application updates the `struct rte_event_timer`` attributes such as
 649  * expiry event attributes, timeout ticks from now.
 650  * This function submits the event timer arm requests to the event timer adapter
 651  * and on expiry, the events will be injected to designated event queue.
 652  *
 653  * @param adapter
 654  *   A pointer to an event timer adapter structure.
 655  * @param evtims
 656  *   Pointer to an array of objects of type *rte_event_timer* structure.
 657  * @param nb_evtims
 658  *   Number of event timers in the supplied array.
 659  *
 660  * @return
 661  *   The number of successfully armed event timers. The return value can be less
 662  *   than the value of the *nb_evtims* parameter. If the return value is less
 663  *   than *nb_evtims*, the remaining event timers at the end of *evtims*
 664  *   are not consumed, and the caller has to take care of them, and rte_errno
 665  *   is set accordingly. Possible errno values include:
 666  *   - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
 667  *   expiry event's sched type doesn't match the capabilities of the
 668  *   destination event queue.
 669  *   - EAGAIN Specified timer adapter is not running
 670  *   - EALREADY A timer was encountered that was already armed
 671  */
 672 static inline uint16_t __rte_experimental
 673 rte_event_timer_arm_burst(const struct rte_event_timer_adapter *adapter,
 674                           struct rte_event_timer **evtims,
 675                           uint16_t nb_evtims)
 676 {
 677 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
 678         ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
 679         FUNC_PTR_OR_ERR_RET(adapter->arm_burst, -EINVAL);
 680 #endif
 681         return adapter->arm_burst(adapter, evtims, nb_evtims);
 682 }
 683
 684 /**
 685  * @warning
 686  * @b EXPERIMENTAL: this API may change without prior notice
 687  *
 688  * Arm a burst of event timers with same expiration timeout tick.
 689  *
 690  * Provides the same functionality as ``rte_event_timer_arm_burst()``, except
 691  * that application can use this API when all the event timers have the
 692  * same timeout expiration tick. This specialized function can provide the
 693  * additional hint to the adapter implementation and optimize if possible.
 694  *
 695  * @param adapter
 696  *   A pointer to an event timer adapter structure.
 697  * @param evtims
 698  *   Points to an array of objects of type *rte_event_timer* structure.
 699  * @param timeout_ticks
 700  *   The number of ticks in which the timers should expire.
 701  * @param nb_evtims
 702  *   Number of event timers in the supplied array.
 703  *
 704  * @return
 705  *   The number of successfully armed event timers. The return value can be less
 706  *   than the value of the *nb_evtims* parameter. If the return value is less
 707  *   than *nb_evtims*, the remaining event timers at the end of *evtims*
 708  *   are not consumed, and the caller has to take care of them, and rte_errno
 709  *   is set accordingly. Possible errno values include:
 710  *   - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
 711  *   expiry event's sched type doesn't match the capabilities of the
 712  *   destination event queue.
 713  *   - EAGAIN Specified event timer adapter is not running
 714  *   - EALREADY A timer was encountered that was already armed
 715  */
 716 static inline uint16_t __rte_experimental
 717 rte_event_timer_arm_tmo_tick_burst(
 718                         const struct rte_event_timer_adapter *adapter,
 719                         struct rte_event_timer **evtims,
 720                         const uint64_t timeout_ticks,
 721                         const uint16_t nb_evtims)
 722 {
 723 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
 724         ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
 725         FUNC_PTR_OR_ERR_RET(adapter->arm_tmo_tick_burst, -EINVAL);
 726 #endif
 727         return adapter->arm_tmo_tick_burst(adapter, evtims, timeout_ticks,
 728                                            nb_evtims);
 729 }
 730
 731 /**
 732  * @warning
 733  * @b EXPERIMENTAL: this API may change without prior notice
 734  *
 735  * Cancel a burst of event timers from being scheduled to the event device.
 736  *
 737  * @param adapter
 738  *   A pointer to an event timer adapter structure.
 739  * @param evtims
 740  *   Points to an array of objects of type *rte_event_timer* structure
 741  * @param nb_evtims
 742  *   Number of event timer instances in the supplied array.
 743  *
 744  * @return
 745  *   The number of successfully canceled event timers. The return value can be
 746  *   less than the value of the *nb_evtims* parameter. If the return value is
 747  *   less than *nb_evtims*, the remaining event timers at the end of *evtims*
 748  *   are not consumed, and the caller has to take care of them, and rte_errno
 749  *   is set accordingly. Possible errno values include:
 750  *   - EINVAL Invalid timer adapter identifier
 751  *   - EAGAIN Specified timer adapter is not running
 752  *   - EALREADY  A timer was encountered that was already canceled
 753  */
 754 static inline uint16_t __rte_experimental
 755 rte_event_timer_cancel_burst(const struct rte_event_timer_adapter *adapter,
 756                              struct rte_event_timer **evtims,
 757                              uint16_t nb_evtims)
 758 {
 759 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
 760         ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
 761         FUNC_PTR_OR_ERR_RET(adapter->cancel_burst, -EINVAL);
 762 #endif
 763         return adapter->cancel_burst(adapter, evtims, nb_evtims);
 764 }
 765
 766 #endif /* __RTE_EVENT_TIMER_ADAPTER_H__ */