1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2014 Intel Corporation
12 * This library provides a timer service to RTE Data Plane execution
13 * units that allows the execution of callback functions asynchronously.
15 * - Timers can be periodic or single (one-shot).
16 * - The timers can be loaded from one core and executed on another. This has
17 * to be specified in the call to rte_timer_reset().
18 * - High precision is possible. NOTE: this depends on the call frequency to
19 * rte_timer_manage() that check the timer expiration for the local core.
20 * - If not used in an application, for improved performance, it can be
21 * disabled at compilation time by not calling the rte_timer_manage()
22 * to improve performance.
24 * The timer library uses the rte_get_hpet_cycles() function that
25 * uses the HPET, when available, to provide a reliable time reference. [HPET
26 * routines are provided by EAL, which falls back to using the chip TSC (time-
27 * stamp counter) as fallback when HPET is not available]
29 * This library provides an interface to add, delete and restart a
30 * timer. The API is based on the BSD callout(9) API with a few
33 * See the RTE architecture documentation for more information about the
34 * design of this library.
40 #include <rte_common.h>
41 #include <rte_config.h>
42 #include <rte_spinlock.h>
48 #define RTE_TIMER_STOP 0 /**< State: timer is stopped. */
49 #define RTE_TIMER_PENDING 1 /**< State: timer is scheduled. */
50 #define RTE_TIMER_RUNNING 2 /**< State: timer function is running. */
51 #define RTE_TIMER_CONFIG 3 /**< State: timer is being configured. */
53 #define RTE_TIMER_NO_OWNER -2 /**< Timer has no owner. */
56 * Timer type: Periodic or single (one-shot).
64 * Timer status: A union of the state (stopped, pending, running,
65 * config) and an owner (the id of the lcore that owns the timer).
67 union rte_timer_status {
70 uint16_t state; /**< Stop, pending, running, config. */
71 int16_t owner; /**< The lcore that owns the timer. */
73 uint32_t u32; /**< To atomic-set status + owner. */
76 #ifdef RTE_LIBRTE_TIMER_DEBUG
78 * A structure that stores the timer statistics (per-lcore).
80 struct rte_timer_debug_stats {
81 uint64_t reset; /**< Number of success calls to rte_timer_reset(). */
82 uint64_t stop; /**< Number of success calls to rte_timer_stop(). */
83 uint64_t manage; /**< Number of calls to rte_timer_manage(). */
84 uint64_t pending; /**< Number of pending/running timers. */
91 * Callback function type for timer expiry.
93 typedef void (*rte_timer_cb_t)(struct rte_timer *, void *);
95 #define MAX_SKIPLIST_DEPTH 10
98 * A structure describing a timer in RTE.
102 uint64_t expire; /**< Time when timer expire. */
103 struct rte_timer *sl_next[MAX_SKIPLIST_DEPTH];
104 volatile union rte_timer_status status; /**< Status of timer. */
105 uint64_t period; /**< Period of timer (0 if not periodic). */
106 rte_timer_cb_t f; /**< Callback function. */
107 void *arg; /**< Argument to callback function. */
113 * A C++ static initializer for a timer structure.
115 #define RTE_TIMER_INITIALIZER { \
118 {{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \
125 * A static initializer for a timer structure.
127 #define RTE_TIMER_INITIALIZER { \
129 .state = RTE_TIMER_STOP, \
130 .owner = RTE_TIMER_NO_OWNER, \
137 * @b EXPERIMENTAL: this API may change without prior notice
139 * Allocate a timer data instance in shared memory to track a set of pending
143 * Pointer to variable into which to write the identifier of the allocated
144 * timer data instance.
148 * - -ENOSPC: maximum number of timer data instances already allocated
150 int __rte_experimental rte_timer_data_alloc(uint32_t *id_ptr);
154 * @b EXPERIMENTAL: this API may change without prior notice
156 * Deallocate a timer data instance.
159 * Identifier of the timer data instance to deallocate.
163 * - -EINVAL: invalid timer data instance identifier
165 int __rte_experimental rte_timer_data_dealloc(uint32_t id);
168 * Initialize the timer library.
170 * Initializes internal variables (list, locks and so on) for the RTE
173 void rte_timer_subsystem_init_v20(void);
176 * Initialize the timer library.
178 * Initializes internal variables (list, locks and so on) for the RTE
183 * - -EEXIST: Returned in secondary process when primary process has not
184 * yet initialized the timer subsystem
185 * - -ENOMEM: Unable to allocate memory needed to initialize timer
188 int rte_timer_subsystem_init_v1905(void);
189 int rte_timer_subsystem_init(void);
193 * @b EXPERIMENTAL: this API may change without prior notice
195 * Free timer subsystem resources.
197 void __rte_experimental rte_timer_subsystem_finalize(void);
200 * Initialize a timer handle.
202 * The rte_timer_init() function initializes the timer handle *tim*
203 * for use. No operations can be performed on a timer before it is
207 * The timer to initialize.
209 void rte_timer_init(struct rte_timer *tim);
212 * Reset and start the timer associated with the timer handle.
214 * The rte_timer_reset() function resets and starts the timer
215 * associated with the timer handle *tim*. When the timer expires after
216 * *ticks* HPET cycles, the function specified by *fct* will be called
217 * with the argument *arg* on core *tim_lcore*.
219 * If the timer associated with the timer handle is already running
220 * (in the RUNNING state), the function will fail. The user has to check
221 * the return value of the function to see if there is a chance that the
222 * timer is in the RUNNING state.
224 * If the timer is being configured on another core (the CONFIG state),
227 * If the timer is pending or stopped, it will be rescheduled with the
233 * The number of cycles (see rte_get_hpet_hz()) before the callback
234 * function is called.
236 * The type can be either:
237 * - PERIODICAL: The timer is automatically reloaded after execution
238 * (returns to the PENDING state)
239 * - SINGLE: The timer is one-shot, that is, the timer goes to a
240 * STOPPED state after execution.
242 * The ID of the lcore where the timer callback function has to be
243 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
244 * launch it on a different core for each call (round-robin).
246 * The callback function of the timer.
248 * The user argument of the callback function.
250 * - 0: Success; the timer is scheduled.
251 * - (-1): Timer is in the RUNNING or CONFIG state.
253 int rte_timer_reset_v20(struct rte_timer *tim, uint64_t ticks,
254 enum rte_timer_type type, unsigned int tim_lcore,
255 rte_timer_cb_t fct, void *arg);
256 int rte_timer_reset_v1905(struct rte_timer *tim, uint64_t ticks,
257 enum rte_timer_type type, unsigned int tim_lcore,
258 rte_timer_cb_t fct, void *arg);
259 int rte_timer_reset(struct rte_timer *tim, uint64_t ticks,
260 enum rte_timer_type type, unsigned tim_lcore,
261 rte_timer_cb_t fct, void *arg);
265 * Loop until rte_timer_reset() succeeds.
267 * Reset and start the timer associated with the timer handle. Always
268 * succeed. See rte_timer_reset() for details.
273 * The number of cycles (see rte_get_hpet_hz()) before the callback
274 * function is called.
276 * The type can be either:
277 * - PERIODICAL: The timer is automatically reloaded after execution
278 * (returns to the PENDING state)
279 * - SINGLE: The timer is one-shot, that is, the timer goes to a
280 * STOPPED state after execution.
282 * The ID of the lcore where the timer callback function has to be
283 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
284 * launch it on a different core for each call (round-robin).
286 * The callback function of the timer.
288 * The user argument of the callback function.
291 rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks,
292 enum rte_timer_type type, unsigned tim_lcore,
293 rte_timer_cb_t fct, void *arg);
298 * The rte_timer_stop() function stops the timer associated with the
299 * timer handle *tim*. It may fail if the timer is currently running or
302 * If the timer is pending or stopped (for instance, already expired),
303 * the function will succeed. The timer handle tim must have been
304 * initialized using rte_timer_init(), otherwise, undefined behavior
307 * This function can be called safely from a timer callback. If it
308 * succeeds, the timer is not referenced anymore by the timer library
309 * and the timer structure can be freed (even in the callback
315 * - 0: Success; the timer is stopped.
316 * - (-1): The timer is in the RUNNING or CONFIG state.
318 int rte_timer_stop_v20(struct rte_timer *tim);
319 int rte_timer_stop_v1905(struct rte_timer *tim);
320 int rte_timer_stop(struct rte_timer *tim);
323 * Loop until rte_timer_stop() succeeds.
325 * After a call to this function, the timer identified by *tim* is
326 * stopped. See rte_timer_stop() for details.
331 void rte_timer_stop_sync(struct rte_timer *tim);
334 * Test if a timer is pending.
336 * The rte_timer_pending() function tests the PENDING status
337 * of the timer handle *tim*. A PENDING timer is one that has been
338 * scheduled and whose function has not yet been called.
343 * - 0: The timer is not pending.
344 * - 1: The timer is pending.
346 int rte_timer_pending(struct rte_timer *tim);
349 * Manage the timer list and execute callback functions.
351 * This function must be called periodically from EAL lcores
352 * main_loop(). It browses the list of pending timers and runs all
353 * timers that are expired.
355 * The precision of the timer depends on the call frequency of this
356 * function. However, the more often the function is called, the more
357 * CPU resources it will use.
359 void rte_timer_manage_v20(void);
362 * Manage the timer list and execute callback functions.
364 * This function must be called periodically from EAL lcores
365 * main_loop(). It browses the list of pending timers and runs all
366 * timers that are expired.
368 * The precision of the timer depends on the call frequency of this
369 * function. However, the more often the function is called, the more
370 * CPU resources it will use.
374 * - -EINVAL: timer subsystem not yet initialized
376 int rte_timer_manage_v1905(void);
377 int rte_timer_manage(void);
380 * Dump statistics about timers.
383 * A pointer to a file for output
385 void rte_timer_dump_stats_v20(FILE *f);
388 * Dump statistics about timers.
391 * A pointer to a file for output
394 * - -EINVAL: timer subsystem not yet initialized
396 int rte_timer_dump_stats_v1905(FILE *f);
397 int rte_timer_dump_stats(FILE *f);
401 * @b EXPERIMENTAL: this API may change without prior notice
403 * This function is the same as rte_timer_reset(), except that it allows a
404 * caller to specify the rte_timer_data instance containing the list to which
405 * the timer should be added.
407 * @see rte_timer_reset()
409 * @param timer_data_id
410 * An identifier indicating which instance of timer data should be used for
415 * The number of cycles (see rte_get_hpet_hz()) before the callback
416 * function is called.
418 * The type can be either:
419 * - PERIODICAL: The timer is automatically reloaded after execution
420 * (returns to the PENDING state)
421 * - SINGLE: The timer is one-shot, that is, the timer goes to a
422 * STOPPED state after execution.
424 * The ID of the lcore where the timer callback function has to be
425 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
426 * launch it on a different core for each call (round-robin).
428 * The callback function of the timer. This parameter can be NULL if (and
429 * only if) rte_timer_alt_manage() will be used to manage this timer.
431 * The user argument of the callback function.
433 * - 0: Success; the timer is scheduled.
434 * - (-1): Timer is in the RUNNING or CONFIG state.
435 * - -EINVAL: invalid timer_data_id
437 int __rte_experimental
438 rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim,
439 uint64_t ticks, enum rte_timer_type type,
440 unsigned int tim_lcore, rte_timer_cb_t fct, void *arg);
444 * @b EXPERIMENTAL: this API may change without prior notice
446 * This function is the same as rte_timer_stop(), except that it allows a
447 * caller to specify the rte_timer_data instance containing the list from which
448 * this timer should be removed.
450 * @see rte_timer_stop()
452 * @param timer_data_id
453 * An identifier indicating which instance of timer data should be used for
458 * - 0: Success; the timer is stopped.
459 * - (-1): The timer is in the RUNNING or CONFIG state.
460 * - -EINVAL: invalid timer_data_id
462 int __rte_experimental
463 rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim);
466 * Callback function type for rte_timer_alt_manage().
468 typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim);
472 * @b EXPERIMENTAL: this API may change without prior notice
474 * Manage a set of timer lists and execute the specified callback function for
475 * all expired timers. This function is similar to rte_timer_manage(), except
476 * that it allows a caller to specify the timer_data instance that should
477 * be operated on, as well as a set of lcore IDs identifying which timer lists
478 * should be processed. Callback functions of individual timers are ignored.
480 * @see rte_timer_manage()
482 * @param timer_data_id
483 * An identifier indicating which instance of timer data should be used for
486 * An array of lcore ids identifying the timer lists that should be processed.
487 * NULL is allowed - if NULL, the timer list corresponding to the lcore
488 * calling this routine is processed (same as rte_timer_manage()).
489 * @param n_poll_lcores
490 * The size of the poll_lcores array. If 'poll_lcores' is NULL, this parameter
493 * The callback function which should be called for all expired timers.
496 * - -EINVAL: invalid timer_data_id
498 int __rte_experimental
499 rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores,
500 int n_poll_lcores, rte_timer_alt_manage_cb_t f);
503 * Callback function type for rte_timer_stop_all().
505 typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg);
509 * @b EXPERIMENTAL: this API may change without prior notice
511 * Walk the pending timer lists for the specified lcore IDs, and for each timer
512 * that is encountered, stop it and call the specified callback function to
513 * process it further.
515 * @param timer_data_id
516 * An identifier indicating which instance of timer data should be used for
519 * An array of lcore ids identifying the timer lists that should be processed.
520 * @param nb_walk_lcores
521 * The size of the walk_lcores array.
523 * The callback function which should be called for each timers. Can be NULL.
525 * An arbitrary argument that will be passed to f, if it is called.
528 * - EINVAL: invalid timer_data_id
530 int __rte_experimental
531 rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores,
532 int nb_walk_lcores, rte_timer_stop_all_cb_t f, void *f_arg);
536 * @b EXPERIMENTAL: this API may change without prior notice
538 * This function is the same as rte_timer_dump_stats(), except that it allows
539 * the caller to specify the rte_timer_data instance that should be used.
541 * @see rte_timer_dump_stats()
543 * @param timer_data_id
544 * An identifier indicating which instance of timer data should be used for
547 * A pointer to a file for output
550 * - -EINVAL: invalid timer_data_id
552 int __rte_experimental
553 rte_timer_alt_dump_stats(uint32_t timer_data_id, FILE *f);
559 #endif /* _RTE_TIMER_H_ */