1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Cavium, Inc.
3 * Copyright(c) 2017-2018 Intel Corporation.
7 #ifndef __RTE_EVENT_TIMER_ADAPTER_H__
8 #define __RTE_EVENT_TIMER_ADAPTER_H__
13 * RTE Event Timer Adapter
15 * An event timer adapter has the following abstract working model:
21 * +-------+ bkt 0 +----v---+
24 * +---+---+ +---+---+ +---+---+---+---+
26 * | bkt n | | bkt 1 |<-> t0| t1| t2| tn|
28 * +---+---+ +---+---+ +---+---+---+---+
32 * | bkt 4 | | bkt 2 |<--- Current bucket
37 * +------+ bkt 3 +-------+
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.
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.
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.
53 * - The application arms an event timer that will expire *timer_tick_ns*
56 * - The application can cancel an armed timer and no timer expiry event will be
59 * - If a timer expires then the library injects the timer expiry event in
60 * the designated event queue.
62 * - The timer expiry event will be received through *rte_event_dequeue_burst*.
64 * - The application frees the timer adapter instance.
66 * Multiple timer adapters can be created with a varying level of resolution
67 * for various expiry use cases that run in parallel.
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.
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.
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.
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.
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.
97 * The application can cancel the timers from expiring using the
98 * ``rte_event_timer_cancel_burst()``.
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.
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.
114 #include <rte_spinlock.h>
115 #include <rte_memory.h>
117 #include "rte_eventdev.h"
121 * @b EXPERIMENTAL: this enum may change without prior notice
123 * Timer adapter clock source
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. */
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()``.
147 * @see struct rte_event_timer_adapter_info::min_resolution_ns
148 * @see struct rte_event_timer_adapter_info::max_tmo_ns
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.
153 * @see struct rte_event_timer_adapter_conf::flags
158 * @b EXPERIMENTAL: this structure may change without prior notice
160 * Timer adapter configuration structure
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 */
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 */
174 /**< Maximum timer timeout(expiry) in ns */
176 /**< Total number of timers per adapter */
178 /**< Timer adapter config flags (RTE_EVENT_TIMER_ADAPTER_F_*) */
183 * @b EXPERIMENTAL: this structure may change without prior notice
185 * Event timer adapter stats structure
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 */
200 struct rte_event_timer_adapter;
204 * @b EXPERIMENTAL: this API may change without prior notice
206 * Callback function type for producer port creation.
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,
215 * @b EXPERIMENTAL: this API may change without prior notice
217 * Create an event timer adapter.
219 * This function must be invoked first before any other function in the API.
222 * The event timer adapter configuration structure.
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.
238 struct rte_event_timer_adapter * __rte_experimental
239 rte_event_timer_adapter_create(const struct rte_event_timer_adapter_conf *conf);
243 * @b EXPERIMENTAL: this API may change without prior notice
245 * Create a timer adapter with the supplied callback.
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
253 * The timer adapter configuration structure
255 * The port config callback function.
257 * Opaque pointer to the argument for the callback function
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
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,
276 * @b EXPERIMENTAL: this structure may change without prior notice
278 * Timer adapter info structure.
280 struct rte_event_timer_adapter_info {
281 uint64_t min_resolution_ns;
282 /**< Minimum timer adapter resolution in ns */
284 /**< Maximum timer timeout(expire) in ns */
285 struct rte_event_timer_adapter_conf conf;
286 /**< Configured timer adapter attributes */
288 /**< Event timer adapter capabilities */
289 int16_t event_dev_port_id;
290 /**< Event device port ID, if applicable */
295 * @b EXPERIMENTAL: this API may change without prior notice
297 * Retrieve the contextual information of an event timer adapter.
300 * A pointer to the event timer adapter structure.
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.
307 * - 0: Success, driver updates the contextual information of the
309 * - <0: Error code returned by the driver info get function.
310 * - -EINVAL: adapter identifier invalid
312 * @see RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES,
313 * struct rte_event_timer_adapter_info
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);
323 * @b EXPERIMENTAL: this API may change without prior notice
325 * Start a timer adapter.
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.
330 * On success, all basic functions exported by the API (timer arm,
331 * timer cancel and so on) can be invoked.
334 * A pointer to the event timer adapter structure.
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 * - -EALREADY if adapter has already been started
345 * The eventdev to which the event_timer_adapter is connected needs to
346 * be started before calling rte_event_timer_adapter_start().
348 int __rte_experimental
349 rte_event_timer_adapter_start(
350 const struct rte_event_timer_adapter *adapter);
354 * @b EXPERIMENTAL: this API may change without prior notice
356 * Stop an event timer adapter.
358 * The adapter can be restarted with a call to
359 * ``rte_event_timer_adapter_start()``.
362 * A pointer to the event timer adapter structure.
365 * - 0: Success, adapter stopped.
366 * - <0: Error code returned by the driver stop function.
367 * - -EINVAL if adapter identifier invalid
369 int __rte_experimental
370 rte_event_timer_adapter_stop(const struct rte_event_timer_adapter *adapter);
374 * @b EXPERIMENTAL: this API may change without prior notice
376 * Lookup an event timer adapter using its identifier.
378 * If an event timer adapter was created in another process with the same
379 * identifier, this function will locate its state and set up access to it
380 * so that it can be used in this process.
383 * The event timer adapter identifier.
386 * A pointer to the event timer adapter matching the identifier on success.
387 * NULL on error with rte_errno set appropriately.
388 * Possible rte_errno values include:
389 * - ENOENT - requested entry not available to return.
391 struct rte_event_timer_adapter * __rte_experimental
392 rte_event_timer_adapter_lookup(uint16_t adapter_id);
396 * @b EXPERIMENTAL: this API may change without prior notice
398 * Free an event timer adapter.
400 * Destroy an event timer adapter, freeing all resources.
402 * Before invoking this function, the application must wait for all the
403 * armed timers to expire or cancel the outstanding armed timers.
406 * A pointer to an event timer adapter structure.
409 * - 0: Successfully freed the event timer adapter resources.
410 * - <0: Failed to free the event timer adapter resources.
411 * - -EAGAIN: adapter is busy; timers outstanding
412 * - -EBUSY: stop hasn't been called for this adapter yet
413 * - -EINVAL: adapter id invalid, or adapter invalid
415 int __rte_experimental
416 rte_event_timer_adapter_free(struct rte_event_timer_adapter *adapter);
419 * Retrieve the service ID of the event timer adapter. If the adapter doesn't
420 * use an rte_service function, this function returns -ESRCH.
423 * A pointer to an event timer adapter.
425 * @param [out] service_id
426 * A pointer to a uint32_t, to be filled in with the service id.
430 * - <0: Error code on failure
431 * - -ESRCH: the adapter does not require a service to operate
433 int __rte_experimental
434 rte_event_timer_adapter_service_id_get(struct rte_event_timer_adapter *adapter,
435 uint32_t *service_id);
439 * @b EXPERIMENTAL: this API may change without prior notice
441 * Retrieve statistics for an event timer adapter instance.
444 * A pointer to an event timer adapter structure.
446 * A pointer to a structure to fill with statistics.
449 * - 0: Successfully retrieved.
450 * - <0: Failure; error code returned.
452 int __rte_experimental
453 rte_event_timer_adapter_stats_get(struct rte_event_timer_adapter *adapter,
454 struct rte_event_timer_adapter_stats *stats);
458 * @b EXPERIMENTAL: this API may change without prior notice
460 * Reset statistics for an event timer adapter instance.
463 * A pointer to an event timer adapter structure.
466 * - 0: Successfully reset;
467 * - <0: Failure; error code returned.
469 int __rte_experimental
470 rte_event_timer_adapter_stats_reset(struct rte_event_timer_adapter *adapter);
474 * @b EXPERIMENTAL: this structure may change without prior notice
478 enum rte_event_timer_state {
479 RTE_EVENT_TIMER_NOT_ARMED = 0,
480 /**< Event timer not armed. */
481 RTE_EVENT_TIMER_ARMED = 1,
482 /**< Event timer successfully armed. */
483 RTE_EVENT_TIMER_CANCELED = 2,
484 /**< Event timer successfully canceled. */
485 RTE_EVENT_TIMER_ERROR = -1,
486 /**< Generic event timer error. */
487 RTE_EVENT_TIMER_ERROR_TOOEARLY = -2,
488 /**< Event timer timeout tick value is too small for the adapter to
489 * handle, given its configured resolution.
491 RTE_EVENT_TIMER_ERROR_TOOLATE = -3,
492 /**< Event timer timeout tick is greater than the maximum timeout.*/
497 * @b EXPERIMENTAL: this structure may change without prior notice
499 * The generic *rte_event_timer* structure to hold the event timer attributes
500 * for arm and cancel operations.
503 struct rte_event_timer {
506 * Expiry event attributes. On successful event timer timeout,
507 * the following attributes will be used to inject the expiry event to
509 * - event_queue_id: Targeted event queue id for expiry events.
510 * - event_priority: Event priority of the event expiry event in the
511 * event queue relative to other events.
512 * - sched_type: Scheduling type of the expiry event.
513 * - flow_id: Flow id of the expiry event.
514 * - op: RTE_EVENT_OP_NEW
515 * - event_type: RTE_EVENT_TYPE_TIMER
517 volatile enum rte_event_timer_state state;
518 /**< State of the event timer. */
519 uint64_t timeout_ticks;
520 /**< Expiry timer ticks expressed in number of *timer_ticks_ns* from
522 * @see struct rte_event_timer_adapter_info::adapter_conf::timer_tick_ns
524 uint64_t impl_opaque[2];
525 /**< Implementation-specific opaque data.
526 * An event timer adapter implementation use this field to hold
527 * implementation specific values to share between the arm and cancel
528 * operations. The application should not modify this field.
530 uint8_t user_meta[0];
531 /**< Memory to store user specific metadata.
532 * The event timer adapter implementation should not modify this area.
534 } __rte_cache_aligned;
536 typedef uint16_t (*rte_event_timer_arm_burst_t)(
537 const struct rte_event_timer_adapter *adapter,
538 struct rte_event_timer **tims,
540 /**< @internal Enable event timers to enqueue timer events upon expiry */
541 typedef uint16_t (*rte_event_timer_arm_tmo_tick_burst_t)(
542 const struct rte_event_timer_adapter *adapter,
543 struct rte_event_timer **tims,
544 uint64_t timeout_tick,
546 /**< @internal Enable event timers with common expiration time */
547 typedef uint16_t (*rte_event_timer_cancel_burst_t)(
548 const struct rte_event_timer_adapter *adapter,
549 struct rte_event_timer **tims,
551 /**< @internal Prevent event timers from enqueuing timer events */
554 * @internal Data structure associated with each event timer adapter.
556 struct rte_event_timer_adapter {
557 rte_event_timer_arm_burst_t arm_burst;
558 /**< Pointer to driver arm_burst function. */
559 rte_event_timer_arm_tmo_tick_burst_t arm_tmo_tick_burst;
560 /**< Pointer to driver arm_tmo_tick_burst function. */
561 rte_event_timer_cancel_burst_t cancel_burst;
562 /**< Pointer to driver cancel function. */
563 struct rte_event_timer_adapter_data *data;
564 /**< Pointer to shared adapter data */
565 const struct rte_event_timer_adapter_ops *ops;
566 /**< Functions exported by adapter driver */
569 uint8_t allocated : 1;
570 /**< Flag to indicate that this adapter has been allocated */
571 } __rte_cache_aligned;
573 #define ADAPTER_VALID_OR_ERR_RET(adapter, retval) do { \
574 if (adapter == NULL || !adapter->allocated) \
578 #define FUNC_PTR_OR_ERR_RET(func, errval) do { \
579 if ((func) == NULL) \
583 #define FUNC_PTR_OR_NULL_RET_WITH_ERRNO(func, errval) do { \
584 if ((func) == NULL) { \
585 rte_errno = errval; \
592 * @b EXPERIMENTAL: this API may change without prior notice
594 * Arm a burst of event timers with separate expiration timeout tick for each
597 * Before calling this function, the application allocates
598 * ``struct rte_event_timer`` objects from mempool or huge page backed
599 * application buffers of desired size. On successful allocation,
600 * application updates the `struct rte_event_timer`` attributes such as
601 * expiry event attributes, timeout ticks from now.
602 * This function submits the event timer arm requests to the event timer adapter
603 * and on expiry, the events will be injected to designated event queue.
606 * A pointer to an event timer adapter structure.
608 * Pointer to an array of objects of type *rte_event_timer* structure.
610 * Number of event timers in the supplied array.
613 * The number of successfully armed event timers. The return value can be less
614 * than the value of the *nb_evtims* parameter. If the return value is less
615 * than *nb_evtims*, the remaining event timers at the end of *evtims*
616 * are not consumed, and the caller has to take care of them, and rte_errno
617 * is set accordingly. Possible errno values include:
618 * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
619 * expiry event's sched type doesn't match the capabilities of the
620 * destination event queue.
621 * - EAGAIN Specified timer adapter is not running
622 * - EALREADY A timer was encountered that was already armed
624 static inline uint16_t __rte_experimental
625 rte_event_timer_arm_burst(const struct rte_event_timer_adapter *adapter,
626 struct rte_event_timer **evtims,
629 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
630 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
631 FUNC_PTR_OR_ERR_RET(adapter->arm_burst, -EINVAL);
633 return adapter->arm_burst(adapter, evtims, nb_evtims);
638 * @b EXPERIMENTAL: this API may change without prior notice
640 * Arm a burst of event timers with same expiration timeout tick.
642 * Provides the same functionality as ``rte_event_timer_arm_burst()``, except
643 * that application can use this API when all the event timers have the
644 * same timeout expiration tick. This specialized function can provide the
645 * additional hint to the adapter implementation and optimize if possible.
648 * A pointer to an event timer adapter structure.
650 * Points to an array of objects of type *rte_event_timer* structure.
651 * @param timeout_ticks
652 * The number of ticks in which the timers should expire.
654 * Number of event timers in the supplied array.
657 * The number of successfully armed event timers. The return value can be less
658 * than the value of the *nb_evtims* parameter. If the return value is less
659 * than *nb_evtims*, the remaining event timers at the end of *evtims*
660 * are not consumed, and the caller has to take care of them, and rte_errno
661 * is set accordingly. Possible errno values include:
662 * - EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an
663 * expiry event's sched type doesn't match the capabilities of the
664 * destination event queue.
665 * - EAGAIN Specified event timer adapter is not running
666 * - EALREADY A timer was encountered that was already armed
668 static inline uint16_t __rte_experimental
669 rte_event_timer_arm_tmo_tick_burst(
670 const struct rte_event_timer_adapter *adapter,
671 struct rte_event_timer **evtims,
672 const uint64_t timeout_ticks,
673 const uint16_t nb_evtims)
675 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
676 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
677 FUNC_PTR_OR_ERR_RET(adapter->arm_tmo_tick_burst, -EINVAL);
679 return adapter->arm_tmo_tick_burst(adapter, evtims, timeout_ticks,
685 * @b EXPERIMENTAL: this API may change without prior notice
687 * Cancel a burst of event timers from being scheduled to the event device.
690 * A pointer to an event timer adapter structure.
692 * Points to an array of objects of type *rte_event_timer* structure
694 * Number of event timer instances in the supplied array.
697 * The number of successfully canceled event timers. The return value can be
698 * less than the value of the *nb_evtims* parameter. If the return value is
699 * less than *nb_evtims*, the remaining event timers at the end of *evtims*
700 * are not consumed, and the caller has to take care of them, and rte_errno
701 * is set accordingly. Possible errno values include:
702 * - EINVAL Invalid timer adapter identifier
703 * - EAGAIN Specified timer adapter is not running
704 * - EALREADY A timer was encountered that was already canceled
706 static inline uint16_t __rte_experimental
707 rte_event_timer_cancel_burst(const struct rte_event_timer_adapter *adapter,
708 struct rte_event_timer **evtims,
711 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
712 ADAPTER_VALID_OR_ERR_RET(adapter, -EINVAL);
713 FUNC_PTR_OR_ERR_RET(adapter->cancel_burst, -EINVAL);
715 return adapter->cancel_burst(adapter, evtims, nb_evtims);
718 #endif /* __RTE_EVENT_TIMER_ADAPTER_H__ */