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
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 #define RTE_TIMER_STOP    0 /**< State: timer is stopped. */
  47 #define RTE_TIMER_PENDING 1 /**< State: timer is scheduled. */
  48 #define RTE_TIMER_RUNNING 2 /**< State: timer function is running. */
  49 #define RTE_TIMER_CONFIG  3 /**< State: timer is being configured. */
  50
  51 #define RTE_TIMER_NO_OWNER -2 /**< Timer has no owner. */
  52
  53 /**
  54  * Timer type: Periodic or single (one-shot).
  55  */
  56 enum rte_timer_type {
  57         SINGLE,
  58         PERIODICAL
  59 };
  60
  61 /**
  62  * Timer status: A union of the state (stopped, pending, running,
  63  * config) and an owner (the id of the lcore that owns the timer).
  64  */
  65 union rte_timer_status {
  66         RTE_STD_C11
  67         struct {
  68                 uint16_t state;  /**< Stop, pending, running, config. */
  69                 int16_t owner;   /**< The lcore that owns the timer. */
  70         };
  71         uint32_t u32;            /**< To atomic-set status + owner. */
  72 };
  73
  74 #ifdef RTE_LIBRTE_TIMER_DEBUG
  75 /**
  76  * A structure that stores the timer statistics (per-lcore).
  77  */
  78 struct rte_timer_debug_stats {
  79         uint64_t reset;   /**< Number of success calls to rte_timer_reset(). */
  80         uint64_t stop;    /**< Number of success calls to rte_timer_stop(). */
  81         uint64_t manage;  /**< Number of calls to rte_timer_manage(). */
  82         uint64_t pending; /**< Number of pending/running timers. */
  83 };
  84 #endif
  85
  86 struct rte_timer;
  87
  88 /**
  89  * Callback function type for timer expiry.
  90  */
  91 typedef void (*rte_timer_cb_t)(struct rte_timer *, void *);
  92
  93 #define MAX_SKIPLIST_DEPTH 10
  94
  95 /**
  96  * A structure describing a timer in RTE.
  97  */
  98 struct rte_timer
  99 {
 100         uint64_t expire;       /**< Time when timer expire. */
 101         struct rte_timer *sl_next[MAX_SKIPLIST_DEPTH];
 102         volatile union rte_timer_status status; /**< Status of timer. */
 103         uint64_t period;       /**< Period of timer (0 if not periodic). */
 104         rte_timer_cb_t f;      /**< Callback function. */
 105         void *arg;             /**< Argument to callback function. */
 106 };
 107
 108
 109 #ifdef __cplusplus
 110 /**
 111  * A C++ static initializer for a timer structure.
 112  */
 113 #define RTE_TIMER_INITIALIZER {             \
 114         0,                                      \
 115         {NULL},                                 \
 116         {{RTE_TIMER_STOP, RTE_TIMER_NO_OWNER}}, \
 117         0,                                      \
 118         NULL,                                   \
 119         NULL,                                   \
 120         }
 121 #else
 122 /**
 123  * A static initializer for a timer structure.
 124  */
 125 #define RTE_TIMER_INITIALIZER {                      \
 126                 .status = {{                         \
 127                         .state = RTE_TIMER_STOP,     \
 128                         .owner = RTE_TIMER_NO_OWNER, \
 129                 }},                                  \
 130         }
 131 #endif
 132
 133 /**
 134  * Initialize the timer library.
 135  *
 136  * Initializes internal variables (list, locks and so on) for the RTE
 137  * timer library.
 138  */
 139 void rte_timer_subsystem_init(void);
 140
 141 /**
 142  * Initialize a timer handle.
 143  *
 144  * The rte_timer_init() function initializes the timer handle *tim*
 145  * for use. No operations can be performed on a timer before it is
 146  * initialized.
 147  *
 148  * @param tim
 149  *   The timer to initialize.
 150  */
 151 void rte_timer_init(struct rte_timer *tim);
 152
 153 /**
 154  * Reset and start the timer associated with the timer handle.
 155  *
 156  * The rte_timer_reset() function resets and starts the timer
 157  * associated with the timer handle *tim*. When the timer expires after
 158  * *ticks* HPET cycles, the function specified by *fct* will be called
 159  * with the argument *arg* on core *tim_lcore*.
 160  *
 161  * If the timer associated with the timer handle is already running
 162  * (in the RUNNING state), the function will fail. The user has to check
 163  * the return value of the function to see if there is a chance that the
 164  * timer is in the RUNNING state.
 165  *
 166  * If the timer is being configured on another core (the CONFIG state),
 167  * it will also fail.
 168  *
 169  * If the timer is pending or stopped, it will be rescheduled with the
 170  * new parameters.
 171  *
 172  * @param tim
 173  *   The timer handle.
 174  * @param ticks
 175  *   The number of cycles (see rte_get_hpet_hz()) before the callback
 176  *   function is called.
 177  * @param type
 178  *   The type can be either:
 179  *   - PERIODICAL: The timer is automatically reloaded after execution
 180  *     (returns to the PENDING state)
 181  *   - SINGLE: The timer is one-shot, that is, the timer goes to a
 182  *     STOPPED state after execution.
 183  * @param tim_lcore
 184  *   The ID of the lcore where the timer callback function has to be
 185  *   executed. If tim_lcore is LCORE_ID_ANY, the timer library will
 186  *   launch it on a different core for each call (round-robin).
 187  * @param fct
 188  *   The callback function of the timer.
 189  * @param arg
 190  *   The user argument of the callback function.
 191  * @return
 192  *   - 0: Success; the timer is scheduled.
 193  *   - (-1): Timer is in the RUNNING or CONFIG state.
 194  */
 195 int rte_timer_reset(struct rte_timer *tim, uint64_t ticks,
 196                     enum rte_timer_type type, unsigned tim_lcore,
 197                     rte_timer_cb_t fct, void *arg);
 198
 199
 200 /**
 201  * Loop until rte_timer_reset() succeeds.
 202  *
 203  * Reset and start the timer associated with the timer handle. Always
 204  * succeed. See rte_timer_reset() for details.
 205  *
 206  * @param tim
 207  *   The timer handle.
 208  * @param ticks
 209  *   The number of cycles (see rte_get_hpet_hz()) before the callback
 210  *   function is called.
 211  * @param type
 212  *   The type can be either:
 213  *   - PERIODICAL: The timer is automatically reloaded after execution
 214  *     (returns to the PENDING state)
 215  *   - SINGLE: The timer is one-shot, that is, the timer goes to a
 216  *     STOPPED state after execution.
 217  * @param tim_lcore
 218  *   The ID of the lcore where the timer callback function has to be
 219  *   executed. If tim_lcore is LCORE_ID_ANY, the timer library will
 220  *   launch it on a different core for each call (round-robin).
 221  * @param fct
 222  *   The callback function of the timer.
 223  * @param arg
 224  *   The user argument of the callback function.
 225  */
 226 void
 227 rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks,
 228                      enum rte_timer_type type, unsigned tim_lcore,
 229                      rte_timer_cb_t fct, void *arg);
 230
 231 /**
 232  * Stop a timer.
 233  *
 234  * The rte_timer_stop() function stops the timer associated with the
 235  * timer handle *tim*. It may fail if the timer is currently running or
 236  * being configured.
 237  *
 238  * If the timer is pending or stopped (for instance, already expired),
 239  * the function will succeed. The timer handle tim must have been
 240  * initialized using rte_timer_init(), otherwise, undefined behavior
 241  * will occur.
 242  *
 243  * This function can be called safely from a timer callback. If it
 244  * succeeds, the timer is not referenced anymore by the timer library
 245  * and the timer structure can be freed (even in the callback
 246  * function).
 247  *
 248  * @param tim
 249  *   The timer handle.
 250  * @return
 251  *   - 0: Success; the timer is stopped.
 252  *   - (-1): The timer is in the RUNNING or CONFIG state.
 253  */
 254 int rte_timer_stop(struct rte_timer *tim);
 255
 256
 257 /**
 258  * Loop until rte_timer_stop() succeeds.
 259  *
 260  * After a call to this function, the timer identified by *tim* is
 261  * stopped. See rte_timer_stop() for details.
 262  *
 263  * @param tim
 264  *   The timer handle.
 265  */
 266 void rte_timer_stop_sync(struct rte_timer *tim);
 267
 268 /**
 269  * Test if a timer is pending.
 270  *
 271  * The rte_timer_pending() function tests the PENDING status
 272  * of the timer handle *tim*. A PENDING timer is one that has been
 273  * scheduled and whose function has not yet been called.
 274  *
 275  * @param tim
 276  *   The timer handle.
 277  * @return
 278  *   - 0: The timer is not pending.
 279  *   - 1: The timer is pending.
 280  */
 281 int rte_timer_pending(struct rte_timer *tim);
 282
 283 /**
 284  * Manage the timer list and execute callback functions.
 285  *
 286  * This function must be called periodically from EAL lcores
 287  * main_loop(). It browses the list of pending timers and runs all
 288  * timers that are expired.
 289  *
 290  * The precision of the timer depends on the call frequency of this
 291  * function. However, the more often the function is called, the more
 292  * CPU resources it will use.
 293  */
 294 void rte_timer_manage(void);
 295
 296 /**
 297  * Dump statistics about timers.
 298  *
 299  * @param f
 300  *   A pointer to a file for output
 301  */
 302 void rte_timer_dump_stats(FILE *f);
 303
 304 #ifdef __cplusplus
 305 }
 306 #endif
 307
 308 #endif /* _RTE_TIMER_H_ */