iokit/IOKit/IOTimerEventSource.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  27  *
  28  * IOTimerEventSource.h
  29  *
  30  * HISTORY
  31  * 2-Feb-1999           Joe Liu (jliu) created.
  32  *
  33  */
  34
  35 #ifndef _IOTIMEREVENTSOURCE
  36 #define _IOTIMEREVENTSOURCE
  37
  38 #include <sys/cdefs.h>
  39
  40 __BEGIN_DECLS
  41 #include <kern/clock.h>
  42 __END_DECLS
  43
  44 #include <IOKit/IOEventSource.h>
  45 #include <IOKit/IOTypes.h>
  46
  47 /*!
  48     @class IOTimerEventSource : public IOEventSource
  49     @abstract Time based event source mechanism.
  50     @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.
  51 <br><br>
  52         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.
  53 <br><br>
  54         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.
  55 */
  56 class IOTimerEventSource : public IOEventSource
  57 {
  58     OSDeclareDefaultStructors(IOTimerEventSource)
  59
  60 protected:
  61 /*! @var calloutEntry thread_call entry for preregistered thread callouts */
  62     void *calloutEntry;
  63
  64 /*! @var abstime time to wake up next, see enable. */
  65     AbsoluteTime abstime;
  66
  67 /*! @struct ExpansionData
  68     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  69     */
  70     struct ExpansionData { };
  71
  72 /*! @var reserved
  73     Reserved for future use.  (Internal use only)  */
  74     ExpansionData *reserved;
  75
  76 /*! @function timeout
  77     @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
  78     @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.
  79     @param self This argument will be cast to an IOTimerEventSource. */
  80     static void timeout(void *self);
  81
  82 /*! @function setTimeoutFunc
  83     @abstract Set's timeout as the function of calloutEntry.
  84     @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. */
  85     virtual void setTimeoutFunc();
  86
  87 /*! @function free
  88     @abstract Sub-class implementation of free method, frees calloutEntry */
  89     virtual void free();
  90
  91 /*! @function checkForWork
  92     @abstract Have to implement it is mandatory in $link IOEventSource, but IOTimerEventSources don't actually use this work-loop mechanism. */
  93     virtual bool checkForWork();
  94
  95 public:
  96
  97 /*! @typedef Action
  98     @discussion 'C' Function pointer defining the callout routine of this event source.
  99     @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.
 100     @param sender The object that timed out. */
 101     typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);
 102
 103 /*! @function timerEventSource
 104     @abstract Allocates and returns an initialized timer instance.
 105     @param owner
 106     @param action */
 107     static IOTimerEventSource *
 108         timerEventSource(OSObject *owner, Action action = 0);
 109
 110 /*! @function init
 111     @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
 112     @param owner
 113     @param action */
 114     virtual bool init(OSObject *owner, Action action = 0);
 115
 116 /*! @function enable
 117     @abstract Enables a call to the action.
 118     @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. */
 119     virtual void enable();
 120
 121 /*! @function disable
 122     @abstract Disable a timed callout.
 123     @discussion When disable returns the action will not be called until the next time enable(qv) is called. */
 124     virtual void disable();
 125
 126
 127 /*! @function setTimeoutTicks
 128     @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).
 129     @param interval Delay from now to wake up, in scheduler ticks, whatever that may be.
 130     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 131     virtual IOReturn setTimeoutTicks(UInt32 ticks);
 132
 133 /*! @function setTimeoutMS
 134     @abstract Setup a callback at after the delay in milliseconds.  See wakeAtTime(AbsoluteTime).
 135     @param interval Delay from now to wake up, time in milliseconds.
 136     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 137     virtual IOReturn setTimeoutMS(UInt32 ms);
 138
 139 /*! @function setTimeoutUS
 140         @abstract Setup a callback at after the delay in microseconds.   See wakeAtTime(AbsoluteTime).
 141     @param interval Delay from now to wake up, time in microseconds.
 142     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 143     virtual IOReturn setTimeoutUS(UInt32 us);
 144
 145 /*! @function setTimeout
 146     @abstract Setup a callback at after the delay in some unit.  See wakeAtTime(AbsoluteTime).
 147     @param interval Delay from now to wake up in some defined unit.
 148     @param scale_factor Define the unit of interval, default to nanoseconds.
 149     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 150     virtual IOReturn setTimeout(UInt32 interval,
 151                                 UInt32 scale_factor = kNanosecondScale);
 152
 153 /*! @function setTimeout
 154     @abstract Setup a callback at after the delay in decrementer ticks.  See wakeAtTime(AbsoluteTime).
 155     @param interval Delay from now to wake up.
 156     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 157     virtual IOReturn setTimeout(mach_timespec_t interval);
 158
 159 /*! @function setTimeout
 160     @abstract Setup a callback at after the delay in decrementer ticks.  See wakeAtTime(AbsoluteTime).
 161     @param interval Delay from now to wake up in decrementer ticks.
 162     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 163     virtual IOReturn setTimeout(AbsoluteTime interval);
 164
 165 /*! @function wakeAtTimeTicks
 166     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 167     @param abstime Time to wake up in scheduler quantums, whatever that is?
 168     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 169     virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
 170
 171 /*! @function wakeAtTimeMS
 172     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 173     @param abstime Time to wake up in milliseconds.
 174     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 175     virtual IOReturn wakeAtTimeMS(UInt32 ms);
 176
 177 /*! @function wakeAtTimeUS
 178     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 179     @param abstime Time to wake up in microseconds.
 180     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 181     virtual IOReturn wakeAtTimeUS(UInt32 us);
 182
 183 /*! @function wakeAtTime
 184     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 185     @param abstime Time to wake up in some unit.
 186     @param scale_factor Define the unit of abstime, default to nanoseconds.
 187     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 188     virtual IOReturn wakeAtTime(UInt32 abstime,
 189                                 UInt32 scale_factor = kNanosecondScale);
 190
 191 /*! @function wakeAtTime
 192     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
 193     @param abstime mach_timespec_t of the desired callout time.
 194     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
 195     virtual IOReturn wakeAtTime(mach_timespec_t abstime);
 196
 197 /*! @function wakeAtTime
 198     @abstract Setup a callback at this absolute time.
 199     @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.
 200     @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
 201     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
 202     virtual IOReturn wakeAtTime(AbsoluteTime abstime);
 203
 204 /*! @function cancelTimeout
 205     @abstract Disable any outstanding calls to this event source.
 206     @discussion Clear down any oustanding calls.  By the time this function completes it is guaranteed that the action will not be called again. */
 207    virtual void cancelTimeout();
 208
 209 private:
 210     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 0);
 211     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 1);
 212     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 2);
 213     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
 214     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
 215     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
 216     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
 217     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
 218 };
 219
 220 #endif /* !_IOTIMEREVENTSOURCE */