The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/iokit/IOKit/IOTimerEventSource.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 /*
    2  * Copyright (c) 1998-2000 Apple Computer, 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     @class IOTimerEventSource : public IOEventSource
   52     @abstract Time based event source mechanism.
   53     @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.
   54 <br><br>
   55         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.
   56 <br><br>
   57         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.
   58 */
   59 class IOTimerEventSource : public IOEventSource
   60 {
   61     OSDeclareDefaultStructors(IOTimerEventSource)
   62 
   63 protected:
   64 /*! @var calloutEntry thread_call entry for preregistered thread callouts */
   65     void *calloutEntry;
   66 
   67 /*! @var abstime time to wake up next, see enable. */
   68     AbsoluteTime abstime;
   69 
   70 /*! @struct ExpansionData
   71     @discussion This structure is private to the IOTimerEventSource implementation.
   72     */    
   73     struct ExpansionData
   74     {
   75         SInt32       calloutGeneration;
   76         IOWorkLoop * workLoop;
   77     };
   78 
   79 /*! @var reserved
   80     Reserved for future use.  (Internal use only)  */
   81     ExpansionData *reserved;
   82 
   83 /*! @function timeout
   84     @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
   85     @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.
   86     @param self This argument will be cast to an IOTimerEventSource. */
   87     static void timeout(void *self);
   88 
   89 /*! @function setTimeoutFunc
   90     @abstract Set's timeout as the function of calloutEntry.
   91     @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. */
   92     virtual void setTimeoutFunc();
   93 
   94 /*! @function free
   95     @abstract Sub-class implementation of free method, frees calloutEntry */
   96     virtual void free();
   97 
   98 /*! @function checkForWork
   99     @abstract Have to implement it is mandatory in $link IOEventSource, but IOTimerEventSources don't actually use this work-loop mechanism. */
  100     virtual bool checkForWork();
  101 
  102     virtual void setWorkLoop(IOWorkLoop *workLoop);
  103 
  104 public:
  105 
  106 /*! @typedef Action
  107     @discussion 'C' Function pointer defining the callout routine of this event source.
  108     @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.
  109     @param sender The object that timed out. */
  110     typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);
  111 
  112 /*! @function timerEventSource
  113     @abstract Allocates and returns an initialized timer instance.
  114     @param owner
  115     @param action */
  116     static IOTimerEventSource *
  117         timerEventSource(OSObject *owner, Action action = 0);
  118 
  119 /*! @function init
  120     @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
  121     @param owner 
  122     @param action */
  123     virtual bool init(OSObject *owner, Action action = 0);
  124 
  125 /*! @function enable
  126     @abstract Enables a call to the action.
  127     @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. */
  128     virtual void enable();
  129 
  130 /*! @function disable
  131     @abstract Disable a timed callout.
  132     @discussion When disable returns the action will not be called until the next time enable(qv) is called. */
  133     virtual void disable();
  134 
  135 
  136 /*! @function setTimeoutTicks
  137     @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).
  138     @param interval Delay from now to wake up, in scheduler ticks, whatever that may be.
  139     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  140     virtual IOReturn setTimeoutTicks(UInt32 ticks);
  141 
  142 /*! @function setTimeoutMS
  143     @abstract Setup a callback at after the delay in milliseconds.  See wakeAtTime(AbsoluteTime).
  144     @param interval Delay from now to wake up, time in milliseconds.
  145     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  146     virtual IOReturn setTimeoutMS(UInt32 ms);
  147 
  148 /*! @function setTimeoutUS
  149         @abstract Setup a callback at after the delay in microseconds.   See wakeAtTime(AbsoluteTime).
  150     @param interval Delay from now to wake up, time in microseconds.
  151     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  152     virtual IOReturn setTimeoutUS(UInt32 us);
  153 
  154 /*! @function setTimeout
  155     @abstract Setup a callback at after the delay in some unit.  See wakeAtTime(AbsoluteTime).
  156     @param interval Delay from now to wake up in some defined unit.
  157     @param scale_factor Define the unit of interval, default to nanoseconds.
  158     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  159     virtual IOReturn setTimeout(UInt32 interval,
  160                                 UInt32 scale_factor = kNanosecondScale);
  161 
  162 /*! @function setTimeout
  163     @abstract Setup a callback at after the delay in decrementer ticks.  See wakeAtTime(AbsoluteTime).
  164     @param interval Delay from now to wake up.
  165     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  166     virtual IOReturn setTimeout(mach_timespec_t interval);
  167 
  168 /*! @function setTimeout
  169     @abstract Setup a callback at after the delay in decrementer ticks.  See wakeAtTime(AbsoluteTime).
  170     @param interval Delay from now to wake up in decrementer ticks.
  171     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  172     virtual IOReturn setTimeout(AbsoluteTime interval);
  173 
  174 /*! @function wakeAtTimeTicks
  175     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
  176     @param abstime Time to wake up in scheduler quantums, whatever that is?
  177     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  178     virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
  179 
  180 /*! @function wakeAtTimeMS
  181     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
  182     @param abstime Time to wake up in milliseconds.
  183     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  184     virtual IOReturn wakeAtTimeMS(UInt32 ms);
  185 
  186 /*! @function wakeAtTimeUS
  187     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
  188     @param abstime Time to wake up in microseconds.
  189     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  190     virtual IOReturn wakeAtTimeUS(UInt32 us);
  191 
  192 /*! @function wakeAtTime
  193     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
  194     @param abstime Time to wake up in some unit.
  195     @param scale_factor Define the unit of abstime, default to nanoseconds.
  196     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  197     virtual IOReturn wakeAtTime(UInt32 abstime,
  198                                 UInt32 scale_factor = kNanosecondScale);
  199 
  200 /*! @function wakeAtTime
  201     @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
  202     @param abstime mach_timespec_t of the desired callout time.
  203     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
  204     virtual IOReturn wakeAtTime(mach_timespec_t abstime);
  205 
  206 /*! @function wakeAtTime
  207     @abstract Setup a callback at this absolute time.
  208     @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.  
  209     @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
  210     @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
  211     virtual IOReturn wakeAtTime(AbsoluteTime abstime);
  212 
  213 /*! @function cancelTimeout
  214     @abstract Disable any outstanding calls to this event source.
  215     @discussion Clear down any oustanding calls.  By the time this function completes it is guaranteed that the action will not be called again. */
  216    virtual void cancelTimeout();
  217 
  218 private:
  219     static void timeoutAndRelease(void *self, void *wl);
  220 
  221 private:
  222     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 0);
  223     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 1);
  224     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 2);
  225     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
  226     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
  227     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
  228     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
  229     OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
  230 };
  231 
  232 #endif /* !_IOTIMEREVENTSOURCE */

Cache object: 42871df6307bb55b215f2e628bdb62fe


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.