cd7c59dc04
It is useful to know when the next timer will expire when using rte_epoll_wait (or sleep when idle). This experimental API provides a hook to query the number of ticks remaining. Signed-off-by: Stephen Hemminger <stephen@networkplumber.org> Acked-by: Erik Gabriel Carrillo <erik.g.carrillo@intel.com>
544 lines
16 KiB
C
544 lines
16 KiB
C
/* SPDX-License-Identifier: BSD-3-Clause
|
|
* Copyright(c) 2010-2014 Intel Corporation
|
|
*/
|
|
|
|
#ifndef _RTE_TIMER_H_
|
|
#define _RTE_TIMER_H_
|
|
|
|
/**
|
|
* @file
|
|
RTE Timer
|
|
*
|
|
* This library provides a timer service to RTE Data Plane execution
|
|
* units that allows the execution of callback functions asynchronously.
|
|
*
|
|
* - Timers can be periodic or single (one-shot).
|
|
* - The timers can be loaded from one core and executed on another. This has
|
|
* to be specified in the call to rte_timer_reset().
|
|
* - High precision is possible. NOTE: this depends on the call frequency to
|
|
* rte_timer_manage() that check the timer expiration for the local core.
|
|
* - If not used in an application, for improved performance, it can be
|
|
* disabled at compilation time by not calling the rte_timer_manage()
|
|
* to improve performance.
|
|
*
|
|
* The timer library uses the rte_get_hpet_cycles() function that
|
|
* uses the HPET, when available, to provide a reliable time reference. [HPET
|
|
* routines are provided by EAL, which falls back to using the chip TSC (time-
|
|
* stamp counter) as fallback when HPET is not available]
|
|
*
|
|
* This library provides an interface to add, delete and restart a
|
|
* timer. The API is based on the BSD callout(9) API with a few
|
|
* differences.
|
|
*
|
|
* See the RTE architecture documentation for more information about the
|
|
* design of this library.
|
|
*/
|
|
|
|
#include <stdio.h>
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
#include <rte_common.h>
|
|
#include <rte_config.h>
|
|
#include <rte_spinlock.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#define RTE_TIMER_STOP 0 /**< State: timer is stopped. */
|
|
#define RTE_TIMER_PENDING 1 /**< State: timer is scheduled. */
|
|
#define RTE_TIMER_RUNNING 2 /**< State: timer function is running. */
|
|
#define RTE_TIMER_CONFIG 3 /**< State: timer is being configured. */
|
|
|
|
#define RTE_TIMER_NO_OWNER -2 /**< Timer has no owner. */
|
|
|
|
/**
|
|
* Timer type: Periodic or single (one-shot).
|
|
*/
|
|
enum rte_timer_type {
|
|
SINGLE,
|
|
PERIODICAL
|
|
};
|
|
|
|
/**
|
|
* Timer status: A union of the state (stopped, pending, running,
|
|
* config) and an owner (the id of the lcore that owns the timer).
|
|
*/
|
|
union rte_timer_status {
|
|
RTE_STD_C11
|
|
struct {
|
|
uint16_t state; /**< Stop, pending, running, config. */
|
|
int16_t owner; /**< The lcore that owns the timer. */
|
|
};
|
|
uint32_t u32; /**< To atomic-set status + owner. */
|
|
};
|
|
|
|
#ifdef RTE_LIBRTE_TIMER_DEBUG
|
|
/**
|
|
* A structure that stores the timer statistics (per-lcore).
|
|
*/
|
|
struct rte_timer_debug_stats {
|
|
uint64_t reset; /**< Number of success calls to rte_timer_reset(). */
|
|
uint64_t stop; /**< Number of success calls to rte_timer_stop(). */
|
|
uint64_t manage; /**< Number of calls to rte_timer_manage(). */
|
|
uint64_t pending; /**< Number of pending/running timers. */
|
|
};
|
|
#endif
|
|
|
|
struct rte_timer;
|
|
|
|
/**
|
|
* Callback function type for timer expiry.
|
|
*/
|
|
typedef void (*rte_timer_cb_t)(struct rte_timer *, void *);
|
|
|
|
#define MAX_SKIPLIST_DEPTH 10
|
|
|
|
/**
|
|
* A structure describing a timer in RTE.
|
|
*/
|
|
struct rte_timer
|
|
{
|
|
uint64_t expire; /**< Time when timer expire. */
|
|
struct rte_timer *sl_next[MAX_SKIPLIST_DEPTH];
|
|
volatile union rte_timer_status status; /**< Status of timer. */
|
|
uint64_t period; /**< Period of timer (0 if not periodic). */
|
|
rte_timer_cb_t f; /**< Callback function. */
|
|
void *arg; /**< Argument to callback function. */
|
|
};
|
|
|
|
|
|
#ifdef __cplusplus
|
|
/**
|
|
* A C++ static initializer for a timer structure.
|
|
*/
|
|
#define RTE_TIMER_INITIALIZER { \
|
|
0, \
|
|
{NULL}, \
|
|
{{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \
|
|
0, \
|
|
NULL, \
|
|
NULL, \
|
|
}
|
|
#else
|
|
/**
|
|
* A static initializer for a timer structure.
|
|
*/
|
|
#define RTE_TIMER_INITIALIZER { \
|
|
.status = {{ \
|
|
.state = RTE_TIMER_STOP, \
|
|
.owner = RTE_TIMER_NO_OWNER, \
|
|
}}, \
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* Allocate a timer data instance in shared memory to track a set of pending
|
|
* timer lists.
|
|
*
|
|
* @param id_ptr
|
|
* Pointer to variable into which to write the identifier of the allocated
|
|
* timer data instance.
|
|
*
|
|
* @return
|
|
* - 0: Success
|
|
* - -ENOSPC: maximum number of timer data instances already allocated
|
|
*/
|
|
__rte_experimental
|
|
int rte_timer_data_alloc(uint32_t *id_ptr);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* Deallocate a timer data instance.
|
|
*
|
|
* @param id
|
|
* Identifier of the timer data instance to deallocate.
|
|
*
|
|
* @return
|
|
* - 0: Success
|
|
* - -EINVAL: invalid timer data instance identifier
|
|
*/
|
|
__rte_experimental
|
|
int rte_timer_data_dealloc(uint32_t id);
|
|
|
|
/**
|
|
* Initialize the timer library.
|
|
*
|
|
* Initializes internal variables (list, locks and so on) for the RTE
|
|
* timer library.
|
|
*
|
|
* @note
|
|
* This function must be called in every process before using the library.
|
|
*
|
|
* @return
|
|
* - 0: Success
|
|
* - -ENOMEM: Unable to allocate memory needed to initialize timer
|
|
* subsystem
|
|
*/
|
|
int rte_timer_subsystem_init(void);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* Free timer subsystem resources.
|
|
*/
|
|
__rte_experimental
|
|
void rte_timer_subsystem_finalize(void);
|
|
|
|
/**
|
|
* Initialize a timer handle.
|
|
*
|
|
* The rte_timer_init() function initializes the timer handle *tim*
|
|
* for use. No operations can be performed on a timer before it is
|
|
* initialized.
|
|
*
|
|
* @param tim
|
|
* The timer to initialize.
|
|
*/
|
|
void rte_timer_init(struct rte_timer *tim);
|
|
|
|
/**
|
|
* Reset and start the timer associated with the timer handle.
|
|
*
|
|
* The rte_timer_reset() function resets and starts the timer
|
|
* associated with the timer handle *tim*. When the timer expires after
|
|
* *ticks* HPET cycles, the function specified by *fct* will be called
|
|
* with the argument *arg* on core *tim_lcore*.
|
|
*
|
|
* If the timer associated with the timer handle is already running
|
|
* (in the RUNNING state), the function will fail. The user has to check
|
|
* the return value of the function to see if there is a chance that the
|
|
* timer is in the RUNNING state.
|
|
*
|
|
* If the timer is being configured on another core (the CONFIG state),
|
|
* it will also fail.
|
|
*
|
|
* If the timer is pending or stopped, it will be rescheduled with the
|
|
* new parameters.
|
|
*
|
|
* @param tim
|
|
* The timer handle.
|
|
* @param ticks
|
|
* The number of cycles (see rte_get_hpet_hz()) before the callback
|
|
* function is called.
|
|
* @param type
|
|
* The type can be either:
|
|
* - PERIODICAL: The timer is automatically reloaded after execution
|
|
* (returns to the PENDING state)
|
|
* - SINGLE: The timer is one-shot, that is, the timer goes to a
|
|
* STOPPED state after execution.
|
|
* @param tim_lcore
|
|
* The ID of the lcore where the timer callback function has to be
|
|
* executed. If tim_lcore is LCORE_ID_ANY, the timer library will
|
|
* launch it on a different core for each call (round-robin).
|
|
* @param fct
|
|
* The callback function of the timer.
|
|
* @param arg
|
|
* The user argument of the callback function.
|
|
* @return
|
|
* - 0: Success; the timer is scheduled.
|
|
* - (-1): Timer is in the RUNNING or CONFIG state.
|
|
*/
|
|
int rte_timer_reset(struct rte_timer *tim, uint64_t ticks,
|
|
enum rte_timer_type type, unsigned tim_lcore,
|
|
rte_timer_cb_t fct, void *arg);
|
|
|
|
/**
|
|
* Loop until rte_timer_reset() succeeds.
|
|
*
|
|
* Reset and start the timer associated with the timer handle. Always
|
|
* succeed. See rte_timer_reset() for details.
|
|
*
|
|
* @param tim
|
|
* The timer handle.
|
|
* @param ticks
|
|
* The number of cycles (see rte_get_hpet_hz()) before the callback
|
|
* function is called.
|
|
* @param type
|
|
* The type can be either:
|
|
* - PERIODICAL: The timer is automatically reloaded after execution
|
|
* (returns to the PENDING state)
|
|
* - SINGLE: The timer is one-shot, that is, the timer goes to a
|
|
* STOPPED state after execution.
|
|
* @param tim_lcore
|
|
* The ID of the lcore where the timer callback function has to be
|
|
* executed. If tim_lcore is LCORE_ID_ANY, the timer library will
|
|
* launch it on a different core for each call (round-robin).
|
|
* @param fct
|
|
* The callback function of the timer.
|
|
* @param arg
|
|
* The user argument of the callback function.
|
|
*/
|
|
void
|
|
rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks,
|
|
enum rte_timer_type type, unsigned tim_lcore,
|
|
rte_timer_cb_t fct, void *arg);
|
|
|
|
/**
|
|
* Stop a timer.
|
|
*
|
|
* The rte_timer_stop() function stops the timer associated with the
|
|
* timer handle *tim*. It may fail if the timer is currently running or
|
|
* being configured.
|
|
*
|
|
* If the timer is pending or stopped (for instance, already expired),
|
|
* the function will succeed. The timer handle tim must have been
|
|
* initialized using rte_timer_init(), otherwise, undefined behavior
|
|
* will occur.
|
|
*
|
|
* This function can be called safely from a timer callback. If it
|
|
* succeeds, the timer is not referenced anymore by the timer library
|
|
* and the timer structure can be freed (even in the callback
|
|
* function).
|
|
*
|
|
* @param tim
|
|
* The timer handle.
|
|
* @return
|
|
* - 0: Success; the timer is stopped.
|
|
* - (-1): The timer is in the RUNNING or CONFIG state.
|
|
*/
|
|
int rte_timer_stop(struct rte_timer *tim);
|
|
|
|
/**
|
|
* Loop until rte_timer_stop() succeeds.
|
|
*
|
|
* After a call to this function, the timer identified by *tim* is
|
|
* stopped. See rte_timer_stop() for details.
|
|
*
|
|
* @param tim
|
|
* The timer handle.
|
|
*/
|
|
void rte_timer_stop_sync(struct rte_timer *tim);
|
|
|
|
/**
|
|
* Test if a timer is pending.
|
|
*
|
|
* The rte_timer_pending() function tests the PENDING status
|
|
* of the timer handle *tim*. A PENDING timer is one that has been
|
|
* scheduled and whose function has not yet been called.
|
|
*
|
|
* @param tim
|
|
* The timer handle.
|
|
* @return
|
|
* - 0: The timer is not pending.
|
|
* - 1: The timer is pending.
|
|
*/
|
|
int rte_timer_pending(struct rte_timer *tim);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* Time until the next timer on the current lcore
|
|
* This function gives the ticks until the next timer will be active.
|
|
*
|
|
* @return
|
|
* - -EINVAL: invalid timer data instance identifier
|
|
* - -ENOENT: no timer pending
|
|
* - 0: a timer is pending and will run at next rte_timer_manage()
|
|
* - >0: ticks until the next timer is ready
|
|
*/
|
|
__rte_experimental
|
|
int64_t rte_timer_next_ticks(void);
|
|
|
|
/**
|
|
* Manage the timer list and execute callback functions.
|
|
*
|
|
* This function must be called periodically from EAL lcores
|
|
* main_loop(). It browses the list of pending timers and runs all
|
|
* timers that are expired.
|
|
*
|
|
* The precision of the timer depends on the call frequency of this
|
|
* function. However, the more often the function is called, the more
|
|
* CPU resources it will use.
|
|
*
|
|
* @return
|
|
* - 0: Success
|
|
* - -EINVAL: timer subsystem not yet initialized
|
|
*/
|
|
int rte_timer_manage(void);
|
|
|
|
/**
|
|
* Dump statistics about timers.
|
|
*
|
|
* @param f
|
|
* A pointer to a file for output
|
|
* @return
|
|
* - 0: Success
|
|
* - -EINVAL: timer subsystem not yet initialized
|
|
*/
|
|
int rte_timer_dump_stats(FILE *f);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* This function is the same as rte_timer_reset(), except that it allows a
|
|
* caller to specify the rte_timer_data instance containing the list to which
|
|
* the timer should be added.
|
|
*
|
|
* @see rte_timer_reset()
|
|
*
|
|
* @param timer_data_id
|
|
* An identifier indicating which instance of timer data should be used for
|
|
* this operation.
|
|
* @param tim
|
|
* The timer handle.
|
|
* @param ticks
|
|
* The number of cycles (see rte_get_hpet_hz()) before the callback
|
|
* function is called.
|
|
* @param type
|
|
* The type can be either:
|
|
* - PERIODICAL: The timer is automatically reloaded after execution
|
|
* (returns to the PENDING state)
|
|
* - SINGLE: The timer is one-shot, that is, the timer goes to a
|
|
* STOPPED state after execution.
|
|
* @param tim_lcore
|
|
* The ID of the lcore where the timer callback function has to be
|
|
* executed. If tim_lcore is LCORE_ID_ANY, the timer library will
|
|
* launch it on a different core for each call (round-robin).
|
|
* @param fct
|
|
* The callback function of the timer. This parameter can be NULL if (and
|
|
* only if) rte_timer_alt_manage() will be used to manage this timer.
|
|
* @param arg
|
|
* The user argument of the callback function.
|
|
* @return
|
|
* - 0: Success; the timer is scheduled.
|
|
* - (-1): Timer is in the RUNNING or CONFIG state.
|
|
* - -EINVAL: invalid timer_data_id
|
|
*/
|
|
__rte_experimental
|
|
int
|
|
rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim,
|
|
uint64_t ticks, enum rte_timer_type type,
|
|
unsigned int tim_lcore, rte_timer_cb_t fct, void *arg);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* This function is the same as rte_timer_stop(), except that it allows a
|
|
* caller to specify the rte_timer_data instance containing the list from which
|
|
* this timer should be removed.
|
|
*
|
|
* @see rte_timer_stop()
|
|
*
|
|
* @param timer_data_id
|
|
* An identifier indicating which instance of timer data should be used for
|
|
* this operation.
|
|
* @param tim
|
|
* The timer handle.
|
|
* @return
|
|
* - 0: Success; the timer is stopped.
|
|
* - (-1): The timer is in the RUNNING or CONFIG state.
|
|
* - -EINVAL: invalid timer_data_id
|
|
*/
|
|
__rte_experimental
|
|
int
|
|
rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim);
|
|
|
|
/**
|
|
* Callback function type for rte_timer_alt_manage().
|
|
*/
|
|
typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* Manage a set of timer lists and execute the specified callback function for
|
|
* all expired timers. This function is similar to rte_timer_manage(), except
|
|
* that it allows a caller to specify the timer_data instance that should
|
|
* be operated on, as well as a set of lcore IDs identifying which timer lists
|
|
* should be processed. Callback functions of individual timers are ignored.
|
|
*
|
|
* @see rte_timer_manage()
|
|
*
|
|
* @param timer_data_id
|
|
* An identifier indicating which instance of timer data should be used for
|
|
* this operation.
|
|
* @param poll_lcores
|
|
* An array of lcore ids identifying the timer lists that should be processed.
|
|
* NULL is allowed - if NULL, the timer list corresponding to the lcore
|
|
* calling this routine is processed (same as rte_timer_manage()).
|
|
* @param n_poll_lcores
|
|
* The size of the poll_lcores array. If 'poll_lcores' is NULL, this parameter
|
|
* is ignored.
|
|
* @param f
|
|
* The callback function which should be called for all expired timers.
|
|
* @return
|
|
* - 0: success
|
|
* - -EINVAL: invalid timer_data_id
|
|
*/
|
|
__rte_experimental
|
|
int
|
|
rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores,
|
|
int n_poll_lcores, rte_timer_alt_manage_cb_t f);
|
|
|
|
/**
|
|
* Callback function type for rte_timer_stop_all().
|
|
*/
|
|
typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* Walk the pending timer lists for the specified lcore IDs, and for each timer
|
|
* that is encountered, stop it and call the specified callback function to
|
|
* process it further.
|
|
*
|
|
* @param timer_data_id
|
|
* An identifier indicating which instance of timer data should be used for
|
|
* this operation.
|
|
* @param walk_lcores
|
|
* An array of lcore ids identifying the timer lists that should be processed.
|
|
* @param nb_walk_lcores
|
|
* The size of the walk_lcores array.
|
|
* @param f
|
|
* The callback function which should be called for each timers. Can be NULL.
|
|
* @param f_arg
|
|
* An arbitrary argument that will be passed to f, if it is called.
|
|
* @return
|
|
* - 0: success
|
|
* - EINVAL: invalid timer_data_id
|
|
*/
|
|
__rte_experimental
|
|
int
|
|
rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores,
|
|
int nb_walk_lcores, rte_timer_stop_all_cb_t f, void *f_arg);
|
|
|
|
/**
|
|
* @warning
|
|
* @b EXPERIMENTAL: this API may change without prior notice
|
|
*
|
|
* This function is the same as rte_timer_dump_stats(), except that it allows
|
|
* the caller to specify the rte_timer_data instance that should be used.
|
|
*
|
|
* @see rte_timer_dump_stats()
|
|
*
|
|
* @param timer_data_id
|
|
* An identifier indicating which instance of timer data should be used for
|
|
* this operation.
|
|
* @param f
|
|
* A pointer to a file for output
|
|
* @return
|
|
* - 0: success
|
|
* - -EINVAL: invalid timer_data_id
|
|
*/
|
|
__rte_experimental
|
|
int
|
|
rte_timer_alt_dump_stats(uint32_t timer_data_id, FILE *f);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _RTE_TIMER_H_ */
|