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