iokit/IOKit/IOWorkLoop.h

   1 /*
   2  * Copyright (c) 1998-2009 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 #ifndef __IOKIT_IOWORKLOOP_H
  30 #define __IOKIT_IOWORKLOOP_H
  31
  32 #include <libkern/c++/OSObject.h>
  33 #include <IOKit/IOReturn.h>
  34 #include <IOKit/IOLib.h>
  35 #include <IOKit/IOLocks.h>
  36
  37 #include <IOKit/system.h>
  38
  39 #if IOKITSTATS
  40 #include <IOKit/IOStatisticsPrivate.h>
  41 #endif
  42
  43 class IOEventSource;
  44 class IOTimerEventSource;
  45 class IOCommandGate;
  46
  47 /*! @class IOWorkLoop
  48     @discussion An IOWorkLoop is a thread of control that is intended to be used to provide single threaded access to hardware.  This class has no knowledge of the nature and type of the events that it marshals and forwards.  When a device driver successfully starts (see IOService::start), it is expected to create the event sources it will need to receive events.  Then a work loop is initialized and the events are added to the work loop for monitoring.  In general this set up will be automated by the family superclass of the specific device.
  49 <br><br>
  50         The thread main method walks the event source linked list and messages each one requesting a work check.  At this point each event source is expected to notify its registered owner that the event has occurred.  After each event has been walked and each indicates that another loop isn't required (by setting the 'more' flag to false) the thread will go to sleep on a signaling semaphore.
  51 <br><br>
  52         When an event source is registered with a work loop it is informed of the semaphore to use to wake up the loop.
  53 */
  54 class IOWorkLoop : public OSObject
  55 {
  56     OSDeclareDefaultStructors(IOWorkLoop)
  57
  58 public:
  59 /*!
  60     @typedef Action
  61     @discussion Type and arguments of callout C function that is used when
  62 a runCommand is executed by a client.  Cast to this type when you want a C++
  63 member function to be used.  Note the arg1 - arg3 parameters are straight pass
  64 through from the runCommand to the action callout.
  65     @param target
  66         Target of the function, can be used as a refcon.  Note if a C++ function
  67 was specified, this parameter is implicitly the first parameter in the target
  68 member function's parameter list.
  69     @param arg0 Argument to action from run operation.
  70     @param arg1 Argument to action from run operation.
  71     @param arg2 Argument to action from run operation.
  72     @param arg3 Argument to action from run operation.
  73 */
  74     typedef IOReturn (*Action)(OSObject *target,
  75                                void *arg0, void *arg1,
  76                                void *arg2, void *arg3);
  77     enum {
  78         kPreciousStack  = 0x00000001,
  79         kTimeLockPanics = 0x00000002,
  80     };
  81
  82 private:
  83 /*! @function threadMainContinuation
  84     @abstract Static function that calls the threadMain function.
  85 */
  86     static void threadMainContinuation(IOWorkLoop *self);
  87
  88 /*! @function eventSourcePerformsWork
  89         @abstract Checks if the event source passed in overrides checkForWork() to perform any work.
  90 IOWorkLoop uses this to determine if the event source should be polled in runEventSources() or not.
  91         @param inEventSource The event source to check.
  92 */
  93         bool eventSourcePerformsWork(IOEventSource *inEventSource);
  94
  95 protected:
  96
  97 /*! @typedef maintCommandEnum
  98     @discussion Enumeration of commands that _maintCommand can deal with.
  99     @constant mAddEvent Used to tag a Remove event source command.
 100     @constant mRemoveEvent Used to tag a Remove event source command.
 101 */
 102     typedef enum { mAddEvent, mRemoveEvent } maintCommandEnum;
 103
 104 /*! @var gateLock
 105     Mutual exclusion lock that is used by close and open Gate functions.
 106     This is a recursive lock, which allows multiple layers of code to share a single IOWorkLoop without deadlock.  This is common in IOKit since threads of execution tend to follow the service plane in the IORegistry, and multiple objects along the call path may acquire the gate for the same (shared) workloop.
 107 */
 108     IORecursiveLock *gateLock;
 109
 110 /*! @var eventChain
 111     Pointer to first event source in linked list.
 112 */
 113     IOEventSource *eventChain;
 114
 115 /*! @var controlG
 116     Internal control gate to maintain event system.
 117 */
 118     IOCommandGate *controlG;
 119
 120 /*! @var workToDoLock
 121     The spin lock that is used to guard the 'workToDo' variable.
 122 */
 123     IOSimpleLock *workToDoLock;
 124
 125 /*! @var workThread
 126     Work loop thread.
 127 */
 128     IOThread workThread;
 129
 130 /*! @var workToDo
 131     Used to to indicate that an interrupt has fired and needs to be processed.
 132 */
 133     volatile bool workToDo;
 134
 135 /*! @var loopRestart
 136     Set if an event chain has been changed and the system has to be rechecked from start.  (Internal use only)
 137 */
 138     bool loopRestart;
 139
 140 /*! @struct ExpansionData
 141     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
 142 */
 143     struct ExpansionData {
 144         IOOptionBits options;
 145         IOEventSource *passiveEventChain;
 146 #if DEBUG
 147         void * allocationBacktrace[16];
 148 #endif /* DEBUG */
 149 #if IOKITSTATS
 150         struct IOWorkLoopCounter *counter;
 151 #else
 152         void *iokitstatsReserved;
 153 #endif
 154         uint64_t lockInterval;
 155         uint64_t lockTime;
 156     };
 157
 158 /*! @var reserved
 159     Reserved for future use.  (Internal use only)
 160 */
 161     ExpansionData *reserved;
 162
 163 /*! @function _maintRequest
 164     @abstract Synchronous implementation of addEventSource and removeEventSource functions.
 165     @discussion This function implements the commands as defined in the maintCommandEnum.  It can be subclassed but it isn't an external API in the usual sense.  A subclass implementation of _maintRequest would be called synchronously with respect to the work loop and it should be implemented in the usual way that an ioctl would be.
 166     @return kIOReturnUnsupported if the command given is not implemented, kIOReturnSuccess otherwise.
 167 */
 168     virtual IOReturn _maintRequest(void *command, void *data, void *, void *);
 169
 170 /*! @function free
 171     @discussion Mandatory free of the object independent of the current retain count.  If the work loop is running, this method will not return until the thread has successfully terminated.  Each event source in the chain will be released and the working semaphore will be destroyed.
 172 <br><br>
 173         If the client has some outstanding requests on an event they will never be informed of completion.  If an external thread is blocked on any of the event sources they will be awakened with a KERN_INTERUPTED status.
 174 */
 175     virtual void free() APPLE_KEXT_OVERRIDE;
 176
 177 /*! @function threadMain
 178     @discussion Work loop threads main function.  This function consists of 3
 179     loops: the outermost loop is the semaphore clear and wait loop, the middle
 180     loop terminates when there is no more work, and the inside loop walks the
 181     event list calling the checkForWork method in each event source.  If an
 182     event source has more work to do, it can set the more flag and the middle
 183     loop will repeat.  When no more work is outstanding the outermost will
 184     sleep until an event is signalled.
 185 */
 186     virtual void threadMain();
 187
 188 public:
 189
 190 /*! @function workLoop
 191     @abstract Factory member function to construct and intialize a work loop.
 192     @result Returns a workLoop instance if constructed successfully, 0 otherwise.
 193 */
 194     static IOWorkLoop *workLoop();
 195
 196 /*! @function workLoopWithOptions(IOOptionBits options)
 197     @abstract Factory member function to constuct and intialize a work loop.
 198     @param options Options - kPreciousStack to avoid stack deallocation on paging path.
 199     @result Returns a workLoop instance if constructed successfully, 0 otherwise.
 200 */
 201     static IOWorkLoop *workLoopWithOptions(IOOptionBits options);
 202
 203 /*! @function init
 204     @discussion Initializes an instance of the workloop.  This method creates and initializes the signaling semaphore, the controller gate lock, and spawns the thread that will continue executing.
 205     @result Returns true if initialized successfully, false otherwise.
 206 */
 207     virtual bool init() APPLE_KEXT_OVERRIDE;
 208
 209 /*! @function getThread
 210     @abstract Gets the workThread.
 211     @result Returns workThread.
 212 */
 213     virtual IOThread getThread() const;
 214
 215 /*! @function onThread
 216     @abstract Is the current execution context on the work thread?
 217     @result Returns true if IOThreadSelf() == workThread.
 218 */
 219     virtual bool onThread() const;
 220
 221 /*! @function inGate
 222     @abstract Is the current execution context holding the work-loop's gate?
 223     @result Returns true if IOThreadSelf() is gate holder.
 224 */
 225     virtual bool inGate() const;
 226
 227 /*! @function addEventSource
 228     @discussion Add an event source to be monitored by the work loop.  This function does not return until the work loop has acknowledged the arrival of the new event source.  When a new event has been added the threadMain will always restart its loop and check all outstanding events.  The event source is retained by the work loop.
 229     @param newEvent Pointer to IOEventSource subclass to add.
 230     @result Always returns kIOReturnSuccess.
 231 */
 232     virtual IOReturn addEventSource(IOEventSource *newEvent);
 233
 234 /*! @function removeEventSource
 235     @discussion Remove an event source from the work loop.  This function does not return until the work loop has acknowledged the removal of the event source.  When an event has been removed the threadMain will always restart its loop and check all outstanding events.  The event source will be released before return.
 236     @param toRemove Pointer to IOEventSource subclass to remove.
 237     @result Returns kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found.
 238 */
 239     virtual IOReturn removeEventSource(IOEventSource *toRemove);
 240
 241 /*! @function enableAllEventSources
 242     @abstract Calls enable() in all event sources.
 243     @discussion For all event sources in eventChain, call enable() function.  See IOEventSource::enable().
 244 */
 245     virtual void enableAllEventSources() const;
 246
 247 /*! @function disableAllEventSources
 248     @abstract Calls disable() in all event sources.
 249     @discussion For all event sources in eventChain, call disable() function.  See IOEventSource::disable().
 250 */
 251     virtual void disableAllEventSources() const;
 252
 253 /*! @function enableAllInterrupts
 254     @abstract Calls enable() in all interrupt event sources.
 255     @discussion For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call enable() function.  See IOEventSource::enable().
 256 */
 257     virtual void enableAllInterrupts() const;
 258
 259 /*! @function disableAllInterrupts
 260     @abstract Calls disable() in all interrupt event sources.
 261     @discussion For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid,  in eventChain call disable() function.  See IOEventSource::disable().
 262 */
 263     virtual void disableAllInterrupts() const;
 264
 265
 266 protected:
 267     // Internal APIs used by event sources to control the thread
 268     friend class IOEventSource;
 269     friend class IOTimerEventSource;
 270     friend class IOCommandGate;
 271 #if IOKITSTATS
 272     friend class IOStatistics;
 273 #endif
 274     virtual void signalWorkAvailable();
 275     virtual void openGate();
 276     virtual void closeGate();
 277     virtual bool tryCloseGate();
 278     virtual int  sleepGate(void *event, UInt32 interuptibleType);
 279     virtual void wakeupGate(void *event, bool oneThread);
 280
 281 public:
 282     /* methods available in Mac OS X 10.1 or later */
 283
 284 /*! @function runAction
 285     @abstract Single thread a call to an action with the work-loop.
 286     @discussion Client function that causes the given action to be called in a single threaded manner.  Beware: the work-loop's gate is recursive and runAction can cause direct or indirect re-entrancy.  When executing on a client's thread, runAction will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources.
 287     @param action Pointer to function to be executed in work-loop context.
 288     @param arg0 Parameter for action parameter, defaults to 0.
 289     @param arg1 Parameter for action parameter, defaults to 0.
 290     @param arg2 Parameter for action parameter, defaults to 0.
 291     @param arg3 Parameter for action parameter, defaults to 0.
 292     @result Returns the value of the Action callout.
 293 */
 294     virtual IOReturn runAction(Action action, OSObject *target,
 295                                void *arg0 = 0, void *arg1 = 0,
 296                                void *arg2 = 0, void *arg3 = 0);
 297
 298 /*! @function runEventSources
 299     @discussion Consists of the inner 2 loops of the threadMain function(qv).
 300     The outer loop terminates when there is no more work, and the inside loop
 301     walks the event list calling the checkForWork method in each event source.
 302     If an event source has more work to do, it can set the more flag and the
 303     outer loop will repeat.
 304 <br><br>
 305     This function can be used to clear a priority inversion between the normal
 306     workloop thread and multimedia's real time threads.  The problem is that
 307     the interrupt action routine is often held off by high priority threads.
 308     So if they want to get their data now they will have to call us and ask if
 309     any data is available.  The multi-media user client will arrange for this
 310     function to be called, which causes any pending interrupts to be processed
 311     and the completion routines called.  By the time the function returns all
 312     outstanding work will have been completed at the real time threads
 313     priority.
 314
 315     @result Return false if the work loop is shutting down, true otherwise.
 316 */
 317     virtual bool runEventSources();
 318
 319 /*! @function setMaximumLockTime
 320     @discussion For diagnostics use in DEVELOPMENT kernels, set a time interval which if the work loop lock is held for this time or greater, IOWorkLoop will panic or log a backtrace.
 321     @param interval An absolute time interval, eg. created with clock_interval_to_absolutetime_interval().
 322     @param options Pass IOWorkLoop::kTimeLockPanics to panic when the time is exceeded, otherwise a log will be generated with OSReportWithBacktrace().
 323 */
 324     void setMaximumLockTime(uint64_t interval, uint32_t options);
 325
 326 protected:
 327     // Internal APIs used by event sources to control the thread
 328     virtual int sleepGate(void *event, AbsoluteTime deadline, UInt32 interuptibleType);
 329
 330 #if XNU_KERNEL_PRIVATE
 331     void lockTime(void);
 332 #endif /* XNU_KERNEL_PRIVATE */
 333
 334 protected:
 335 #if __LP64__
 336     OSMetaClassDeclareReservedUnused(IOWorkLoop, 0);
 337     OSMetaClassDeclareReservedUnused(IOWorkLoop, 1);
 338     OSMetaClassDeclareReservedUnused(IOWorkLoop, 2);
 339 #else
 340     OSMetaClassDeclareReservedUsed(IOWorkLoop, 0);
 341     OSMetaClassDeclareReservedUsed(IOWorkLoop, 1);
 342     OSMetaClassDeclareReservedUsed(IOWorkLoop, 2);
 343 #endif
 344     OSMetaClassDeclareReservedUnused(IOWorkLoop, 3);
 345     OSMetaClassDeclareReservedUnused(IOWorkLoop, 4);
 346     OSMetaClassDeclareReservedUnused(IOWorkLoop, 5);
 347     OSMetaClassDeclareReservedUnused(IOWorkLoop, 6);
 348     OSMetaClassDeclareReservedUnused(IOWorkLoop, 7);
 349 };
 350
 351 #endif /* !__IOKIT_IOWORKLOOP_H */