event/octeontx2: support xstats
[dpdk.git] / lib / librte_timer / rte_timer.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4
5 #ifndef _RTE_TIMER_H_
6 #define _RTE_TIMER_H_
7
8 /**
9  * @file
10  RTE Timer
11  *
12  * This library provides a timer service to RTE Data Plane execution
13  * units that allows the execution of callback functions asynchronously.
14  *
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.
23  *
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]
28  *
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
31  * differences.
32  *
33  * See the RTE architecture documentation for more information about the
34  * design of this library.
35  */
36
37 #include <stdio.h>
38 #include <stdint.h>
39 #include <stddef.h>
40 #include <rte_common.h>
41 #include <rte_config.h>
42 #include <rte_spinlock.h>
43
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47
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. */
52
53 #define RTE_TIMER_NO_OWNER -2 /**< Timer has no owner. */
54
55 /**
56  * Timer type: Periodic or single (one-shot).
57  */
58 enum rte_timer_type {
59         SINGLE,
60         PERIODICAL
61 };
62
63 /**
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).
66  */
67 union rte_timer_status {
68         RTE_STD_C11
69         struct {
70                 uint16_t state;  /**< Stop, pending, running, config. */
71                 int16_t owner;   /**< The lcore that owns the timer. */
72         };
73         uint32_t u32;            /**< To atomic-set status + owner. */
74 };
75
76 #ifdef RTE_LIBRTE_TIMER_DEBUG
77 /**
78  * A structure that stores the timer statistics (per-lcore).
79  */
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. */
85 };
86 #endif
87
88 struct rte_timer;
89
90 /**
91  * Callback function type for timer expiry.
92  */
93 typedef void (*rte_timer_cb_t)(struct rte_timer *, void *);
94
95 #define MAX_SKIPLIST_DEPTH 10
96
97 /**
98  * A structure describing a timer in RTE.
99  */
100 struct rte_timer
101 {
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. */
108 };
109
110
111 #ifdef __cplusplus
112 /**
113  * A C++ static initializer for a timer structure.
114  */
115 #define RTE_TIMER_INITIALIZER {             \
116         0,                                      \
117         {NULL},                                 \
118         {{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \
119         0,                                      \
120         NULL,                                   \
121         NULL,                                   \
122         }
123 #else
124 /**
125  * A static initializer for a timer structure.
126  */
127 #define RTE_TIMER_INITIALIZER {                      \
128                 .status = {{                         \
129                         .state = RTE_TIMER_STOP,     \
130                         .owner = RTE_TIMER_NO_OWNER, \
131                 }},                                  \
132         }
133 #endif
134
135 /**
136  * @warning
137  * @b EXPERIMENTAL: this API may change without prior notice
138  *
139  * Allocate a timer data instance in shared memory to track a set of pending
140  * timer lists.
141  *
142  * @param id_ptr
143  *   Pointer to variable into which to write the identifier of the allocated
144  *   timer data instance.
145  *
146  * @return
147  *   - 0: Success
148  *   - -ENOSPC: maximum number of timer data instances already allocated
149  */
150 __rte_experimental
151 int rte_timer_data_alloc(uint32_t *id_ptr);
152
153 /**
154  * @warning
155  * @b EXPERIMENTAL: this API may change without prior notice
156  *
157  * Deallocate a timer data instance.
158  *
159  * @param id
160  *   Identifier of the timer data instance to deallocate.
161  *
162  * @return
163  *   - 0: Success
164  *   - -EINVAL: invalid timer data instance identifier
165  */
166 __rte_experimental
167 int rte_timer_data_dealloc(uint32_t id);
168
169 /**
170  * Initialize the timer library.
171  *
172  * Initializes internal variables (list, locks and so on) for the RTE
173  * timer library.
174  *
175  * @return
176  *   - 0: Success
177  *   - -EEXIST: Returned in secondary process when primary process has not
178  *      yet initialized the timer subsystem
179  *   - -ENOMEM: Unable to allocate memory needed to initialize timer
180  *      subsystem
181  */
182 int rte_timer_subsystem_init(void);
183 int rte_timer_subsystem_init_v1905(void);
184 void rte_timer_subsystem_init_v20(void);
185
186 /**
187  * @warning
188  * @b EXPERIMENTAL: this API may change without prior notice
189  *
190  * Free timer subsystem resources.
191  */
192 __rte_experimental
193 void rte_timer_subsystem_finalize(void);
194
195 /**
196  * Initialize a timer handle.
197  *
198  * The rte_timer_init() function initializes the timer handle *tim*
199  * for use. No operations can be performed on a timer before it is
200  * initialized.
201  *
202  * @param tim
203  *   The timer to initialize.
204  */
205 void rte_timer_init(struct rte_timer *tim);
206
207 /**
208  * Reset and start the timer associated with the timer handle.
209  *
210  * The rte_timer_reset() function resets and starts the timer
211  * associated with the timer handle *tim*. When the timer expires after
212  * *ticks* HPET cycles, the function specified by *fct* will be called
213  * with the argument *arg* on core *tim_lcore*.
214  *
215  * If the timer associated with the timer handle is already running
216  * (in the RUNNING state), the function will fail. The user has to check
217  * the return value of the function to see if there is a chance that the
218  * timer is in the RUNNING state.
219  *
220  * If the timer is being configured on another core (the CONFIG state),
221  * it will also fail.
222  *
223  * If the timer is pending or stopped, it will be rescheduled with the
224  * new parameters.
225  *
226  * @param tim
227  *   The timer handle.
228  * @param ticks
229  *   The number of cycles (see rte_get_hpet_hz()) before the callback
230  *   function is called.
231  * @param type
232  *   The type can be either:
233  *   - PERIODICAL: The timer is automatically reloaded after execution
234  *     (returns to the PENDING state)
235  *   - SINGLE: The timer is one-shot, that is, the timer goes to a
236  *     STOPPED state after execution.
237  * @param tim_lcore
238  *   The ID of the lcore where the timer callback function has to be
239  *   executed. If tim_lcore is LCORE_ID_ANY, the timer library will
240  *   launch it on a different core for each call (round-robin).
241  * @param fct
242  *   The callback function of the timer.
243  * @param arg
244  *   The user argument of the callback function.
245  * @return
246  *   - 0: Success; the timer is scheduled.
247  *   - (-1): Timer is in the RUNNING or CONFIG state.
248  */
249 int rte_timer_reset(struct rte_timer *tim, uint64_t ticks,
250                     enum rte_timer_type type, unsigned tim_lcore,
251                     rte_timer_cb_t fct, void *arg);
252 int rte_timer_reset_v1905(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);
255 int rte_timer_reset_v20(struct rte_timer *tim, uint64_t ticks,
256                         enum rte_timer_type type, unsigned int tim_lcore,
257                         rte_timer_cb_t fct, void *arg);
258
259
260 /**
261  * Loop until rte_timer_reset() succeeds.
262  *
263  * Reset and start the timer associated with the timer handle. Always
264  * succeed. See rte_timer_reset() for details.
265  *
266  * @param tim
267  *   The timer handle.
268  * @param ticks
269  *   The number of cycles (see rte_get_hpet_hz()) before the callback
270  *   function is called.
271  * @param type
272  *   The type can be either:
273  *   - PERIODICAL: The timer is automatically reloaded after execution
274  *     (returns to the PENDING state)
275  *   - SINGLE: The timer is one-shot, that is, the timer goes to a
276  *     STOPPED state after execution.
277  * @param tim_lcore
278  *   The ID of the lcore where the timer callback function has to be
279  *   executed. If tim_lcore is LCORE_ID_ANY, the timer library will
280  *   launch it on a different core for each call (round-robin).
281  * @param fct
282  *   The callback function of the timer.
283  * @param arg
284  *   The user argument of the callback function.
285  */
286 void
287 rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks,
288                      enum rte_timer_type type, unsigned tim_lcore,
289                      rte_timer_cb_t fct, void *arg);
290
291 /**
292  * Stop a timer.
293  *
294  * The rte_timer_stop() function stops the timer associated with the
295  * timer handle *tim*. It may fail if the timer is currently running or
296  * being configured.
297  *
298  * If the timer is pending or stopped (for instance, already expired),
299  * the function will succeed. The timer handle tim must have been
300  * initialized using rte_timer_init(), otherwise, undefined behavior
301  * will occur.
302  *
303  * This function can be called safely from a timer callback. If it
304  * succeeds, the timer is not referenced anymore by the timer library
305  * and the timer structure can be freed (even in the callback
306  * function).
307  *
308  * @param tim
309  *   The timer handle.
310  * @return
311  *   - 0: Success; the timer is stopped.
312  *   - (-1): The timer is in the RUNNING or CONFIG state.
313  */
314 int rte_timer_stop(struct rte_timer *tim);
315 int rte_timer_stop_v1905(struct rte_timer *tim);
316 int rte_timer_stop_v20(struct rte_timer *tim);
317
318 /**
319  * Loop until rte_timer_stop() succeeds.
320  *
321  * After a call to this function, the timer identified by *tim* is
322  * stopped. See rte_timer_stop() for details.
323  *
324  * @param tim
325  *   The timer handle.
326  */
327 void rte_timer_stop_sync(struct rte_timer *tim);
328
329 /**
330  * Test if a timer is pending.
331  *
332  * The rte_timer_pending() function tests the PENDING status
333  * of the timer handle *tim*. A PENDING timer is one that has been
334  * scheduled and whose function has not yet been called.
335  *
336  * @param tim
337  *   The timer handle.
338  * @return
339  *   - 0: The timer is not pending.
340  *   - 1: The timer is pending.
341  */
342 int rte_timer_pending(struct rte_timer *tim);
343
344 /**
345  * Manage the timer list and execute callback functions.
346  *
347  * This function must be called periodically from EAL lcores
348  * main_loop(). It browses the list of pending timers and runs all
349  * timers that are expired.
350  *
351  * The precision of the timer depends on the call frequency of this
352  * function. However, the more often the function is called, the more
353  * CPU resources it will use.
354  *
355  * @return
356  *   - 0: Success
357  *   - -EINVAL: timer subsystem not yet initialized
358  */
359 int rte_timer_manage(void);
360 int rte_timer_manage_v1905(void);
361 void rte_timer_manage_v20(void);
362
363 /**
364  * Dump statistics about timers.
365  *
366  * @param f
367  *   A pointer to a file for output
368  * @return
369  *   - 0: Success
370  *   - -EINVAL: timer subsystem not yet initialized
371  */
372 int rte_timer_dump_stats(FILE *f);
373 int rte_timer_dump_stats_v1905(FILE *f);
374 void rte_timer_dump_stats_v20(FILE *f);
375
376 /**
377  * @warning
378  * @b EXPERIMENTAL: this API may change without prior notice
379  *
380  * This function is the same as rte_timer_reset(), except that it allows a
381  * caller to specify the rte_timer_data instance containing the list to which
382  * the timer should be added.
383  *
384  * @see rte_timer_reset()
385  *
386  * @param timer_data_id
387  *   An identifier indicating which instance of timer data should be used for
388  *   this operation.
389  * @param tim
390  *   The timer handle.
391  * @param ticks
392  *   The number of cycles (see rte_get_hpet_hz()) before the callback
393  *   function is called.
394  * @param type
395  *   The type can be either:
396  *   - PERIODICAL: The timer is automatically reloaded after execution
397  *     (returns to the PENDING state)
398  *   - SINGLE: The timer is one-shot, that is, the timer goes to a
399  *     STOPPED state after execution.
400  * @param tim_lcore
401  *   The ID of the lcore where the timer callback function has to be
402  *   executed. If tim_lcore is LCORE_ID_ANY, the timer library will
403  *   launch it on a different core for each call (round-robin).
404  * @param fct
405  *   The callback function of the timer. This parameter can be NULL if (and
406  *   only if) rte_timer_alt_manage() will be used to manage this timer.
407  * @param arg
408  *   The user argument of the callback function.
409  * @return
410  *   - 0: Success; the timer is scheduled.
411  *   - (-1): Timer is in the RUNNING or CONFIG state.
412  *   - -EINVAL: invalid timer_data_id
413  */
414 __rte_experimental
415 int
416 rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim,
417                     uint64_t ticks, enum rte_timer_type type,
418                     unsigned int tim_lcore, rte_timer_cb_t fct, void *arg);
419
420 /**
421  * @warning
422  * @b EXPERIMENTAL: this API may change without prior notice
423  *
424  * This function is the same as rte_timer_stop(), except that it allows a
425  * caller to specify the rte_timer_data instance containing the list from which
426  * this timer should be removed.
427  *
428  * @see rte_timer_stop()
429  *
430  * @param timer_data_id
431  *   An identifier indicating which instance of timer data should be used for
432  *   this operation.
433  * @param tim
434  *   The timer handle.
435  * @return
436  *   - 0: Success; the timer is stopped.
437  *   - (-1): The timer is in the RUNNING or CONFIG state.
438  *   - -EINVAL: invalid timer_data_id
439  */
440 __rte_experimental
441 int
442 rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim);
443
444 /**
445  * Callback function type for rte_timer_alt_manage().
446  */
447 typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim);
448
449 /**
450  * @warning
451  * @b EXPERIMENTAL: this API may change without prior notice
452  *
453  * Manage a set of timer lists and execute the specified callback function for
454  * all expired timers. This function is similar to rte_timer_manage(), except
455  * that it allows a caller to specify the timer_data instance that should
456  * be operated on, as well as a set of lcore IDs identifying which timer lists
457  * should be processed.  Callback functions of individual timers are ignored.
458  *
459  * @see rte_timer_manage()
460  *
461  * @param timer_data_id
462  *   An identifier indicating which instance of timer data should be used for
463  *   this operation.
464  * @param poll_lcores
465  *   An array of lcore ids identifying the timer lists that should be processed.
466  *   NULL is allowed - if NULL, the timer list corresponding to the lcore
467  *   calling this routine is processed (same as rte_timer_manage()).
468  * @param n_poll_lcores
469  *   The size of the poll_lcores array. If 'poll_lcores' is NULL, this parameter
470  *   is ignored.
471  * @param f
472  *   The callback function which should be called for all expired timers.
473  * @return
474  *   - 0: success
475  *   - -EINVAL: invalid timer_data_id
476  */
477 __rte_experimental
478 int
479 rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores,
480                      int n_poll_lcores, rte_timer_alt_manage_cb_t f);
481
482 /**
483  * Callback function type for rte_timer_stop_all().
484  */
485 typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg);
486
487 /**
488  * @warning
489  * @b EXPERIMENTAL: this API may change without prior notice
490  *
491  * Walk the pending timer lists for the specified lcore IDs, and for each timer
492  * that is encountered, stop it and call the specified callback function to
493  * process it further.
494  *
495  * @param timer_data_id
496  *   An identifier indicating which instance of timer data should be used for
497  *   this operation.
498  * @param walk_lcores
499  *   An array of lcore ids identifying the timer lists that should be processed.
500  * @param nb_walk_lcores
501  *   The size of the walk_lcores array.
502  * @param f
503  *   The callback function which should be called for each timers. Can be NULL.
504  * @param f_arg
505  *   An arbitrary argument that will be passed to f, if it is called.
506  * @return
507  *   - 0: success
508  *   - EINVAL: invalid timer_data_id
509  */
510 __rte_experimental
511 int
512 rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores,
513                    int nb_walk_lcores, rte_timer_stop_all_cb_t f, void *f_arg);
514
515 /**
516  * @warning
517  * @b EXPERIMENTAL: this API may change without prior notice
518  *
519  * This function is the same as rte_timer_dump_stats(), except that it allows
520  * the caller to specify the rte_timer_data instance that should be used.
521  *
522  * @see rte_timer_dump_stats()
523  *
524  * @param timer_data_id
525  *   An identifier indicating which instance of timer data should be used for
526  *   this operation.
527  * @param f
528  *   A pointer to a file for output
529  * @return
530  *   - 0: success
531  *   - -EINVAL: invalid timer_data_id
532  */
533 __rte_experimental
534 int
535 rte_timer_alt_dump_stats(uint32_t timer_data_id, FILE *f);
536
537 #ifdef __cplusplus
538 }
539 #endif
540
541 #endif /* _RTE_TIMER_H_ */