iokit/IOKit/IOWorkLoop.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23 Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  24 HISTORY
  25     1998-7-13   Godfrey van der Linden(gvdl)
  26         Created.
  27     1998-10-30  Godfrey van der Linden(gvdl)
  28         Converted to C++
  29 */
  30
  31 #ifndef __IOKIT_IOWORKLOOP_H
  32 #define __IOKIT_IOWORKLOOP_H
  33
  34 #include <libkern/c++/OSObject.h>
  35 #include <IOKit/IOReturn.h>
  36 #include <IOKit/IOLib.h>
  37 #include <IOKit/IOLocks.h>
  38
  39 #include <IOKit/system.h>
  40
  41 class IOEventSource;
  42 class IOCommandGate;
  43
  44 /*! @class IOWorkLoop : public OSObject
  45     @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 an device driver sucessfully starts, See $link IOService::start it is expected to create the event sources it will need to receive events from.  Then a work loop is initialised 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.
  46 <br><br>
  47         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 their registered owner that the event has occured.  After each event has been walked and they indicate that another loop isn't required by the 'more' flag being false the thread will go to sleep on a signaling semaphore.
  48 <br><br>
  49         When an event source is registered with a work loop it is informed of the semaphore to use to wake up the loop.*/
  50 class IOWorkLoop : public OSObject
  51 {
  52     OSDeclareDefaultStructors(IOWorkLoop)
  53
  54 public:
  55 /*!
  56     @typedef Action
  57     @discussion Type and arguments of callout C function that is used when
  58 a runCommand is executed by a client.  Cast to this type when you want a C++
  59 member function to be used.  Note the arg1 - arg3 parameters are straight pass
  60 through from the runCommand to the action callout.
  61     @param target
  62         Target of the function, can be used as a refcon.  Note if a C++ function
  63 was specified this parameter is implicitly the first paramter in the target
  64 member function's parameter list.
  65     @param arg0 Argument to action from run operation.
  66     @param arg1 Argument to action from run operation.
  67     @param arg2 Argument to action from run operation.
  68     @param arg3 Argument to action from run operation.
  69 */
  70     typedef IOReturn (*Action)(OSObject *target,
  71                                void *arg0, void *arg1,
  72                                void *arg2, void *arg3);
  73
  74 private:
  75 /*! @function launchThreadMain
  76     @abstract Static function that setup thread state and calls the continuation function, $link threadMainContinuation */
  77     static void launchThreadMain(void *self);
  78
  79 /*! @function threadMainContinuation
  80     @abstract Static function that calls the $link threadMain function. */
  81     static void threadMainContinuation();
  82
  83 protected:
  84
  85 /*! @typedef maintCommandEnum
  86     @discussion Enumeration of commands that $link _maintCommand can deal with.
  87     @enum
  88     @constant mAddEvent Used to tag a Remove event source command.
  89     @constant mRemoveEvent Used to tag a Remove event source command. */
  90     typedef enum { mAddEvent, mRemoveEvent } maintCommandEnum;
  91
  92 /*! @var gateLock
  93     Mutual exlusion lock that used by close and open Gate functions.  */
  94     IORecursiveLock *gateLock;
  95
  96 /*! @var eventChain Pointer to first Event Source in linked list.  */
  97     IOEventSource *eventChain;
  98
  99 /*! @var controlG Internal control gate to maintain event system.  */
 100     IOCommandGate *controlG;
 101
 102 /*! @var workSpinLock
 103     The spin lock that is used to guard the 'workToDo' variable.  */
 104     IOSimpleLock *workToDoLock;
 105
 106 /*! @var workThread Work loop thread.    */
 107     IOThread workThread;
 108
 109 /*! @var workToDo
 110     Used to to indicate that an interrupt has fired and needs to be processed.
 111 */
 112     volatile bool workToDo;
 113
 114 /*! @var loopRestart
 115     If event chain has been changed and the system has to be rechecked from start this flag is set.  (Internal use only)  */
 116     bool loopRestart;
 117
 118 /*! @struct ExpansionData
 119     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
 120     */
 121     struct ExpansionData { };
 122
 123 /*! @var reserved
 124     Reserved for future use.  (Internal use only)  */
 125     ExpansionData *reserved;
 126
 127 /*! @function _maintRequest
 128     @abstract Synchrounous implementation of $link addEventSource & $link removeEventSource functions. */
 129     virtual IOReturn _maintRequest(void *command, void *data, void *, void *);
 130
 131 /*! @function free
 132     @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 succefully terminated.  Each event source in the chain will be released and the working semaphore will be destroyed.
 133 <br><br>
 134         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 awoken with a KERN_INTERUPTED status. */
 135     virtual void free();
 136
 137 /*! @function threadMain
 138     @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 $link checkForWork method in each event source.  If an event source has more work to do then it can set the more flag and the middle loop will repeat.  When no more work is outstanding the outermost will sleep until and event is signaled 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. */
 139     virtual void threadMain();
 140
 141 public:
 142
 143 /*! @function workLoop
 144     @abstract Factory member function to constuct and intialise a work loop.
 145     @result workLoop instance if constructed successfully, 0 otherwise. */
 146     static IOWorkLoop *workLoop();
 147
 148 /*! @function init
 149     @description
 150     Initialises an instance of the workloop.  This method creates and initialses the signaling semaphore and forks the thread that will continue executing.
 151     @result true if initialised successfully, false otherwise. */
 152     virtual bool init();
 153
 154 /*! @function getThread
 155     @abstract Get'ter for $link workThread.
 156     @result Returns workThread */
 157     virtual IOThread getThread() const;
 158
 159 /*! @function onThread
 160     @abstract Is the current execution context on the work thread?
 161     @result Returns true if IOThreadSelf() == workThread. */
 162     virtual bool onThread() const;
 163
 164 /*! @function inGate
 165     @abstract Is the current execution context holding the work-loop's gate?
 166     @result Returns true if IOThreadSelf() is gate holder. */
 167     virtual bool inGate() const;
 168
 169 /*! @function addEventSource
 170     @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 it's loop and check all outstanding events.  The event source is retained by the work loop
 171     @param newEvent Pointer to $link IOEventSource subclass to add.
 172     @result Always returns kIOReturnSuccess. */
 173     virtual IOReturn addEventSource(IOEventSource *newEvent);
 174
 175 /*! @function removeEventSource
 176     @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 it's loop and check all outstanding events.  The event source will be released before return.
 177     @param toRemove Pointer to $link IOEventSource subclass to remove.
 178     @result kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found. */
 179     virtual IOReturn removeEventSource(IOEventSource *toRemove);
 180
 181 /*! @function enableAllEventSources
 182     @abstract Call enable() in all event sources
 183     @discussion For all event sources in $link eventChain call enable() function.  See $link IOEventSource::enable()  */
 184     virtual void enableAllEventSources() const;
 185
 186 /*! @function disableAllEventSources
 187     @abstract Call disable() in all event sources
 188     @discussion For all event sources in $link eventChain call disable() function.  See $link IOEventSource::disable() */
 189     virtual void disableAllEventSources() const;
 190
 191 /*! @function enableAllInterrupts
 192     @abstract Call enable() in all interrupt event sources
 193     @discussion For all event sources, ES, for which IODynamicCast(IOInterruptEventSource, ES) is valid, in $link eventChain call enable() function.  See $link IOEventSource::enable()  */
 194     virtual void enableAllInterrupts() const;
 195
 196 /*! @function disableAllInterrupts
 197     @abstract Call disable() in all interrupt event sources
 198     @discussion For all event sources, ES, for which IODynamicCast(IOInterruptEventSource, ES) is valid,  in $link eventChain call disable() function.  See $link IOEventSource::disable() */
 199     virtual void disableAllInterrupts() const;
 200
 201
 202 protected:
 203     // Internal APIs used by event sources to control the thread
 204     friend class IOEventSource;
 205     virtual void signalWorkAvailable();
 206     virtual void openGate();
 207     virtual void closeGate();
 208     virtual bool tryCloseGate();
 209     virtual int sleepGate(void *event, UInt32 interuptibleType);
 210     virtual void wakeupGate(void *event, bool oneThread);
 211
 212 public:
 213     /* methods available in Mac OS X 10.1 or later */
 214
 215 /*! @function runAction
 216     @abstract Single thread a call to an action with the work-loop.
 217     @discussion Client function that causes the given action to be called in
 218 a single threaded manner.  Beware the work-loop's gate is recursive and runAction
 219  can cause direct or indirect re-entrancy.       When the executing on a
 220 client's thread runAction will sleep until the work-loop's gate opens for
 221 execution of client actions, the action is single threaded against all other
 222 work-loop event sources.
 223     @param action Pointer to function to be executed in work-loop context.
 224     @param arg0 Parameter for action parameter, defaults to 0.
 225     @param arg1 Parameter for action parameter, defaults to 0.
 226     @param arg2 Parameter for action parameter, defaults to 0.
 227     @param arg3 Parameter for action parameter, defaults to 0.
 228     @result return value of the Action callout.
 229 */
 230     virtual IOReturn runAction(Action action, OSObject *target,
 231                                void *arg0 = 0, void *arg1 = 0,
 232                                void *arg2 = 0, void *arg3 = 0);
 233
 234 protected:
 235     OSMetaClassDeclareReservedUsed(IOWorkLoop, 0);
 236
 237     OSMetaClassDeclareReservedUnused(IOWorkLoop, 1);
 238     OSMetaClassDeclareReservedUnused(IOWorkLoop, 2);
 239     OSMetaClassDeclareReservedUnused(IOWorkLoop, 3);
 240     OSMetaClassDeclareReservedUnused(IOWorkLoop, 4);
 241     OSMetaClassDeclareReservedUnused(IOWorkLoop, 5);
 242     OSMetaClassDeclareReservedUnused(IOWorkLoop, 6);
 243     OSMetaClassDeclareReservedUnused(IOWorkLoop, 7);
 244 };
 245
 246 #endif /* !__IOKIT_IOWORKLOOP_H */