iokit/IOKit/IOWorkLoop.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /*
  31 Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  32 HISTORY
  33     1998-7-13   Godfrey van der Linden(gvdl)
  34         Created.
  35     1998-10-30  Godfrey van der Linden(gvdl)
  36         Converted to C++
  37 */
  38
  39 #ifndef __IOKIT_IOWORKLOOP_H
  40 #define __IOKIT_IOWORKLOOP_H
  41
  42 #include <libkern/c++/OSObject.h>
  43 #include <IOKit/IOReturn.h>
  44 #include <IOKit/IOLib.h>
  45 #include <IOKit/IOLocks.h>
  46
  47 #include <IOKit/system.h>
  48
  49 class IOEventSource;
  50 class IOTimerEventSource;
  51 class IOCommandGate;
  52
  53 /*! @class IOWorkLoop
  54     @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.
  55 <br><br>
  56         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.
  57 <br><br>
  58         When an event source is registered with a work loop it is informed of the semaphore to use to wake up the loop.
  59 */
  60 class IOWorkLoop : public OSObject
  61 {
  62     OSDeclareDefaultStructors(IOWorkLoop)
  63
  64 public:
  65 /*!
  66     @typedef Action
  67     @discussion Type and arguments of callout C function that is used when
  68 a runCommand is executed by a client.  Cast to this type when you want a C++
  69 member function to be used.  Note the arg1 - arg3 parameters are straight pass
  70 through from the runCommand to the action callout.
  71     @param target
  72         Target of the function, can be used as a refcon.  Note if a C++ function
  73 was specified, this parameter is implicitly the first parameter in the target
  74 member function's parameter list.
  75     @param arg0 Argument to action from run operation.
  76     @param arg1 Argument to action from run operation.
  77     @param arg2 Argument to action from run operation.
  78     @param arg3 Argument to action from run operation.
  79 */
  80     typedef IOReturn (*Action)(OSObject *target,
  81                                void *arg0, void *arg1,
  82                                void *arg2, void *arg3);
  83
  84 private:
  85 /*! @function threadMainContinuation
  86     @abstract Static function that calls the threadMain function.
  87 */
  88     static void threadMainContinuation(IOWorkLoop *self);
  89
  90 protected:
  91
  92 /*! @typedef maintCommandEnum
  93     @discussion Enumeration of commands that _maintCommand can deal with.
  94     @constant mAddEvent Used to tag a Remove event source command.
  95     @constant mRemoveEvent Used to tag a Remove event source command.
  96 */
  97     typedef enum { mAddEvent, mRemoveEvent } maintCommandEnum;
  98
  99 /*! @var gateLock
 100     Mutual exclusion lock that is used by close and open Gate functions.
 101 */
 102     IORecursiveLock *gateLock;
 103
 104 /*! @var eventChain
 105     Pointer to first event source in linked list.
 106 */
 107     IOEventSource *eventChain;
 108
 109 /*! @var controlG
 110     Internal control gate to maintain event system.
 111 */
 112     IOCommandGate *controlG;
 113
 114 /*! @var workSpinLock
 115     The spin lock that is used to guard the 'workToDo' variable.
 116 */
 117     IOSimpleLock *workToDoLock;
 118
 119 /*! @var workThread
 120     Work loop thread.
 121 */
 122     IOThread workThread;
 123
 124 /*! @var workToDo
 125     Used to to indicate that an interrupt has fired and needs to be processed.
 126 */
 127     volatile bool workToDo;
 128
 129 /*! @var loopRestart
 130     Set if an event chain has been changed and the system has to be rechecked from start.  (Internal use only)
 131 */
 132     bool loopRestart;
 133
 134 /*! @struct ExpansionData
 135     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
 136 */
 137     struct ExpansionData { };
 138
 139 /*! @var reserved
 140     Reserved for future use.  (Internal use only)
 141 */
 142     ExpansionData *reserved;
 143
 144 /*! @function _maintRequest
 145     @abstract Synchronous implementation of addEventSource and removeEventSource functions.
 146     @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.
 147     @return kIOReturnUnsupported if the command given is not implemented, kIOReturnSuccess otherwise.
 148 */
 149     virtual IOReturn _maintRequest(void *command, void *data, void *, void *);
 150
 151 /*! @function free
 152     @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.
 153 <br><br>
 154         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.
 155 */
 156     virtual void free();
 157
 158 /*! @function threadMain
 159     @discussion Work loop threads main function.  This function consists of 3 loops: the outermost loop is the semaphore clear and wait loop, the middle loop terminates when there is no more work, and the inside loop walks the event list calling the checkForWork method in each event source.  If an event source has more work to do, it can set the more flag and the middle loop will repeat.  When no more work is outstanding the outermost will sleep until an event is signalled or the least wakeupTime, whichever occurs first.  If the event source does not require the semaphore wait to time out, it must set the provided wakeupTime parameter to zero.
 160 */
 161     virtual void threadMain();
 162
 163 public:
 164
 165 /*! @function workLoop
 166     @abstract Factory member function to constuct and intialize a work loop.
 167     @result Returns a workLoop instance if constructed successfully, 0 otherwise.
 168 */
 169     static IOWorkLoop *workLoop();
 170
 171 /*! @function init
 172     @discussion Initializes an instance of the workloop.  This method creates and initialses the signaling semaphore and forks the thread that will continue executing.
 173     @result Returns true if initialized successfully, false otherwise.
 174 */
 175     virtual bool init();
 176
 177 /*! @function getThread
 178     @abstract Gets the workThread.
 179     @result Returns workThread.
 180 */
 181     virtual IOThread getThread() const;
 182
 183 /*! @function onThread
 184     @abstract Is the current execution context on the work thread?
 185     @result Returns true if IOThreadSelf() == workThread.
 186 */
 187     virtual bool onThread() const;
 188
 189 /*! @function inGate
 190     @abstract Is the current execution context holding the work-loop's gate?
 191     @result Returns true if IOThreadSelf() is gate holder.
 192 */
 193     virtual bool inGate() const;
 194
 195 /*! @function addEventSource
 196     @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.
 197     @param newEvent Pointer to IOEventSource subclass to add.
 198     @result Always returns kIOReturnSuccess.
 199 */
 200     virtual IOReturn addEventSource(IOEventSource *newEvent);
 201
 202 /*! @function removeEventSource
 203     @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.
 204     @param toRemove Pointer to IOEventSource subclass to remove.
 205     @result Returns kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found.
 206 */
 207     virtual IOReturn removeEventSource(IOEventSource *toRemove);
 208
 209 /*! @function enableAllEventSources
 210     @abstract Calls enable() in all event sources.
 211     @discussion For all event sources in eventChain, call enable() function.  See IOEventSource::enable().
 212 */
 213     virtual void enableAllEventSources() const;
 214
 215 /*! @function disableAllEventSources
 216     @abstract Calls disable() in all event sources.
 217     @discussion For all event sources in eventChain, call disable() function.  See IOEventSource::disable().
 218 */
 219     virtual void disableAllEventSources() const;
 220
 221 /*! @function enableAllInterrupts
 222     @abstract Calls enable() in all interrupt event sources.
 223     @discussion For all event sources (ES) for which IODynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call enable() function.  See IOEventSource::enable().
 224 */
 225     virtual void enableAllInterrupts() const;
 226
 227 /*! @function disableAllInterrupts
 228     @abstract Calls disable() in all interrupt event sources.
 229     @discussion For all event sources (ES) for which IODynamicCast(IOInterruptEventSource, ES) is valid,  in eventChain call disable() function.  See IOEventSource::disable().
 230 */
 231     virtual void disableAllInterrupts() const;
 232
 233
 234 protected:
 235     // Internal APIs used by event sources to control the thread
 236     friend class IOEventSource;
 237     friend class IOTimerEventSource;
 238     virtual void signalWorkAvailable();
 239     virtual void openGate();
 240     virtual void closeGate();
 241     virtual bool tryCloseGate();
 242     virtual int sleepGate(void *event, UInt32 interuptibleType);
 243     virtual void wakeupGate(void *event, bool oneThread);
 244
 245 public:
 246     /* methods available in Mac OS X 10.1 or later */
 247
 248 /*! @function runAction
 249     @abstract Single thread a call to an action with the work-loop.
 250     @discussion Client function that causes the given action to be called in
 251 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
 252 execution of client actions, the action is single threaded against all other work-loop event sources.
 253     @param action Pointer to function to be executed in work-loop context.
 254     @param arg0 Parameter for action parameter, defaults to 0.
 255     @param arg1 Parameter for action parameter, defaults to 0.
 256     @param arg2 Parameter for action parameter, defaults to 0.
 257     @param arg3 Parameter for action parameter, defaults to 0.
 258     @result Returns the value of the Action callout.
 259 */
 260     virtual IOReturn runAction(Action action, OSObject *target,
 261                                void *arg0 = 0, void *arg1 = 0,
 262                                void *arg2 = 0, void *arg3 = 0);
 263
 264 protected:
 265     OSMetaClassDeclareReservedUsed(IOWorkLoop, 0);
 266
 267     OSMetaClassDeclareReservedUnused(IOWorkLoop, 1);
 268     OSMetaClassDeclareReservedUnused(IOWorkLoop, 2);
 269     OSMetaClassDeclareReservedUnused(IOWorkLoop, 3);
 270     OSMetaClassDeclareReservedUnused(IOWorkLoop, 4);
 271     OSMetaClassDeclareReservedUnused(IOWorkLoop, 5);
 272     OSMetaClassDeclareReservedUnused(IOWorkLoop, 6);
 273     OSMetaClassDeclareReservedUnused(IOWorkLoop, 7);
 274 };
 275
 276 #endif /* !__IOKIT_IOWORKLOOP_H */