include/iprt/timer.h

   1 /** @file
   2  * IPRT - Timer.
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2024 Oracle and/or its affiliates.
   7  *
   8  * This file is part of VirtualBox base platform packages, as
   9  * available from https://www.virtualbox.org.
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation, in version 3 of the
  14  * License.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, see <https://www.gnu.org/licenses>.
  23  *
  24  * The contents of this file may alternatively be used under the terms
  25  * of the Common Development and Distribution License Version 1.0
  26  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
  27  * in the VirtualBox distribution, in which case the provisions of the
  28  * CDDL are applicable instead of those of the GPL.
  29  *
  30  * You may elect to license modified versions of this file under the
  31  * terms and conditions of either the GPL or the CDDL or both.
  32  *
  33  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
  34  */
  35
  36 #ifndef IPRT_INCLUDED_timer_h
  37 #define IPRT_INCLUDED_timer_h
  38 #ifndef RT_WITHOUT_PRAGMA_ONCE
  39 # pragma once
  40 #endif
  41
  42
  43 #include <iprt/cdefs.h>
  44 #include <iprt/types.h>
  45
  46
  47 RT_C_DECLS_BEGIN
  48
  49 /** @defgroup grp_rt_timer      RTTimer - Timer
  50  *
  51  * The IPRT timer API provides a simple abstraction of recurring and one-shot callback timers.
  52  *
  53  * Because of the great variation in the native APIs and the quality of
  54  * the service delivered by those native APIs, the timers are operated
  55  * on at best effort basis.
  56  *
  57  * All the ring-3 implementations are naturally at the mercy of the scheduler,
  58  * which means that the callback rate might vary quite a bit and we might skip
  59  * ticks. Many systems have a restriction that a process can only have one
  60  * timer. IPRT currently makes no efforts at multiplexing timers in those kind
  61  * of situations and will simply fail if you try to create more than one timer.
  62  *
  63  * Things are generally better in ring-0. The implementations will use interrupt
  64  * time callbacks wherever available, and if not, resort to a high priority
  65  * kernel thread.
  66  *
  67  * @ingroup grp_rt
  68  * @{
  69  */
  70
  71
  72 /** Timer handle. */
  73 typedef struct RTTIMER   *PRTTIMER;
  74
  75 /**
  76  * Timer callback function.
  77  *
  78  * The context this call is made in varies with different platforms and
  79  * kernel / user mode IPRT.
  80  *
  81  * In kernel mode a timer callback should not waste time, it shouldn't
  82  * waste stack and it should be prepared that some APIs might not work
  83  * correctly because of weird OS restrictions in this context that we
  84  * haven't discovered and avoided yet. Please fix those APIs so they
  85  * at least avoid panics and weird behaviour.
  86  *
  87  * @param   pTimer      Timer handle.
  88  * @param   pvUser      User argument.
  89  * @param   iTick       The current timer tick. This is always 1 on the first
  90  *                      callback after the timer was started. For omni timers
  91  *                      this will be 1 when a cpu comes back online.
  92  */
  93 typedef DECLCALLBACKTYPE(void, FNRTTIMER,(PRTTIMER pTimer, void *pvUser, uint64_t iTick));
  94 /** Pointer to FNRTTIMER() function. */
  95 typedef FNRTTIMER *PFNRTTIMER;
  96
  97
  98 /**
  99  * Create a recurring timer.
 100  *
 101  * @returns iprt status code.
 102  * @param   ppTimer             Where to store the timer handle.
 103  * @param   uMilliesInterval    Milliseconds between the timer ticks.
 104  *                              This is rounded up to the system granularity.
 105  * @param   pfnTimer            Callback function which shall be scheduled for execution
 106  *                              on every timer tick.
 107  * @param   pvUser              User argument for the callback.
 108  * @see     RTTimerCreateEx, RTTimerStart, RTTimerStop, RTTimerChangeInterval,
 109  *          RTTimerDestroy, RTTimerGetSystemGranularity
 110  */
 111 RTDECL(int) RTTimerCreate(PRTTIMER *ppTimer, unsigned uMilliesInterval, PFNRTTIMER pfnTimer, void *pvUser);
 112
 113 /**
 114  * Create a suspended timer.
 115  *
 116  * @returns iprt status code.
 117  * @retval  VERR_NOT_SUPPORTED if an unsupported flag was specfied.
 118  * @retval  VERR_CPU_NOT_FOUND if the specified CPU
 119  *
 120  * @param   ppTimer             Where to store the timer handle.
 121  * @param   u64NanoInterval     The interval between timer ticks specified in nanoseconds if it's
 122  *                              a recurring timer. This is rounded to the fit the system timer granularity.
 123  *                              For one shot timers, pass 0.
 124  * @param   fFlags              Timer flags.
 125  * @param   pfnTimer            Callback function which shall be scheduled for execution
 126  *                              on every timer tick.
 127  * @param   pvUser              User argument for the callback.
 128  * @see     RTTimerStart, RTTimerStop, RTTimerChangeInterval, RTTimerDestroy,
 129  *          RTTimerGetSystemGranularity, RTTimerCanDoHighResolution
 130  */
 131 RTDECL(int) RTTimerCreateEx(PRTTIMER *ppTimer, uint64_t u64NanoInterval, uint32_t fFlags, PFNRTTIMER pfnTimer, void *pvUser);
 132
 133 /** @name RTTimerCreateEx flags
 134  * @{ */
 135 /** Any CPU is fine. (Must be 0.) */
 136 #define RTTIMER_FLAGS_CPU_ANY       UINT32_C(0)
 137 /** One specific CPU */
 138 #define RTTIMER_FLAGS_CPU_SPECIFIC  RT_BIT(16)
 139 /** Omni timer, run on all online CPUs.
 140  * @remarks The timer callback isn't necessarily running at the time same time on each CPU. */
 141 #define RTTIMER_FLAGS_CPU_ALL       ( RTTIMER_FLAGS_CPU_MASK | RTTIMER_FLAGS_CPU_SPECIFIC )
 142 /** CPU mask. */
 143 #define RTTIMER_FLAGS_CPU_MASK      UINT32_C(0xffff)
 144 /** Desire a high resolution timer that works with RTTimerChangeInterval and
 145  * isn't subject to RTTimerGetSystemGranularity rounding.
 146  * @remarks This is quietly ignored if the feature isn't supported. */
 147 #define RTTIMER_FLAGS_HIGH_RES      RT_BIT(17)
 148 /** Convert a CPU set index (0-based) to RTTimerCreateEx flags.
 149  * This will automatically OR in the RTTIMER_FLAGS_CPU_SPECIFIC flag. */
 150 #define RTTIMER_FLAGS_CPU(iCpu)     ( (iCpu) | RTTIMER_FLAGS_CPU_SPECIFIC )
 151 /** Macro that validates the flags. */
 152 #define RTTIMER_FLAGS_ARE_VALID(fFlags) \
 153     ( !((fFlags) & ((fFlags) & RTTIMER_FLAGS_CPU_SPECIFIC ? ~UINT32_C(0x3ffff) : ~UINT32_C(0x30000))) )
 154 /** @} */
 155
 156 /**
 157  * Stops and destroys a running timer.
 158  *
 159  * @returns iprt status code.
 160  * @retval  VERR_INVALID_CONTEXT if executing at the wrong IRQL (windows), PIL
 161  *          (solaris), or similar.  Portable code does not destroy timers with
 162  *          preemption (or interrupts) disabled.
 163  * @param   pTimer      Timer to stop and destroy. NULL is ok.
 164  */
 165 RTDECL(int) RTTimerDestroy(PRTTIMER pTimer);
 166
 167 /**
 168  * Starts a suspended timer.
 169  *
 170  * @returns IPRT status code.
 171  * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 172  * @retval  VERR_TIMER_ACTIVE if the timer isn't suspended.
 173  * @retval  VERR_CPU_OFFLINE if the CPU the timer was created to run on is not
 174  *          online (this include the case where it's not present in the
 175  *          system).
 176  *
 177  * @param   pTimer      The timer to activate.
 178  * @param   u64First    The RTTimeSystemNanoTS() for when the timer should start
 179  *                      firing (relative).  If 0 is specified, the timer will
 180  *                      fire ASAP.
 181  * @remarks When RTTimerCanDoHighResolution returns true, this API is
 182  *          callable with preemption disabled in ring-0.
 183  * @see     RTTimerStop
 184  */
 185 RTDECL(int) RTTimerStart(PRTTIMER pTimer, uint64_t u64First);
 186
 187 /**
 188  * Stops an active timer.
 189  *
 190  * @todo    May return while the timer callback function is being services on
 191  *          some platforms (ring-0 Windows, ring-0 linux).  This needs to be
 192  *          addressed at some point...
 193  *
 194  * @returns IPRT status code.
 195  * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 196  * @retval  VERR_TIMER_SUSPENDED if the timer isn't active.
 197  * @retval  VERR_NOT_SUPPORTED if the IPRT implementation doesn't support
 198  *          stopping a timer.
 199  *
 200  * @param   pTimer  The timer to suspend.
 201  * @remarks Can be called from the timer callback function to stop it.
 202  * @see     RTTimerStart
 203  */
 204 RTDECL(int) RTTimerStop(PRTTIMER pTimer);
 205
 206 /**
 207  * Changes the interval of a periodic timer.
 208  *
 209  * If the timer is active, it is implementation dependent whether the change
 210  * takes place immediately or after the next tick.  To get defined behavior,
 211  * stop the timer before calling this API.
 212  *
 213  * @returns IPRT status code.
 214  * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 215  * @retval  VERR_NOT_SUPPORTED if not supported.
 216  * @retval  VERR_INVALID_STATE if not a periodic timer.
 217  *
 218  * @param   pTimer              The timer to activate.
 219  * @param   u64NanoInterval     The interval between timer ticks specified in
 220  *                              nanoseconds.  This is rounded to the fit the
 221  *                              system timer granularity.
 222  * @remarks Callable from the timer callback.  Callable with preemption
 223  *          disabled in ring-0.
 224  */
 225 RTDECL(int) RTTimerChangeInterval(PRTTIMER pTimer, uint64_t u64NanoInterval);
 226
 227 /**
 228  * Gets the (current) timer granularity of the system.
 229  *
 230  * @returns The timer granularity of the system in nanoseconds.
 231  * @see     RTTimerRequestSystemGranularity
 232  */
 233 RTDECL(uint32_t) RTTimerGetSystemGranularity(void);
 234
 235 /**
 236  * Requests a specific system timer granularity.
 237  *
 238  * Successfull calls to this API must be coupled with the exact same number of
 239  * calls to RTTimerReleaseSystemGranularity() in order to undo any changes made.
 240  *
 241  *
 242  * @returns IPRT status code.
 243  * @retval  VERR_NOT_SUPPORTED if the requested value isn't supported by the host platform
 244  *          or if the host platform doesn't support modifying the system timer granularity.
 245  * @retval  VERR_PERMISSION_DENIED if the caller doesn't have the necessary privilege to
 246  *          modify the system timer granularity.
 247  *
 248  * @param   u32Request      The requested system timer granularity in nanoseconds.
 249  * @param   pu32Granted     Where to store the granted system granularity. This is the value
 250  *                          that should be passed to  RTTimerReleaseSystemGranularity(). It
 251  *                          is what RTTimerGetSystemGranularity() would return immediately
 252  *                          after the change was made.
 253  *
 254  *                          The value differ from the request in two ways; rounding and
 255  *                          scale. Meaning if your request is for 10.000.000 you might
 256  *                          be granted 10.000.055 or 1.000.000.
 257  * @see     RTTimerReleaseSystemGranularity, RTTimerGetSystemGranularity
 258  */
 259 RTDECL(int) RTTimerRequestSystemGranularity(uint32_t u32Request, uint32_t *pu32Granted);
 260
 261 /**
 262  * Releases a system timer granularity grant acquired by RTTimerRequestSystemGranularity().
 263  *
 264  * @returns IPRT status code.
 265  * @retval  VERR_NOT_SUPPORTED if the host platform doesn't have any way of modifying
 266  *          the system timer granularity.
 267  * @retval  VERR_WRONG_ORDER if nobody call RTTimerRequestSystemGranularity() with the
 268  *          given grant value.
 269  * @param   u32Granted      The granted system granularity.
 270  * @see     RTTimerRequestSystemGranularity
 271  */
 272 RTDECL(int) RTTimerReleaseSystemGranularity(uint32_t u32Granted);
 273
 274 /**
 275  * Checks if the system support high resolution timers.
 276  *
 277  * The kind of support we are checking for is the kind of dynamically
 278  * reprogrammable timers employed by recent Solaris and Linux kernels.  It also
 279  * implies that we can specify microsecond (or even better maybe) intervals
 280  * without getting into trouble.
 281  *
 282  * @returns true if supported, false it not.
 283  *
 284  * @remarks Returning true also means RTTimerChangeInterval must be implemented
 285  *          and RTTimerStart be callable with preemption disabled.
 286  */
 287 RTDECL(bool) RTTimerCanDoHighResolution(void);
 288
 289
 290 /**
 291  * Timer callback function for low res timers.
 292  *
 293  * This is identical to FNRTTIMER except for the first parameter, so
 294  * see FNRTTIMER for details.
 295  *
 296  * @param   hTimerLR    The low resolution timer handle.
 297  * @param   pvUser      User argument.
 298  * @param   iTick       The current timer tick. This is always 1 on the first
 299  *                      callback after the timer was started. Will jump if we've
 300  *                      skipped ticks when lagging behind.
 301  */
 302 typedef DECLCALLBACKTYPE(void, FNRTTIMERLR,(RTTIMERLR hTimerLR, void *pvUser, uint64_t iTick));
 303 /** Pointer to FNRTTIMER() function. */
 304 typedef FNRTTIMERLR *PFNRTTIMERLR;
 305
 306
 307 /**
 308  * Create a recurring low resolution timer.
 309  *
 310  * @returns iprt status code.
 311  * @param   phTimerLR           Where to store the timer handle.
 312  * @param   uMilliesInterval    Milliseconds between the timer ticks, at least 100 ms.
 313  *                              If higher resolution is required use the other API.
 314  * @param   pfnTimer            Callback function which shall be scheduled for execution
 315  *                              on every timer tick.
 316  * @param   pvUser              User argument for the callback.
 317  * @see     RTTimerLRCreateEx, RTTimerLRDestroy, RTTimerLRStop
 318  */
 319 RTDECL(int) RTTimerLRCreate(PRTTIMERLR phTimerLR, uint32_t uMilliesInterval, PFNRTTIMERLR pfnTimer, void *pvUser);
 320
 321 /**
 322  * Create a suspended low resolution timer.
 323  *
 324  * @returns iprt status code.
 325  * @retval  VERR_NOT_SUPPORTED if an unsupported flag was specfied.
 326  *
 327  * @param   phTimerLR           Where to store the timer handle.
 328  * @param   u64NanoInterval     The interval between timer ticks specified in nanoseconds if it's
 329  *                              a recurring timer, the minimum for is 100000000 ns.
 330  *                              For one shot timers, pass 0.
 331  * @param   fFlags              Timer flags. Same as RTTimerCreateEx.
 332  * @param   pfnTimer            Callback function which shall be scheduled for execution
 333  *                              on every timer tick.
 334  * @param   pvUser              User argument for the callback.
 335  * @see     RTTimerLRStart, RTTimerLRStop, RTTimerLRDestroy
 336  */
 337 RTDECL(int) RTTimerLRCreateEx(PRTTIMERLR phTimerLR, uint64_t u64NanoInterval, uint32_t fFlags, PFNRTTIMERLR pfnTimer, void *pvUser);
 338
 339 /**
 340  * Stops and destroys a running low resolution timer.
 341  *
 342  * @returns iprt status code.
 343  * @param   hTimerLR            The low resolution timer to stop and destroy.
 344  *                              NIL_RTTIMERLR is accepted.
 345  */
 346 RTDECL(int) RTTimerLRDestroy(RTTIMERLR hTimerLR);
 347
 348 /**
 349  * Starts a low resolution timer.
 350  *
 351  * @returns IPRT status code.
 352  * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 353  * @retval  VERR_TIMER_ACTIVE if the timer isn't suspended.
 354  *
 355  * @param   hTimerLR            The low resolution timer to activate.
 356  * @param   u64First            The RTTimeSystemNanoTS() for when the timer should start
 357  *                              firing (relative), the minimum is 100000000 ns.
 358  *                              If 0 is specified, the timer will fire ASAP.
 359  *
 360  * @see     RTTimerLRStop
 361  */
 362 RTDECL(int) RTTimerLRStart(RTTIMERLR hTimerLR, uint64_t u64First);
 363
 364 /**
 365  * Stops an active low resolution timer.
 366  *
 367  * @returns IPRT status code.
 368  * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 369  * @retval  VERR_TIMER_SUSPENDED if the timer isn't active.
 370  * @retval  VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.
 371  *
 372  * @param   hTimerLR            The low resolution timer to suspend.
 373  *
 374  * @see     RTTimerLRStart
 375  */
 376 RTDECL(int) RTTimerLRStop(RTTIMERLR hTimerLR);
 377
 378 /**
 379  * Changes the interval of a low resolution timer.
 380  *
 381  * If the timer is active, the next tick will occure immediately just like with
 382  * RTTimerLRStart() when u64First parameter is zero.
 383  *
 384  * @returns IPRT status code.
 385  * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 386  * @retval  VERR_NOT_SUPPORTED if not supported.
 387  *
 388  * @param   hTimerLR            The low resolution timer to update.
 389  * @param   u64NanoInterval     The interval between timer ticks specified in
 390  *                              nanoseconds.  This is rounded to the fit the
 391  *                              system timer granularity.
 392  * @remarks Callable from the timer callback.
 393  */
 394 RTDECL(int) RTTimerLRChangeInterval(RTTIMERLR hTimerLR, uint64_t u64NanoInterval);
 395
 396 /** @} */
 397
 398 RT_C_DECLS_END
 399
 400 #endif /* !IPRT_INCLUDED_timer_h */