iokit/IOKit/IOTimerEventSource.h

   1 /*
   2  * Copyright (c) 1998-2019 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  30  *
  31  * IOTimerEventSource.h
  32  *
  33  * HISTORY
  34  * 2-Feb-1999           Joe Liu (jliu) created.
  35  *
  36  */
  37
  38 #ifndef _IOTIMEREVENTSOURCE
  39 #define _IOTIMEREVENTSOURCE
  40
  41 #include <sys/cdefs.h>
  42
  43 __BEGIN_DECLS
  44 #include <kern/clock.h>
  45 __END_DECLS
  46
  47 #include <IOKit/IOEventSource.h>
  48 #include <IOKit/IOTypes.h>
  49
  50 /*!
  51  *       @enum IOTimerEventSource constructor options
  52  *       @abstract Constants defining behavior of the IOTimerEventSource.
  53  *       @constant kIOTimerEventSourceOptionsPriorityHigh Importance above everything but realtime.
  54  *       Thread calls allocated with this priority execute at extremely high priority,
  55  *       above everything but realtime threads.  They are generally executed in serial.
  56  *       Though they may execute concurrently under some circumstances, no fan-out is implied.
  57  *       These work items should do very small amounts of work or risk disrupting system
  58  *       responsiveness.
  59  *       @constant kIOTimerEventSourceOptionsPriorityKernelHigh Importance higher than most kernel
  60  *       threads.
  61  *       @constant kIOTimerEventSourceOptionsPriorityKernel Importance similar to that of normal kernel
  62  *       threads.
  63  *       @constant kIOTimerEventSourceOptionsPriorityUser Importance similar to that of normal user threads.
  64  *       @constant kIOTimerEventSourceOptionsPriorityLow Very low importance.
  65  *       @constant kIOTimerEventSourceOptionsPriorityWorkLoop Run the callout on the thread of the IOWorkLoop
  66  *       the event source has been added to.
  67  *       @constant kIOTimerEventSourceOptionsAllowReenter Allow the callout to be rescheduled and potentially
  68  *       re-entered, if the IOWorkLoop lock has been released (eg. with commandSleep) during its invocation.
  69  *       @constant kIOTimerEventSourceOptionsDefault Recommended default options.
  70  */
  71 enum{
  72         kIOTimerEventSourceOptionsPriorityMask       = 0x000000ff,
  73         kIOTimerEventSourceOptionsPriorityHigh       = 0x00000000,
  74         kIOTimerEventSourceOptionsPriorityKernelHigh = 0x00000001,
  75         kIOTimerEventSourceOptionsPriorityKernel     = 0x00000002,
  76         kIOTimerEventSourceOptionsPriorityUser       = 0x00000003,
  77         kIOTimerEventSourceOptionsPriorityLow        = 0x00000004,
  78         kIOTimerEventSourceOptionsPriorityWorkLoop   = 0x000000ff,
  79
  80         kIOTimerEventSourceOptionsAllowReenter       = 0x00000100,
  81
  82         kIOTimerEventSourceOptionsDefault            = kIOTimerEventSourceOptionsPriorityKernelHigh
  83 };
  84
  85 #define IOTIMEREVENTSOURCEOPTIONS_DEFINED       1
  86
  87 /*!
  88  *       @enum IOTimerEventSource setTimeout/wakeAtTime options
  89  *       @abstract Constants defining behavior of a scheduled call from IOTimerEventSource.
  90  *       @constant kIOTimeOptionsWithLeeway Use the leeway parameter to the call.
  91  *       @constant kIOTimeOptionsContinuous Use mach_continuous_time() to generate the callback.
  92  */
  93 enum{
  94         kIOTimeOptionsWithLeeway = 0x00000020,
  95         kIOTimeOptionsContinuous = 0x00000100,
  96 };
  97
  98 /*!
  99  *   @class IOTimerEventSource : public IOEventSource
 100  *   @abstract Time based event source mechanism.
 101  *   @discussion An event source that implements a simple timer.         A timeout handler is called once the timeout period expires.  This timeout handler will be called by the work-loop that this event source is attached to.
 102  *  <br><br>
 103  *       Usually a timer event source will be used to implement a timeout.  In general when a driver makes a request it will need to setup a call to keep track of when the I/O doesn't complete.  This class is designed to make that somewhat easier.
 104  *  <br><br>
 105  *       Remember the system doesn't guarantee the accuracy of the callout.     It is possible that a higher priority thread is running which will delay the execution of the action routine.  In fact the thread will be made runable at the exact requested time, within the accuracy of the CPU's decrementer based interrupt, but the scheduler will then control execution.
 106  */
 107
 108 class IOTimerEventSource : public IOEventSource
 109 {
 110         OSDeclareDefaultStructors(IOTimerEventSource);
 111
 112 protected:
 113 /*! @var calloutEntry thread_call entry for preregistered thread callouts */
 114         void *calloutEntry;
 115
 116 /*! @var abstime time to wake up next, see enable. */
 117         AbsoluteTime abstime;
 118
 119 /*! @struct ExpansionData
 120  *   @discussion This structure is private to the IOTimerEventSource implementation.
 121  */
 122         struct ExpansionData {
 123                 SInt32       calloutGeneration;
 124                 SInt32       calloutGenerationSignaled;
 125                 IOWorkLoop * workLoop;
 126         };
 127
 128 /*! @var reserved
 129  *   Reserved for future use.  (Internal use only)  */
 130         APPLE_KEXT_WSHADOW_PUSH;
 131         ExpansionData *reserved;
 132         APPLE_KEXT_WSHADOW_POP;
 133
 134 /*! @function timeout
 135  *   @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
 136  *   @discussion timeout will normally not be called nor overridden by a subclass.  If the event source is enabled then close the work-loop's gate and call the action routine.
 137  *   @param self This argument will be cast to an IOTimerEventSource. */
 138         static void timeout(void *self);
 139
 140 /*! @function setTimeoutFunc
 141  *   @abstract Set's timeout as the function of calloutEntry.
 142  *   @discussion IOTimerEventSource is based upon the kern/thread_call.h APIs currently.         This function allocates the calloutEntry member variable by using thread_call_allocate(timeout, this).  If you need to write your own subclass of IOTimerEventSource you probably should override this method to allocate an entry that points to your own timeout routine. */
 143         virtual void setTimeoutFunc();
 144
 145 /*! @function free
 146  *   @abstract Sub-class implementation of free method, frees calloutEntry */
 147         virtual void free() APPLE_KEXT_OVERRIDE;
 148
 149         virtual void setWorkLoop(IOWorkLoop *workLoop) APPLE_KEXT_OVERRIDE;
 150
 151 public:
 152
 153 /*! @typedef Action
 154  *   @discussion 'C' Function pointer defining the callout routine of this event source.
 155  *   @param owner Owning target object. Note by a startling coincidence the first parameter in a C callout is currently used to define the target of a C++ member function.
 156  *   @param sender The object that timed out. */
 157         typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);
 158
 159 #ifdef __BLOCKS__
 160         typedef void (^ActionBlock)(IOTimerEventSource *sender);
 161 #endif /* __BLOCKS__ */
 162
 163         static IOTimerEventSource *
 164         timerEventSource(OSObject *owner, Action action = NULL);
 165
 166 /*! @function timerEventSource
 167  *   @abstract Allocates and returns an initialized timer instance.
 168  *   @param options Mask of kIOTimerEventSourceOptions* options.
 169  *   @param owner The object that that will be passed to the Action callback.
 170  *   @param action 'C' Function pointer for the callout routine of this event source.
 171  */
 172         static IOTimerEventSource *
 173         timerEventSource(uint32_t options, OSObject *owner, Action action = NULL);
 174
 175 #ifdef __BLOCKS__
 176 /*! @function timerEventSource
 177  *   @abstract Allocates and returns an initialized timer instance.
 178  *   @param options Mask of kIOTimerEventSourceOptions* options.
 179  *   @param inOwner The object that that will be passed to the Action callback.
 180  *   @param action Block for the callout routine of this event source.
 181  */
 182         static IOTimerEventSource *
 183         timerEventSource(uint32_t options, OSObject *inOwner, ActionBlock action);
 184 #endif /* __BLOCKS__ */
 185
 186 #if XNU_KERNEL_PRIVATE
 187         __inline__ void invokeAction(IOTimerEventSource::Action action, IOTimerEventSource * ts,
 188             OSObject * owner, IOWorkLoop * workLoop);
 189 #endif /* XNU_KERNEL_PRIVATE */
 190
 191 /*! @function init
 192  *   @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
 193  */
 194         virtual bool init(OSObject *owner, Action action = NULL);
 195
 196 /*! @function enable
 197  *   @abstract Enables a call to the action.
 198  *   @discussion Allows the action function to be called.  If the timer event source was disabled while a call was outstanding and the call wasn't cancelled then it will be rescheduled.  So a disable/enable pair will disable calls from this event source. */
 199         virtual void enable() APPLE_KEXT_OVERRIDE;
 200
 201 /*! @function disable
 202  *   @abstract Disable a timed callout.
 203  *   @discussion When disable returns the action will not be called until the next time enable(qv) is called. */
 204         virtual void disable() APPLE_KEXT_OVERRIDE;
 205
 206 /*! @function checkForWork
 207  *   @abstract Pure Virtual member function used by IOWorkLoop for issuing a client calls.
 208  *   @discussion This function called when the work-loop is ready to check for any work to do and then to call out the owner/action.
 209  *   @result Return true if this function needs to be called again before all its outstanding events have been processed. */
 210         virtual bool checkForWork() APPLE_KEXT_OVERRIDE;
 211
 212 /*! @function setTimeoutTicks
 213  *   @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).
 214  *   @param ticks Delay from now to wake up, in scheduler ticks, whatever that may be.
 215  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 216         virtual IOReturn setTimeoutTicks(UInt32 ticks);
 217
 218 /*! @function setTimeoutMS
 219  *   @abstract Setup a callback at after the delay in milliseconds.  See wakeAtTime(AbsoluteTime).
 220  *   @param ms Delay from now to wake up, time in milliseconds.
 221  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 222         virtual IOReturn setTimeoutMS(UInt32 ms);
 223
 224 /*! @function setTimeoutUS
 225  *       @abstract Setup a callback at after the delay in microseconds.  See wakeAtTime(AbsoluteTime).
 226  *   @param us Delay from now to wake up, time in microseconds.
 227  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 228         virtual IOReturn setTimeoutUS(UInt32 us);
 229
 230 /*! @function setTimeout
 231  *   @abstract Setup a callback at after the delay in some unit.         See wakeAtTime(AbsoluteTime).
 232  *   @param interval Delay from now to wake up in some defined unit.
 233  *   @param scale_factor Define the unit of interval, default to nanoseconds.
 234  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 235         virtual IOReturn setTimeout(UInt32 interval,
 236             UInt32 scale_factor = kNanosecondScale);
 237
 238 #if !defined(__LP64__)
 239         virtual IOReturn setTimeout(mach_timespec_t interval)
 240         APPLE_KEXT_DEPRECATED;
 241 #endif
 242
 243 /*! @function setTimeout
 244  *   @abstract Setup a callback at after the delay in decrementer ticks.         See wakeAtTime(AbsoluteTime).
 245  *   @param interval Delay from now to wake up in decrementer ticks.
 246  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 247         virtual IOReturn setTimeout(AbsoluteTime interval);
 248
 249 /*! @function wakeAtTimeTicks
 250  *   @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 251  *   @param ticks Time to wake up in scheduler quantums, whatever that is?
 252  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 253         virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
 254
 255 /*! @function wakeAtTimeMS
 256  *   @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 257  *   @param ms Time to wake up in milliseconds.
 258  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 259         virtual IOReturn wakeAtTimeMS(UInt32 ms);
 260
 261 /*! @function wakeAtTimeUS
 262  *   @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 263  *   @param us Time to wake up in microseconds.
 264  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 265         virtual IOReturn wakeAtTimeUS(UInt32 us);
 266
 267 /*! @function wakeAtTime
 268  *   @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 269  *   @param abstime Time to wake up in some unit.
 270  *   @param scale_factor Define the unit of abstime, default to nanoseconds.
 271  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 272         virtual IOReturn wakeAtTime(UInt32 abstime,
 273             UInt32 scale_factor = kNanosecondScale);
 274
 275 #if !defined(__LP64__)
 276         virtual IOReturn wakeAtTime(mach_timespec_t abstime)
 277         APPLE_KEXT_DEPRECATED;
 278 #endif
 279
 280 /*! @function wakeAtTime
 281  *   @abstract Setup a callback at this absolute time.
 282  *   @discussion Starts the timer, which will expire at abstime. After it expires, the timer will call the 'action' registered in the init() function. This timer is not periodic, a further call is needed to reset and restart the timer after it expires.
 283  *   @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
 284  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
 285         virtual IOReturn wakeAtTime(AbsoluteTime abstime);
 286
 287 /*! @function cancelTimeout
 288  *   @abstract Disable any outstanding calls to this event source.
 289  *   @discussion Clear down any oustanding calls.  By the time this function completes it is guaranteed that the action will not be called again. */
 290         virtual void cancelTimeout();
 291
 292 /*! @function init
 293  *   @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
 294  */
 295         virtual bool init(uint32_t options, OSObject *inOwner, Action inAction);
 296
 297 /*! @function setTimeout
 298  *   @abstract Setup a callback at after the delay in decrementer ticks.         See wakeAtTime(AbsoluteTime).
 299  *   @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
 300  *   @param interval Delay from now to wake up in decrementer ticks.
 301  *   @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
 302  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 303         virtual IOReturn setTimeout(uint32_t options, AbsoluteTime interval, AbsoluteTime leeway);
 304
 305 /*! @function wakeAtTime
 306  *   @abstract Setup a callback at this absolute time.
 307  *   @discussion Starts the timer, which will expire at abstime. After it expires, the timer will call the 'action' registered in the init() function. This timer is not periodic, a further call is needed to reset and restart the timer after it expires.
 308  *   @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
 309  *   @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
 310  *   @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
 311  *   @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
 312         virtual IOReturn wakeAtTime(uint32_t options, AbsoluteTime abstime, AbsoluteTime leeway);
 313
 314 private:
 315         static void timeoutAndRelease(void *self, void *c);
 316         static void timeoutSignaled(void *self, void *c);
 317
 318 private:
 319         OSMetaClassDeclareReservedUsed(IOTimerEventSource, 0);
 320         OSMetaClassDeclareReservedUsed(IOTimerEventSource, 1);
 321         OSMetaClassDeclareReservedUsed(IOTimerEventSource, 2);
 322         OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
 323         OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
 324         OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
 325         OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
 326         OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
 327 };
 328
 329 #endif /* !_IOTIMEREVENTSOURCE */