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 43class IOEventSource; 44class IOTimerEventSource; 45class 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*/ 54class IOWorkLoop : public OSObject 55{ 56 OSDeclareDefaultStructors(IOWorkLoop) 57 58public: 59/*! 60 @typedef Action 61 @discussion Type and arguments of callout C function that is used when 62a runCommand is executed by a client. Cast to this type when you want a C++ 63member function to be used. Note the arg1 - arg3 parameters are straight pass 64through 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 67was specified, this parameter is implicitly the first parameter in the target 68member 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 }; 80 81private: 82/*! @function threadMainContinuation 83 @abstract Static function that calls the threadMain function. 84*/ 85 static void threadMainContinuation(IOWorkLoop *self); 86 87/*! @function eventSourcePerformsWork 88 @abstract Checks if the event source passed in overrides checkForWork() to perform any work. 89IOWorkLoop uses this to determine if the event source should be polled in runEventSources() or not. 90 @param inEventSource The event source to check. 91*/ 92 bool eventSourcePerformsWork(IOEventSource *inEventSource); 93 94protected: 95 96/*! @typedef maintCommandEnum 97 @discussion Enumeration of commands that _maintCommand can deal with. 98 @constant mAddEvent Used to tag a Remove event source command. 99 @constant mRemoveEvent Used to tag a Remove event source command. 100*/ 101 typedef enum { mAddEvent, mRemoveEvent } maintCommandEnum; 102 103/*! @var gateLock 104 Mutual exclusion lock that is used by close and open Gate functions. 105 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. 106*/ 107 IORecursiveLock *gateLock; 108 109/*! @var eventChain 110 Pointer to first event source in linked list. 111*/ 112 IOEventSource *eventChain; 113 114/*! @var controlG 115 Internal control gate to maintain event system. 116*/ 117 IOCommandGate *controlG; 118 119/*! @var workToDoLock 120 The spin lock that is used to guard the 'workToDo' variable. 121*/ 122 IOSimpleLock *workToDoLock; 123 124/*! @var workThread 125 Work loop thread. 126*/ 127 IOThread workThread; 128 129/*! @var workToDo 130 Used to to indicate that an interrupt has fired and needs to be processed. 131*/ 132 volatile bool workToDo; 133 134/*! @var loopRestart 135 Set if an event chain has been changed and the system has to be rechecked from start. (Internal use only) 136*/ 137 bool loopRestart; 138 139/*! @struct ExpansionData 140 @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future. 141*/ 142 struct ExpansionData { 143 IOOptionBits options; 144 IOEventSource *passiveEventChain; 145#if DEBUG 146 void * allocationBacktrace[16]; 147#endif /* DEBUG */ 148#if IOKITSTATS 149 struct IOWorkLoopCounter *counter; 150#else 151 void *iokitstatsReserved; 152#endif 153 }; 154 155/*! @var reserved 156 Reserved for future use. (Internal use only) 157*/ 158 ExpansionData *reserved; 159 160/*! @function _maintRequest 161 @abstract Synchronous implementation of addEventSource and removeEventSource functions. 162 @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. 163 @return kIOReturnUnsupported if the command given is not implemented, kIOReturnSuccess otherwise. 164*/ 165 virtual IOReturn _maintRequest(void *command, void *data, void *, void *); 166 167/*! @function free 168 @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. 169<br><br> 170 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. 171*/ 172 virtual void free(); 173 174/*! @function threadMain 175 @discussion Work loop threads main function. This function consists of 3 176 loops: the outermost loop is the semaphore clear and wait loop, the middle 177 loop terminates when there is no more work, and the inside loop walks the 178 event list calling the checkForWork method in each event source. If an 179 event source has more work to do, it can set the more flag and the middle 180 loop will repeat. When no more work is outstanding the outermost will 181 sleep until an event is signalled. 182*/ 183 virtual void threadMain(); 184 185public: 186 187/*! @function workLoop 188 @abstract Factory member function to construct and intialize a work loop. 189 @result Returns a workLoop instance if constructed successfully, 0 otherwise. 190*/ 191 static IOWorkLoop *workLoop(); 192 193/*! @function workLoopWithOptions(IOOptionBits options) 194 @abstract Factory member function to constuct and intialize a work loop. 195 @param options Options - kPreciousStack to avoid stack deallocation on paging path. 196 @result Returns a workLoop instance if constructed successfully, 0 otherwise. 197*/ 198 static IOWorkLoop *workLoopWithOptions(IOOptionBits options); 199 200/*! @function init 201 @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. 202 @result Returns true if initialized successfully, false otherwise. 203*/ 204 virtual bool init(); 205 206/*! @function getThread 207 @abstract Gets the workThread. 208 @result Returns workThread. 209*/ 210 virtual IOThread getThread() const; 211 212/*! @function onThread 213 @abstract Is the current execution context on the work thread? 214 @result Returns true if IOThreadSelf() == workThread. 215*/ 216 virtual bool onThread() const; 217 218/*! @function inGate 219 @abstract Is the current execution context holding the work-loop's gate? 220 @result Returns true if IOThreadSelf() is gate holder. 221*/ 222 virtual bool inGate() const; 223 224/*! @function addEventSource 225 @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. 226 @param newEvent Pointer to IOEventSource subclass to add. 227 @result Always returns kIOReturnSuccess. 228*/ 229 virtual IOReturn addEventSource(IOEventSource *newEvent); 230 231/*! @function removeEventSource 232 @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. 233 @param toRemove Pointer to IOEventSource subclass to remove. 234 @result Returns kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found. 235*/ 236 virtual IOReturn removeEventSource(IOEventSource *toRemove); 237 238/*! @function enableAllEventSources 239 @abstract Calls enable() in all event sources. 240 @discussion For all event sources in eventChain, call enable() function. See IOEventSource::enable(). 241*/ 242 virtual void enableAllEventSources() const; 243 244/*! @function disableAllEventSources 245 @abstract Calls disable() in all event sources. 246 @discussion For all event sources in eventChain, call disable() function. See IOEventSource::disable(). 247*/ 248 virtual void disableAllEventSources() const; 249 250/*! @function enableAllInterrupts 251 @abstract Calls enable() in all interrupt event sources. 252 @discussion For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call enable() function. See IOEventSource::enable(). 253*/ 254 virtual void enableAllInterrupts() const; 255 256/*! @function disableAllInterrupts 257 @abstract Calls disable() in all interrupt event sources. 258 @discussion For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call disable() function. See IOEventSource::disable(). 259*/ 260 virtual void disableAllInterrupts() const; 261 262 263protected: 264 // Internal APIs used by event sources to control the thread 265 friend class IOEventSource; 266 friend class IOTimerEventSource; 267#if IOKITSTATS 268 friend class IOStatistics; 269#endif 270 virtual void signalWorkAvailable(); 271 virtual void openGate(); 272 virtual void closeGate(); 273 virtual bool tryCloseGate(); 274 virtual int sleepGate(void *event, UInt32 interuptibleType); 275 virtual void wakeupGate(void *event, bool oneThread); 276 277public: 278 /* methods available in Mac OS X 10.1 or later */ 279 280/*! @function runAction 281 @abstract Single thread a call to an action with the work-loop. 282 @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. 283 @param action Pointer to function to be executed in work-loop context. 284 @param arg0 Parameter for action parameter, defaults to 0. 285 @param arg1 Parameter for action parameter, defaults to 0. 286 @param arg2 Parameter for action parameter, defaults to 0. 287 @param arg3 Parameter for action parameter, defaults to 0. 288 @result Returns the value of the Action callout. 289*/ 290 virtual IOReturn runAction(Action action, OSObject *target, 291 void *arg0 = 0, void *arg1 = 0, 292 void *arg2 = 0, void *arg3 = 0); 293 294/*! @function runEventSources 295 @discussion Consists of the inner 2 loops of the threadMain function(qv). 296 The outer loop terminates when there is no more work, and the inside loop 297 walks the event list calling the checkForWork method in each event source. 298 If an event source has more work to do, it can set the more flag and the 299 outer loop will repeat. 300<br><br> 301 This function can be used to clear a priority inversion between the normal 302 workloop thread and multimedia's real time threads. The problem is that 303 the interrupt action routine is often held off by high priority threads. 304 So if they want to get their data now they will have to call us and ask if 305 any data is available. The multi-media user client will arrange for this 306 function to be called, which causes any pending interrupts to be processed 307 and the completion routines called. By the time the function returns all 308 outstanding work will have been completed at the real time threads 309 priority. 310 311 @result Return false if the work loop is shutting down, true otherwise. 312*/ 313 virtual bool runEventSources(); 314 315protected: 316 // Internal APIs used by event sources to control the thread 317 virtual int sleepGate(void *event, AbsoluteTime deadline, UInt32 interuptibleType); 318 319protected: 320#if __LP64__ 321 OSMetaClassDeclareReservedUnused(IOWorkLoop, 0); 322 OSMetaClassDeclareReservedUnused(IOWorkLoop, 1); 323 OSMetaClassDeclareReservedUnused(IOWorkLoop, 2); 324#else 325 OSMetaClassDeclareReservedUsed(IOWorkLoop, 0); 326 OSMetaClassDeclareReservedUsed(IOWorkLoop, 1); 327 OSMetaClassDeclareReservedUsed(IOWorkLoop, 2); 328#endif 329 OSMetaClassDeclareReservedUnused(IOWorkLoop, 3); 330 OSMetaClassDeclareReservedUnused(IOWorkLoop, 4); 331 OSMetaClassDeclareReservedUnused(IOWorkLoop, 5); 332 OSMetaClassDeclareReservedUnused(IOWorkLoop, 6); 333 OSMetaClassDeclareReservedUnused(IOWorkLoop, 7); 334}; 335 336#endif /* !__IOKIT_IOWORKLOOP_H */ 337