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