ubuntu/vbox/include/iprt/timer.h

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