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_ */