2 * Copyright (c) <2010>, Intel Corporation
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
12 * - Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in
14 * 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
24 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
27 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
30 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
32 * OF THE POSSIBILITY OF SUCH DAMAGE.
39 //#define CALLOUT_DEBUG
45 * This library provides a timer service to Aversive. Instead of beeing
46 * called from interrupt (like the scheduler lib does), these kind of timers
47 * are not preemptive and should (for instance) be called from a main-loop.
49 * - Timers can be periodic or single (one-shot).
51 * This library provides an interface to add, delete and restart a
52 * timer. The API is based on the BSD callout(9) with few
59 * A structure that stores the timer statistics (per-lcore).
61 struct callout_debug_stats {
62 uint16_t reset; /**< Number of success calls to callout_reset(). */
63 uint16_t stop; /**< Number of success calls to callout_stop(). */
64 uint16_t manage; /**< Number of calls to callout_manage(). */
65 uint16_t pending; /**< Number of pending timers. */
66 uint16_t running; /**< Number of running timers. */
68 extern struct callout_debug_stats callout_debug_stats;
72 struct callout_manager;
75 * Callback function for the timer.
77 typedef void (callout_cb_t)(struct callout_manager *, struct callout *, void *);
80 * A structure describing a timer in RTE.
84 TAILQ_ENTRY(callout) next; /**< Next and prev in list. */
86 uint8_t periodical: 1; /**< timer is periodical or not */
87 uint8_t scheduled: 1; /**< true if timer is scheduled */
88 uint8_t running: 1; /**< true if cb func is beeing executed */
91 uint16_t period; /**< Period of timer (0 if not periodic). */
92 uint16_t expire; /**< Time when timer expire. */
93 callout_cb_t *f; /**< Callback function. */
94 void *arg; /**< Argument to callback function. */
100 TAILQ_HEAD(callout_list, callout);
103 * A static initializer for a timer structure.
105 #define CALLOUT_INITIALIZER { }
108 * Function used by a callout manager to get a time reference
110 typedef uint16_t (get_time_t)(void);
113 * A instance of callout manager (it is possible to have several)
115 struct callout_manager {
116 get_time_t *get_time;
120 struct callout_list pending_list;
123 struct callout_debug_stats stats;
128 * Initialize a callout manager
131 * The uninitialized callout manager structure.
133 * Pointer to a function that returns a time reference (unsigned 16 bits)
136 * - negative on error
139 callout_manager_init(struct callout_manager *cm, get_time_t *get_time);
142 * Initialize a timer handle.
144 * The callout_init() function initializes the timer handle tim
145 * for use. No operations can be performed on the timer before it is
149 * The timer to initialize.
151 void callout_init(struct callout *tim);
154 * Timer type: Periodic or single (one-shot).
162 * Reset and start the timer associated with the timer handle.
164 * The callout_reset() function resets and starts the timer
165 * associated with the timer handle tim. When the timer expires after
166 * ticks/hz seconds, the function specified by *fct* will be called
167 * with the argument *arg* on core *tim_lcore*.
169 * If the timer associated with the timer handle is already running
170 * (in the RUNNING state), the function will fail. The user has to check
171 * the return value of the function to see if there is a chance that the
172 * timer is in the RUNNING state.
174 * If the timer is being configured on another core (the CONFIG state),
177 * If the timer is pending or stopped, it will be rescheduled with the
183 * The number of cycles (see rte_get_hpet_hz()) before the callback
184 * function is called.
186 * The type can be either:
187 * - PERIODICAL: The timer is automatically reloaded after execution
188 * (returns to the PENDING state)
189 * - SINGLE: The timer is one-shot, that is, the timer goes to a
190 * STOPPED state after execution.
192 * The ID of the lcore where the timer callback function has to be
193 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will
194 * launch it on a different core for each call (round-robin).
196 * The callback function of the timer.
198 * The user argument of the callback function.
200 * - 0: Success; the timer is scheduled.
201 * - (-1): Timer is in the RUNNING or CONFIG state.
203 int callout_reset(struct callout_manager *cm, struct callout *tim,
204 uint16_t ticks, enum callout_type type,
205 callout_cb_t fct, void *arg);
211 * The callout_stop() function stops the timer associated with the
212 * timer handle tim. It may fail if the timer is currently running or
215 * If the timer is pending or stopped (for instance, already expired),
216 * the function will succeed. The timer handle tim must have been
217 * initialized using callout_init(), otherwise, undefined behavior
220 * This function can be called safely from a timer callback. If it
221 * succeeds, the timer is not referenced anymore by the timer library
222 * and the timer structure can be freed (even in the callback
228 void callout_stop(struct callout_manager *cm, struct callout *tim);
232 * Test if a timer is pending.
234 * The callout_pending() function tests the PENDING status
235 * of the timer handle tim. A PENDING timer is one that has been
236 * scheduled and whose function has not yet been called.
241 * - 0: The timer is not pending.
242 * - 1: The timer is pending.
244 int callout_pending(struct callout *tim);
247 * Manage the timer list and execute callback functions.
249 * This function must be called periodically from all cores
250 * main_loop(). It browses the list of pending timers and runs all
251 * timers that are expired.
253 * The precision of the timer depends on the call frequency of this
254 * function. However, the more often the function is called, the more
255 * it will use CPU resources.
257 void callout_manage(struct callout_manager *cm);
260 * Dump statistics about timers.
262 void callout_dump_stats(struct callout_manager *cm);
264 #endif /* _CALLOUT_H_ */