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
175 * - -EEXIST: Returned in secondary process when primary process has not
176 * yet initialized the timer subsystem
177 * - -ENOMEM: Unable to allocate memory needed to initialize timer
180 int rte_timer_subsystem_init(void);
181 int rte_timer_subsystem_init_v1905(void);
182 void rte_timer_subsystem_init_v20(void);
186 * @b EXPERIMENTAL: this API may change without prior notice
188 * Free timer subsystem resources.
190 void __rte_experimental
rte_timer_subsystem_finalize(void);
193 * Initialize a timer handle.
195 * The rte_timer_init() function initializes the timer handle *tim*
196 * for use. No operations can be performed on a timer before it is
200 * The timer to initialize.
202 void rte_timer_init(struct rte_timer
*tim
);
205 * Reset and start the timer associated with the timer handle.
207 * The rte_timer_reset() function resets and starts the timer
208 * associated with the timer handle *tim*. When the timer expires after
209 * *ticks* HPET cycles, the function specified by *fct* will be called
210 * with the argument *arg* on core *tim_lcore*.
212 * If the timer associated with the timer handle is already running
213 * (in the RUNNING state), the function will fail. The user has to check
214 * the return value of the function to see if there is a chance that the
215 * timer is in the RUNNING state.
217 * If the timer is being configured on another core (the CONFIG state),
220 * If the timer is pending or stopped, it will be rescheduled with the
226 * The number of cycles (see rte_get_hpet_hz()) before the callback
227 * function is called.
229 * The type can be either:
230 * - PERIODICAL: The timer is automatically reloaded after execution
231 * (returns to the PENDING state)
232 * - SINGLE: The timer is one-shot, that is, the timer goes to a
233 * STOPPED state after execution.
235 * The ID of the lcore where the timer callback function has to be
236 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
237 * launch it on a different core for each call (round-robin).
239 * The callback function of the timer.
241 * The user argument of the callback function.
243 * - 0: Success; the timer is scheduled.
244 * - (-1): Timer is in the RUNNING or CONFIG state.
246 int rte_timer_reset(struct rte_timer
*tim
, uint64_t ticks
,
247 enum rte_timer_type type
, unsigned tim_lcore
,
248 rte_timer_cb_t fct
, void *arg
);
249 int rte_timer_reset_v1905(struct rte_timer
*tim
, uint64_t ticks
,
250 enum rte_timer_type type
, unsigned int tim_lcore
,
251 rte_timer_cb_t fct
, void *arg
);
252 int rte_timer_reset_v20(struct rte_timer
*tim
, uint64_t ticks
,
253 enum rte_timer_type type
, unsigned int tim_lcore
,
254 rte_timer_cb_t fct
, void *arg
);
258 * Loop until rte_timer_reset() succeeds.
260 * Reset and start the timer associated with the timer handle. Always
261 * succeed. See rte_timer_reset() for details.
266 * The number of cycles (see rte_get_hpet_hz()) before the callback
267 * function is called.
269 * The type can be either:
270 * - PERIODICAL: The timer is automatically reloaded after execution
271 * (returns to the PENDING state)
272 * - SINGLE: The timer is one-shot, that is, the timer goes to a
273 * STOPPED state after execution.
275 * The ID of the lcore where the timer callback function has to be
276 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
277 * launch it on a different core for each call (round-robin).
279 * The callback function of the timer.
281 * The user argument of the callback function.
284 rte_timer_reset_sync(struct rte_timer
*tim
, uint64_t ticks
,
285 enum rte_timer_type type
, unsigned tim_lcore
,
286 rte_timer_cb_t fct
, void *arg
);
291 * The rte_timer_stop() function stops the timer associated with the
292 * timer handle *tim*. It may fail if the timer is currently running or
295 * If the timer is pending or stopped (for instance, already expired),
296 * the function will succeed. The timer handle tim must have been
297 * initialized using rte_timer_init(), otherwise, undefined behavior
300 * This function can be called safely from a timer callback. If it
301 * succeeds, the timer is not referenced anymore by the timer library
302 * and the timer structure can be freed (even in the callback
308 * - 0: Success; the timer is stopped.
309 * - (-1): The timer is in the RUNNING or CONFIG state.
311 int rte_timer_stop(struct rte_timer
*tim
);
312 int rte_timer_stop_v1905(struct rte_timer
*tim
);
313 int rte_timer_stop_v20(struct rte_timer
*tim
);
316 * Loop until rte_timer_stop() succeeds.
318 * After a call to this function, the timer identified by *tim* is
319 * stopped. See rte_timer_stop() for details.
324 void rte_timer_stop_sync(struct rte_timer
*tim
);
327 * Test if a timer is pending.
329 * The rte_timer_pending() function tests the PENDING status
330 * of the timer handle *tim*. A PENDING timer is one that has been
331 * scheduled and whose function has not yet been called.
336 * - 0: The timer is not pending.
337 * - 1: The timer is pending.
339 int rte_timer_pending(struct rte_timer
*tim
);
342 * Manage the timer list and execute callback functions.
344 * This function must be called periodically from EAL lcores
345 * main_loop(). It browses the list of pending timers and runs all
346 * timers that are expired.
348 * The precision of the timer depends on the call frequency of this
349 * function. However, the more often the function is called, the more
350 * CPU resources it will use.
354 * - -EINVAL: timer subsystem not yet initialized
356 int rte_timer_manage(void);
357 int rte_timer_manage_v1905(void);
358 void rte_timer_manage_v20(void);
361 * Dump statistics about timers.
364 * A pointer to a file for output
367 * - -EINVAL: timer subsystem not yet initialized
369 int rte_timer_dump_stats(FILE *f
);
370 int rte_timer_dump_stats_v1905(FILE *f
);
371 void rte_timer_dump_stats_v20(FILE *f
);
375 * @b EXPERIMENTAL: this API may change without prior notice
377 * This function is the same as rte_timer_reset(), except that it allows a
378 * caller to specify the rte_timer_data instance containing the list to which
379 * the timer should be added.
381 * @see rte_timer_reset()
383 * @param timer_data_id
384 * An identifier indicating which instance of timer data should be used for
389 * The number of cycles (see rte_get_hpet_hz()) before the callback
390 * function is called.
392 * The type can be either:
393 * - PERIODICAL: The timer is automatically reloaded after execution
394 * (returns to the PENDING state)
395 * - SINGLE: The timer is one-shot, that is, the timer goes to a
396 * STOPPED state after execution.
398 * The ID of the lcore where the timer callback function has to be
399 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
400 * launch it on a different core for each call (round-robin).
402 * The callback function of the timer. This parameter can be NULL if (and
403 * only if) rte_timer_alt_manage() will be used to manage this timer.
405 * The user argument of the callback function.
407 * - 0: Success; the timer is scheduled.
408 * - (-1): Timer is in the RUNNING or CONFIG state.
409 * - -EINVAL: invalid timer_data_id
411 int __rte_experimental
412 rte_timer_alt_reset(uint32_t timer_data_id
, struct rte_timer
*tim
,
413 uint64_t ticks
, enum rte_timer_type type
,
414 unsigned int tim_lcore
, rte_timer_cb_t fct
, void *arg
);
418 * @b EXPERIMENTAL: this API may change without prior notice
420 * This function is the same as rte_timer_stop(), except that it allows a
421 * caller to specify the rte_timer_data instance containing the list from which
422 * this timer should be removed.
424 * @see rte_timer_stop()
426 * @param timer_data_id
427 * An identifier indicating which instance of timer data should be used for
432 * - 0: Success; the timer is stopped.
433 * - (-1): The timer is in the RUNNING or CONFIG state.
434 * - -EINVAL: invalid timer_data_id
436 int __rte_experimental
437 rte_timer_alt_stop(uint32_t timer_data_id
, struct rte_timer
*tim
);
440 * Callback function type for rte_timer_alt_manage().
442 typedef void (*rte_timer_alt_manage_cb_t
)(struct rte_timer
*tim
);
446 * @b EXPERIMENTAL: this API may change without prior notice
448 * Manage a set of timer lists and execute the specified callback function for
449 * all expired timers. This function is similar to rte_timer_manage(), except
450 * that it allows a caller to specify the timer_data instance that should
451 * be operated on, as well as a set of lcore IDs identifying which timer lists
452 * should be processed. Callback functions of individual timers are ignored.
454 * @see rte_timer_manage()
456 * @param timer_data_id
457 * An identifier indicating which instance of timer data should be used for
460 * An array of lcore ids identifying the timer lists that should be processed.
461 * NULL is allowed - if NULL, the timer list corresponding to the lcore
462 * calling this routine is processed (same as rte_timer_manage()).
463 * @param n_poll_lcores
464 * The size of the poll_lcores array. If 'poll_lcores' is NULL, this parameter
467 * The callback function which should be called for all expired timers.
470 * - -EINVAL: invalid timer_data_id
472 int __rte_experimental
473 rte_timer_alt_manage(uint32_t timer_data_id
, unsigned int *poll_lcores
,
474 int n_poll_lcores
, rte_timer_alt_manage_cb_t f
);
477 * Callback function type for rte_timer_stop_all().
479 typedef void (*rte_timer_stop_all_cb_t
)(struct rte_timer
*tim
, void *arg
);
483 * @b EXPERIMENTAL: this API may change without prior notice
485 * Walk the pending timer lists for the specified lcore IDs, and for each timer
486 * that is encountered, stop it and call the specified callback function to
487 * process it further.
489 * @param timer_data_id
490 * An identifier indicating which instance of timer data should be used for
493 * An array of lcore ids identifying the timer lists that should be processed.
494 * @param nb_walk_lcores
495 * The size of the walk_lcores array.
497 * The callback function which should be called for each timers. Can be NULL.
499 * An arbitrary argument that will be passed to f, if it is called.
502 * - EINVAL: invalid timer_data_id
504 int __rte_experimental
505 rte_timer_stop_all(uint32_t timer_data_id
, unsigned int *walk_lcores
,
506 int nb_walk_lcores
, rte_timer_stop_all_cb_t f
, void *f_arg
);
510 * @b EXPERIMENTAL: this API may change without prior notice
512 * This function is the same as rte_timer_dump_stats(), except that it allows
513 * the caller to specify the rte_timer_data instance that should be used.
515 * @see rte_timer_dump_stats()
517 * @param timer_data_id
518 * An identifier indicating which instance of timer data should be used for
521 * A pointer to a file for output
524 * - -EINVAL: invalid timer_data_id
526 int __rte_experimental
527 rte_timer_alt_dump_stats(uint32_t timer_data_id
, FILE *f
);
533 #endif /* _RTE_TIMER_H_ */