xnu-4903.221.2.tar.gz

[apple/xnu.git] / iokit / IOKit / IOTimerEventSource.h

diff --git a/iokit/IOKit/IOTimerEventSource.h b/iokit/IOKit/IOTimerEventSource.h
index cedfaa40dadb2a17abcdab7670466c529c9aadc5..8ef49ef191cd9411a34a688f5f6a80beef9ac8b1 100644 (file)
--- a/iokit/IOKit/IOTimerEventSource.h
+++ b/iokit/IOKit/IOTimerEventSource.h
@@ -1,5 +1,5 @@
 /*
 /*

- * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 1998-2016 Apple Inc. All rights reserved.

  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * 
  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * 


@@ -47,6 +47,56 @@ __END_DECLS
 #include <IOKit/IOEventSource.h>
 #include <IOKit/IOTypes.h>
 
 #include <IOKit/IOEventSource.h>
 #include <IOKit/IOTypes.h>
 

+/*!
+       @enum IOTimerEventSource constructor options
+       @abstract Constants defining behavior of the IOTimerEventSource.
+       @constant kIOTimerEventSourceOptionsPriorityHigh Importance above everything but realtime.
+       Thread calls allocated with this priority execute at extremely high priority,
+       above everything but realtime threads.  They are generally executed in serial.
+       Though they may execute concurrently under some circumstances, no fan-out is implied.
+       These work items should do very small amounts of work or risk disrupting system
+       responsiveness.
+       @constant kIOTimerEventSourceOptionsPriorityKernelHigh Importance higher than most kernel
+       threads.
+       @constant kIOTimerEventSourceOptionsPriorityKernel Importance similar to that of normal kernel
+       threads.
+       @constant kIOTimerEventSourceOptionsPriorityUser Importance similar to that of normal user threads.
+       @constant kIOTimerEventSourceOptionsPriorityLow Very low importance.
+       @constant kIOTimerEventSourceOptionsPriorityWorkLoop Run the callout on the thread of the IOWorkLoop
+       the event source has been added to.
+       @constant kIOTimerEventSourceOptionsAllowReenter Allow the callout to be rescheduled and potentially
+       re-entered, if the IOWorkLoop lock has been released (eg. with commandSleep) during its invocation.
+       @constant kIOTimerEventSourceOptionsDefault Recommended default options.
+ */
+enum
+{
+    kIOTimerEventSourceOptionsPriorityMask       = 0x000000ff,
+    kIOTimerEventSourceOptionsPriorityHigh       = 0x00000000,
+    kIOTimerEventSourceOptionsPriorityKernelHigh = 0x00000001,
+    kIOTimerEventSourceOptionsPriorityKernel     = 0x00000002,
+    kIOTimerEventSourceOptionsPriorityUser       = 0x00000003,
+    kIOTimerEventSourceOptionsPriorityLow        = 0x00000004,
+    kIOTimerEventSourceOptionsPriorityWorkLoop   = 0x000000ff,
+
+    kIOTimerEventSourceOptionsAllowReenter       = 0x00000100,
+
+    kIOTimerEventSourceOptionsDefault            = kIOTimerEventSourceOptionsPriorityKernelHigh
+};
+
+#define IOTIMEREVENTSOURCEOPTIONS_DEFINED      1
+
+/*!
+       @enum IOTimerEventSource setTimeout/wakeAtTime options
+       @abstract Constants defining behavior of a scheduled call from IOTimerEventSource.
+       @constant kIOTimeOptionsWithLeeway Use the leeway parameter to the call.
+       @constant kIOTimeOptionsContinuous Use mach_continuous_time() to generate the callback.
+*/
+enum
+{
+    kIOTimeOptionsWithLeeway = 0x00000020,
+    kIOTimeOptionsContinuous = 0x00000100,
+};
+

 /*!
     @class IOTimerEventSource : public IOEventSource
     @abstract Time based event source mechanism.
 /*!
     @class IOTimerEventSource : public IOEventSource
     @abstract Time based event source mechanism.


@@ -56,6 +106,7 @@ __END_DECLS
 <br><br>
        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.
 */
 <br><br>
        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.
 */

