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 * Allocate a timer data instance in shared memory to track a set of pending 137 * timer lists. 138 * 139 * @param id_ptr 140 * Pointer to variable into which to write the identifier of the allocated 141 * timer data instance. 142 * 143 * @return 144 * - 0: Success 145 * - -ENOSPC: maximum number of timer data instances already allocated 146 */ 147 int rte_timer_data_alloc(uint32_t *id_ptr); 148 149 /** 150 * Deallocate a timer data instance. 151 * 152 * @param id 153 * Identifier of the timer data instance to deallocate. 154 * 155 * @return 156 * - 0: Success 157 * - -EINVAL: invalid timer data instance identifier 158 */ 159 int rte_timer_data_dealloc(uint32_t id); 160 161 /** 162 * Initialize the timer library. 163 * 164 * Initializes internal variables (list, locks and so on) for the RTE 165 * timer library. 166 * 167 * @note 168 * This function must be called in every process before using the library. 169 * 170 * @return 171 * - 0: Success 172 * - -ENOMEM: Unable to allocate memory needed to initialize timer 173 * subsystem 174 * - -EALREADY: timer subsystem was already initialized. Not an error. 175 */ 176 int rte_timer_subsystem_init(void); 177 178 /** 179 * Free timer subsystem resources. 180 */ 181 void rte_timer_subsystem_finalize(void); 182 183 /** 184 * Initialize a timer handle. 185 * 186 * The rte_timer_init() function initializes the timer handle *tim* 187 * for use. No operations can be performed on a timer before it is 188 * initialized. 189 * 190 * @param tim 191 * The timer to initialize. 192 */ 193 void rte_timer_init(struct rte_timer *tim); 194 195 /** 196 * Reset and start the timer associated with the timer handle. 197 * 198 * The rte_timer_reset() function resets and starts the timer 199 * associated with the timer handle *tim*. When the timer expires after 200 * *ticks* HPET cycles, the function specified by *fct* will be called 201 * with the argument *arg* on core *tim_lcore*. 202 * 203 * If the timer associated with the timer handle is already running 204 * (in the RUNNING state), the function will fail. The user has to check 205 * the return value of the function to see if there is a chance that the 206 * timer is in the RUNNING state. 207 * 208 * If the timer is being configured on another core (the CONFIG state), 209 * it will also fail. 210 * 211 * If the timer is pending or stopped, it will be rescheduled with the 212 * new parameters. 213 * 214 * @param tim 215 * The timer handle. 216 * @param ticks 217 * The number of cycles (see rte_get_hpet_hz()) before the callback 218 * function is called. 219 * @param type 220 * The type can be either: 221 * - PERIODICAL: The timer is automatically reloaded after execution 222 * (returns to the PENDING state) 223 * - SINGLE: The timer is one-shot, that is, the timer goes to a 224 * STOPPED state after execution. 225 * @param tim_lcore 226 * The ID of the lcore where the timer callback function has to be 227 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will 228 * launch it on a different core for each call (round-robin). 229 * @param fct 230 * The callback function of the timer. 231 * @param arg 232 * The user argument of the callback function. 233 * @return 234 * - 0: Success; the timer is scheduled. 235 * - (-1): Timer is in the RUNNING or CONFIG state. 236 */ 237 int rte_timer_reset(struct rte_timer *tim, uint64_t ticks, 238 enum rte_timer_type type, unsigned tim_lcore, 239 rte_timer_cb_t fct, void *arg); 240 241 /** 242 * Loop until rte_timer_reset() succeeds. 243 * 244 * Reset and start the timer associated with the timer handle. Always 245 * succeed. See rte_timer_reset() for details. 246 * 247 * @param tim 248 * The timer handle. 249 * @param ticks 250 * The number of cycles (see rte_get_hpet_hz()) before the callback 251 * function is called. 252 * @param type 253 * The type can be either: 254 * - PERIODICAL: The timer is automatically reloaded after execution 255 * (returns to the PENDING state) 256 * - SINGLE: The timer is one-shot, that is, the timer goes to a 257 * STOPPED state after execution. 258 * @param tim_lcore 259 * The ID of the lcore where the timer callback function has to be 260 * executed. If tim_lcore is LCORE_ID_ANY, the timer library will 261 * launch it on a different core for each call (round-robin). 262 * @param fct 263 * The callback function of the timer. 264 * @param arg 265 * The user argument of the callback function. 266 * 267 * @note 268 * This API should not be called inside a timer's callback function to 269 * reset another timer; doing so could hang in certain scenarios. Instead, 270 * the rte_timer_reset() API can be called directly and its return code 271 * can be checked for success or failure. 272 */ 273 void 274 rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks, 275 enum rte_timer_type type, unsigned tim_lcore, 276 rte_timer_cb_t fct, void *arg); 277 278 /** 279 * Stop a timer. 280 * 281 * The rte_timer_stop() function stops the timer associated with the 282 * timer handle *tim*. It may fail if the timer is currently running or 283 * being configured. 284 * 285 * If the timer is pending or stopped (for instance, already expired), 286 * the function will succeed. The timer handle tim must have been 287 * initialized using rte_timer_init(), otherwise, undefined behavior 288 * will occur. 289 * 290 * This function can be called safely from a timer callback. If it 291 * succeeds, the timer is not referenced anymore by the timer library 292 * and the timer structure can be freed (even in the callback 293 * function). 294 * 295 * @param tim 296 * The timer handle. 297 * @return 298 * - 0: Success; the timer is stopped. 299 * - (-1): The timer is in the RUNNING or CONFIG state. 300 */ 301 int rte_timer_stop(struct rte_timer *tim); 302 303 /** 304 * Loop until rte_timer_stop() succeeds. 305 * 306 * After a call to this function, the timer identified by *tim* is 307 * stopped. See rte_timer_stop() for details. 308 * 309 * @param tim 310 * The timer handle. 311 * 312 * @note 313 * This API should not be called inside a timer's callback function to 314 * stop another timer; doing so could hang in certain scenarios. Instead, the 315 * rte_timer_stop() API can be called directly and its return code can 316 * be checked for success or failure. 317 */ 318 void rte_timer_stop_sync(struct rte_timer *tim); 319 320 /** 321 * Test if a timer is pending. 322 * 323 * The rte_timer_pending() function tests the PENDING status 324 * of the timer handle *tim*. A PENDING timer is one that has been 325 * scheduled and whose function has not yet been called. 326 * 327 * @param tim 328 * The timer handle. 329 * @return 330 * - 0: The timer is not pending. 331 * - 1: The timer is pending. 332 */ 333 int rte_timer_pending(struct rte_timer *tim); 334 335 /** 336 * @warning 337 * @b EXPERIMENTAL: this API may change without prior notice 338 * 339 * Time until the next timer on the current lcore 340 * This function gives the ticks until the next timer will be active. 341 * 342 * @return 343 * - -EINVAL: invalid timer data instance identifier 344 * - -ENOENT: no timer pending 345 * - 0: a timer is pending and will run at next rte_timer_manage() 346 * - >0: ticks until the next timer is ready 347 */ 348 __rte_experimental 349 int64_t rte_timer_next_ticks(void); 350 351 /** 352 * Manage the timer list and execute callback functions. 353 * 354 * This function must be called periodically from EAL lcores 355 * main_loop(). It browses the list of pending timers and runs all 356 * timers that are expired. 357 * 358 * The precision of the timer depends on the call frequency of this 359 * function. However, the more often the function is called, the more 360 * CPU resources it will use. 361 * 362 * @return 363 * - 0: Success 364 * - -EINVAL: timer subsystem not yet initialized 365 */ 366 int rte_timer_manage(void); 367 368 /** 369 * Dump statistics about timers. 370 * 371 * @param f 372 * A pointer to a file for output 373 * @return 374 * - 0: Success 375 * - -EINVAL: timer subsystem not yet initialized 376 */ 377 int rte_timer_dump_stats(FILE *f); 378 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 int 415 rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim, 416 uint64_t ticks, enum rte_timer_type type, 417 unsigned int tim_lcore, rte_timer_cb_t fct, void *arg); 418 419 /** 420 * This function is the same as rte_timer_stop(), except that it allows a 421 * caller to specify the rte_timer_data instance containing the list from which 422 * this timer should be removed. 423 * 424 * @see rte_timer_stop() 425 * 426 * @param timer_data_id 427 * An identifier indicating which instance of timer data should be used for 428 * this operation. 429 * @param tim 430 * The timer handle. 431 * @return 432 * - 0: Success; the timer is stopped. 433 * - (-1): The timer is in the RUNNING or CONFIG state. 434 * - -EINVAL: invalid timer_data_id 435 */ 436 int 437 rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim); 438 439 /** 440 * Callback function type for rte_timer_alt_manage(). 441 */ 442 typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim); 443 444 /** 445 * Manage a set of timer lists and execute the specified callback function for 446 * all expired timers. This function is similar to rte_timer_manage(), except 447 * that it allows a caller to specify the timer_data instance that should 448 * be operated on, as well as a set of lcore IDs identifying which timer lists 449 * should be processed. Callback functions of individual timers are ignored. 450 * 451 * @see rte_timer_manage() 452 * 453 * @param timer_data_id 454 * An identifier indicating which instance of timer data should be used for 455 * this operation. 456 * @param poll_lcores 457 * An array of lcore ids identifying the timer lists that should be processed. 458 * NULL is allowed - if NULL, the timer list corresponding to the lcore 459 * calling this routine is processed (same as rte_timer_manage()). 460 * @param n_poll_lcores 461 * The size of the poll_lcores array. If 'poll_lcores' is NULL, this parameter 462 * is ignored. 463 * @param f 464 * The callback function which should be called for all expired timers. 465 * @return 466 * - 0: success 467 * - -EINVAL: invalid timer_data_id 468 */ 469 int 470 rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores, 471 int n_poll_lcores, rte_timer_alt_manage_cb_t f); 472 473 /** 474 * Callback function type for rte_timer_stop_all(). 475 */ 476 typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg); 477 478 /** 479 * Walk the pending timer lists for the specified lcore IDs, and for each timer 480 * that is encountered, stop it and call the specified callback function to 481 * process it further. 482 * 483 * @param timer_data_id 484 * An identifier indicating which instance of timer data should be used for 485 * this operation. 486 * @param walk_lcores 487 * An array of lcore ids identifying the timer lists that should be processed. 488 * @param nb_walk_lcores 489 * The size of the walk_lcores array. 490 * @param f 491 * The callback function which should be called for each timers. Can be NULL. 492 * @param f_arg 493 * An arbitrary argument that will be passed to f, if it is called. 494 * @return 495 * - 0: success 496 * - EINVAL: invalid timer_data_id 497 */ 498 int 499 rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores, 500 int nb_walk_lcores, rte_timer_stop_all_cb_t f, void *f_arg); 501 502 /** 503 * This function is the same as rte_timer_dump_stats(), except that it allows 504 * the caller to specify the rte_timer_data instance that should be used. 505 * 506 * @see rte_timer_dump_stats() 507 * 508 * @param timer_data_id 509 * An identifier indicating which instance of timer data should be used for 510 * this operation. 511 * @param f 512 * A pointer to a file for output 513 * @return 514 * - 0: success 515 * - -EINVAL: invalid timer_data_id 516 */ 517 int 518 rte_timer_alt_dump_stats(uint32_t timer_data_id, FILE *f); 519 520 #ifdef __cplusplus 521 } 522 #endif 523 524 #endif /* _RTE_TIMER_H_ */ 525