4 * Copyright(c) 2010-2012 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * * Neither the name of Intel Corporation nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 * This library provides a timer service to RTE Data Plane execution
43 * units that allows the execution of callback functions asynchronously.
45 * - Timers can be periodic or single (one-shot).
46 * - The timers can be loaded from one core and executed on another. This has
47 * to be specified in the call to rte_timer_reset().
48 * - High precision is possible. NOTE: this depends on the call frequency to
49 * rte_timer_manage() that check the timer expiration for the local core.
50 * - If not used in an application, for improved performance, it can be
51 * disabled at compilation time by not calling the rte_timer_manage()
52 * to improve performance.
54 * The timer library uses the rte_get_hpet_cycles() function that
55 * uses the HPET, when available, to provide a reliable time reference. [HPET
56 * routines are provided by EAL, which falls back to using the chip TSC (time-
57 * stamp counter) as fallback when HPET is not available]
59 * This library provides an interface to add, delete and restart a
60 * timer. The API is based on the BSD callout(9) API with a few
63 * See the RTE architecture documentation for more information about the
64 * design of this library.
69 #include <sys/queue.h>
75 #define RTE_TIMER_STOP 0 /**< State: timer is stopped. */
76 #define RTE_TIMER_PENDING 1 /**< State: timer is scheduled. */
77 #define RTE_TIMER_RUNNING 2 /**< State: timer function is running. */
78 #define RTE_TIMER_CONFIG 3 /**< State: timer is being configured. */
80 #define RTE_TIMER_NO_OWNER -1 /**< Timer has no owner. */
83 * Timer type: Periodic or single (one-shot).
91 * Timer status: A union of the state (stopped, pending, running,
92 * config) and an owner (the id of the lcore that owns the timer).
94 union rte_timer_status {
96 uint16_t state; /**< Stop, pending, running, config. */
97 int16_t owner; /**< The lcore that owns the timer. */
99 uint32_t u32; /**< To atomic-set status + owner. */
102 #ifdef RTE_LIBRTE_TIMER_DEBUG
104 * A structure that stores the timer statistics (per-lcore).
106 struct rte_timer_debug_stats {
107 uint64_t reset; /**< Number of success calls to rte_timer_reset(). */
108 uint64_t stop; /**< Number of success calls to rte_timer_stop(). */
109 uint64_t manage; /**< Number of calls to rte_timer_manage(). */
110 uint64_t pending; /**< Number of pending/running timers. */
117 * Callback function type for timer expiry.
119 typedef void (rte_timer_cb_t)(struct rte_timer *, void *);
122 * A structure describing a timer in RTE.
126 LIST_ENTRY(rte_timer) next; /**< Next and prev in list. */
127 volatile union rte_timer_status status; /**< Status of timer. */
128 uint64_t period; /**< Period of timer (0 if not periodic). */
129 uint64_t expire; /**< Time when timer expire. */
130 rte_timer_cb_t *f; /**< Callback function. */
131 void *arg; /**< Argument to callback function. */
137 * A C++ static initializer for a timer structure.
139 #define RTE_TIMER_INITIALIZER { \
141 {{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \
149 * A static initializer for a timer structure.
151 #define RTE_TIMER_INITIALIZER { \
153 .state = RTE_TIMER_STOP, \
154 .owner = RTE_TIMER_NO_OWNER, \
160 * Initialize the timer library.
162 * Initializes internal variables (list, locks and so on) for the RTE
165 void rte_timer_subsystem_init(void);
168 * Initialize a timer handle.
170 * The rte_timer_init() function initializes the timer handle *tim*
171 * for use. No operations can be performed on a timer before it is
175 * The timer to initialize.
177 void rte_timer_init(struct rte_timer *tim);
180 * Reset and start the timer associated with the timer handle.
182 * The rte_timer_reset() function resets and starts the timer
183 * associated with the timer handle *tim*. When the timer expires after
184 * *ticks* HPET cycles, the function specified by *fct* will be called
185 * with the argument *arg* on core *tim_lcore*.
187 * If the timer associated with the timer handle is already running
188 * (in the RUNNING state), the function will fail. The user has to check
189 * the return value of the function to see if there is a chance that the
190 * timer is in the RUNNING state.
192 * If the timer is being configured on another core (the CONFIG state),
195 * If the timer is pending or stopped, it will be rescheduled with the
201 * The number of cycles (see rte_get_hpet_hz()) before the callback
202 * function is called.
204 * The type can be either:
205 * - PERIODICAL: The timer is automatically reloaded after execution
206 * (returns to the PENDING state)
207 * - SINGLE: The timer is one-shot, that is, the timer goes to a
208 * STOPPED state after execution.
210 * The ID of the lcore where the timer callback function has to be
211 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
212 * launch it on a different core for each call (round-robin).
214 * The callback function of the timer.
216 * The user argument of the callback function.
218 * - 0: Success; the timer is scheduled.
219 * - (-1): Timer is in the RUNNING or CONFIG state.
221 int rte_timer_reset(struct rte_timer *tim, uint64_t ticks,
222 enum rte_timer_type type, unsigned tim_lcore,
223 rte_timer_cb_t fct, void *arg);
227 * Loop until rte_timer_reset() succeeds.
229 * Reset and start the timer associated with the timer handle. Always
230 * succeed. See rte_timer_reset() for details.
235 * The number of cycles (see rte_get_hpet_hz()) before the callback
236 * function is called.
238 * The type can be either:
239 * - PERIODICAL: The timer is automatically reloaded after execution
240 * (returns to the PENDING state)
241 * - SINGLE: The timer is one-shot, that is, the timer goes to a
242 * STOPPED state after execution.
244 * The ID of the lcore where the timer callback function has to be
245 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
246 * launch it on a different core for each call (round-robin).
248 * The callback function of the timer.
250 * The user argument of the callback function.
253 rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks,
254 enum rte_timer_type type, unsigned tim_lcore,
255 rte_timer_cb_t fct, void *arg);
260 * The rte_timer_stop() function stops the timer associated with the
261 * timer handle *tim*. It may fail if the timer is currently running or
264 * If the timer is pending or stopped (for instance, already expired),
265 * the function will succeed. The timer handle tim must have been
266 * initialized using rte_timer_init(), otherwise, undefined behavior
269 * This function can be called safely from a timer callback. If it
270 * succeeds, the timer is not referenced anymore by the timer library
271 * and the timer structure can be freed (even in the callback
277 * - 0: Success; the timer is stopped.
278 * - (-1): The timer is in the RUNNING or CONFIG state.
280 int rte_timer_stop(struct rte_timer *tim);
284 * Loop until rte_timer_stop() succeeds.
286 * After a call to this function, the timer identified by *tim* is
287 * stopped. See rte_timer_stop() for details.
292 void rte_timer_stop_sync(struct rte_timer *tim);
295 * Test if a timer is pending.
297 * The rte_timer_pending() function tests the PENDING status
298 * of the timer handle *tim*. A PENDING timer is one that has been
299 * scheduled and whose function has not yet been called.
304 * - 0: The timer is not pending.
305 * - 1: The timer is pending.
307 int rte_timer_pending(struct rte_timer *tim);
310 * Manage the timer list and execute callback functions.
312 * This function must be called periodically from all cores
313 * main_loop(). It browses the list of pending timers and runs all
314 * timers that are expired.
316 * The precision of the timer depends on the call frequency of this
317 * function. However, the more often the function is called, the more
318 * CPU resources it will use.
320 void rte_timer_manage(void);
323 * Dump statistics about timers.
325 void rte_timer_dump_stats(void);
331 #endif /* _RTE_TIMER_H_ */