+

 class IOTimerEventSource : public IOEventSource
 {
     OSDeclareDefaultStructors(IOTimerEventSource)
 class IOTimerEventSource : public IOEventSource
 {
     OSDeclareDefaultStructors(IOTimerEventSource)


@@ -73,12 +124,15 @@ protected:
     struct ExpansionData
     {
         SInt32      calloutGeneration;
     struct ExpansionData
     {
         SInt32      calloutGeneration;

+        SInt32      calloutGenerationSignaled;

         IOWorkLoop * workLoop;
     };
 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */
         IOWorkLoop * workLoop;
     };
 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */

+    APPLE_KEXT_WSHADOW_PUSH;

     ExpansionData *reserved;
     ExpansionData *reserved;

+    APPLE_KEXT_WSHADOW_POP;

 
 /*! @function timeout
     @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
 
 /*! @function timeout
     @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.


@@ -93,13 +147,9 @@ protected:
 
 /*! @function free
     @abstract Sub-class implementation of free method, frees calloutEntry */
 
 /*! @function free
     @abstract Sub-class implementation of free method, frees calloutEntry */

-    virtual void free();
-
-/*! @function checkForWork
-    @abstract Have to implement it is mandatory in $link IOEventSource, but IOTimerEventSources don't actually use this work-loop mechanism. */
-    virtual bool checkForWork();
+    virtual void free() APPLE_KEXT_OVERRIDE;

 
 

-    virtual void setWorkLoop(IOWorkLoop *workLoop);
+    virtual void setWorkLoop(IOWorkLoop *workLoop) APPLE_KEXT_OVERRIDE;

 
 public:
 
 
 public:
 


@@ -109,45 +159,74 @@ public:
     @param sender The object that timed out. */
     typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);
 
     @param sender The object that timed out. */
     typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);
 

+#ifdef __BLOCKS__
+    typedef void (^ActionBlock)(IOTimerEventSource *sender);
+#endif /* __BLOCKS__ */
+
+    static IOTimerEventSource *
+       timerEventSource(OSObject *owner, Action action = 0);
+

 /*! @function timerEventSource
     @abstract Allocates and returns an initialized timer instance.
 /*! @function timerEventSource
     @abstract Allocates and returns an initialized timer instance.

-    @param owner
-    @param action */
+    @param options Mask of kIOTimerEventSourceOptions* options.
+    @param owner The object that that will be passed to the Action callback.
+    @param action 'C' Function pointer for the callout routine of this event source.
+    */

     static IOTimerEventSource *
     static IOTimerEventSource *

-       timerEventSource(OSObject *owner, Action action = 0);
+       timerEventSource(uint32_t options, OSObject *owner, Action action = 0);
+
+#ifdef __BLOCKS__
+/*! @function timerEventSource
+    @abstract Allocates and returns an initialized timer instance.
+    @param options Mask of kIOTimerEventSourceOptions* options.
+    @param inOwner The object that that will be passed to the Action callback.
+    @param action Block for the callout routine of this event source.
+    */
+    static IOTimerEventSource *
+       timerEventSource(uint32_t options, OSObject *inOwner, ActionBlock action);
+#endif /* __BLOCKS__ */
+
+#if XNU_KERNEL_PRIVATE
+       __inline__ void invokeAction(IOTimerEventSource::Action action, IOTimerEventSource * ts,
+            OSObject * owner, IOWorkLoop * workLoop);
+#endif /* XNU_KERNEL_PRIVATE */

 
 /*! @function init
     @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
 
 /*! @function init
     @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.

-    @param owner 
-    @param action */
+    */

     virtual bool init(OSObject *owner, Action action = 0);
 
 /*! @function enable
     @abstract Enables a call to the action.
     @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. */
     virtual bool init(OSObject *owner, Action action = 0);
 
 /*! @function enable
     @abstract Enables a call to the action.
     @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. */

-    virtual void enable();
+    virtual void enable() APPLE_KEXT_OVERRIDE;

 
 /*! @function disable
     @abstract Disable a timed callout.
     @discussion When disable returns the action will not be called until the next time enable(qv) is called. */
 
 /*! @function disable
     @abstract Disable a timed callout.
     @discussion When disable returns the action will not be called until the next time enable(qv) is called. */

-    virtual void disable();
+    virtual void disable() APPLE_KEXT_OVERRIDE;

 
 

+/*! @function checkForWork
+    @abstract Pure Virtual member function used by IOWorkLoop for issuing a client calls.
+    @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.
+    @result Return true if this function needs to be called again before all its outstanding events have been processed. */
+    virtual bool checkForWork() APPLE_KEXT_OVERRIDE;

 
 /*! @function setTimeoutTicks
     @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).
 
 /*! @function setTimeoutTicks
     @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).

-    @param interval Delay from now to wake up, in scheduler ticks, whatever that may be.
+    @param ticks Delay from now to wake up, in scheduler ticks, whatever that may be.

     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn setTimeoutTicks(UInt32 ticks);
 
 /*! @function setTimeoutMS
     @abstract Setup a callback at after the delay in milliseconds.  See wakeAtTime(AbsoluteTime).
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn setTimeoutTicks(UInt32 ticks);
 
 /*! @function setTimeoutMS
     @abstract Setup a callback at after the delay in milliseconds.  See wakeAtTime(AbsoluteTime).

-    @param interval Delay from now to wake up, time in milliseconds.
+    @param ms Delay from now to wake up, time in milliseconds.

     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn setTimeoutMS(UInt32 ms);
 
 /*! @function setTimeoutUS
         @abstract Setup a callback at after the delay in microseconds.  See wakeAtTime(AbsoluteTime).
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn setTimeoutMS(UInt32 ms);
 
 /*! @function setTimeoutUS
         @abstract Setup a callback at after the delay in microseconds.  See wakeAtTime(AbsoluteTime).

-    @param interval Delay from now to wake up, time in microseconds.
+    @param us Delay from now to wake up, time in microseconds.

     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn setTimeoutUS(UInt32 us);
 
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn setTimeoutUS(UInt32 us);
 


@@ -159,11 +238,10 @@ public:
     virtual IOReturn setTimeout(UInt32 interval,
                                UInt32 scale_factor = kNanosecondScale);
 
     virtual IOReturn setTimeout(UInt32 interval,
                                UInt32 scale_factor = kNanosecondScale);
 

-/*! @function setTimeout
-    @abstract Setup a callback at after the delay in decrementer ticks.         See wakeAtTime(AbsoluteTime).
-    @param interval Delay from now to wake up.
-    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
-    virtual IOReturn setTimeout(mach_timespec_t interval);
+#if !defined(__LP64__)
+    virtual IOReturn setTimeout(mach_timespec_t interval)
+       APPLE_KEXT_DEPRECATED;
+#endif

 
 /*! @function setTimeout
     @abstract Setup a callback at after the delay in decrementer ticks.         See wakeAtTime(AbsoluteTime).
 
 /*! @function setTimeout
     @abstract Setup a callback at after the delay in decrementer ticks.         See wakeAtTime(AbsoluteTime).


@@ -173,19 +251,19 @@ public:
 
 /*! @function wakeAtTimeTicks
     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 
 /*! @function wakeAtTimeTicks
     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).

-    @param abstime Time to wake up in scheduler quantums, whatever that is?
+    @param ticks Time to wake up in scheduler quantums, whatever that is?

     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
 
 /*! @function wakeAtTimeMS
     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
 
 /*! @function wakeAtTimeMS
     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).

-    @param abstime Time to wake up in milliseconds.
+    @param ms Time to wake up in milliseconds.

     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn wakeAtTimeMS(UInt32 ms);
 
 /*! @function wakeAtTimeUS
     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn wakeAtTimeMS(UInt32 ms);
 
 /*! @function wakeAtTimeUS
     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).

-    @param abstime Time to wake up in microseconds.
+    @param us Time to wake up in microseconds.

     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn wakeAtTimeUS(UInt32 us);
 
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
     virtual IOReturn wakeAtTimeUS(UInt32 us);
 


@@ -197,15 +275,14 @@ public:
     virtual IOReturn wakeAtTime(UInt32 abstime,
                                UInt32 scale_factor = kNanosecondScale);
 
     virtual IOReturn wakeAtTime(UInt32 abstime,
                                UInt32 scale_factor = kNanosecondScale);
 

-/*! @function wakeAtTime
-    @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
-    @param abstime mach_timespec_t of the desired callout time.
-    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
-    virtual IOReturn wakeAtTime(mach_timespec_t abstime);
+#if !defined(__LP64__)
+    virtual IOReturn wakeAtTime(mach_timespec_t abstime)
+       APPLE_KEXT_DEPRECATED;
+#endif

 
 /*! @function wakeAtTime
     @abstract Setup a callback at this absolute time.
 
 /*! @function wakeAtTime
     @abstract Setup a callback at this absolute time.

-    @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.  
+    @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.

     @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
     virtual IOReturn wakeAtTime(AbsoluteTime abstime);
     @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
     virtual IOReturn wakeAtTime(AbsoluteTime abstime);


@@ -215,13 +292,36 @@ public:
     @discussion Clear down any oustanding calls.  By the time this function completes it is guaranteed that the action will not be called again. */
    virtual void cancelTimeout();
 
     @discussion Clear down any oustanding calls.  By the time this function completes it is guaranteed that the action will not be called again. */
    virtual void cancelTimeout();
 

+/*! @function init
+    @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
+    */
+    virtual bool init(uint32_t options, OSObject *inOwner, Action inAction);
+
+/*! @function setTimeout
+    @abstract Setup a callback at after the delay in decrementer ticks.         See wakeAtTime(AbsoluteTime).
+    @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
+    @param interval Delay from now to wake up in decrementer ticks.
+    @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
+    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
+    virtual IOReturn setTimeout(uint32_t options, AbsoluteTime interval, AbsoluteTime leeway);
+
+/*! @function wakeAtTime
+    @abstract Setup a callback at this absolute time.
+    @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.
+    @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
+    @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
+    @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
+    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
+    virtual IOReturn wakeAtTime(uint32_t options, AbsoluteTime abstime, AbsoluteTime leeway);
+

 private:
 private:

-    static void timeoutAndRelease(void *self, void *wl);
+    static void timeoutAndRelease(void *self, void *c);
+    static void timeoutSignaled(void *self, void *c);

 
 private:
 
 private:

-    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 0);
-    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 1);
-    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 2);
+    OSMetaClassDeclareReservedUsed(IOTimerEventSource, 0);
+    OSMetaClassDeclareReservedUsed(IOTimerEventSource, 1);
+    OSMetaClassDeclareReservedUsed(IOTimerEventSource, 2);

     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);