iokit/IOKit/IOCommandGate.h

   1 /*
   2  * Copyright (c) 1998-2009 Apple Computer, 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     1999-8-10   Godfrey van der Linden(gvdl)
  30         Created.
  31 ]*/
  32 /*! @language embedded-c++ */
  33
  34 #ifndef _IOKIT_IOCOMMANDGATE_H
  35 #define _IOKIT_IOCOMMANDGATE_H
  36
  37 #include <IOKit/IOEventSource.h>
  38
  39 /*!
  40     @class IOCommandGate : public IOEventSource
  41     @abstract Single-threaded work-loop client request mechanism.
  42     @discussion An IOCommandGate instance is an extremely light way mechanism
  43 that executes an action on the driver's work-loop.  'On the work-loop' is
  44 actually a lie but the work-loop single threaded semantic is maintained for this
  45 event source.  Using the work-loop gate rather than execution by the workloop.
  46 The command gate tests for a potential self dead lock by checking if the
  47 runCommand request is made from the work-loop's thread, it doesn't check for a
  48 mutual dead lock though where a pair of work loop's dead lock each other.
  49 <br><br>
  50         The IOCommandGate is a lighter weight version of the IOCommandQueue and
  51 should be used in preference.  Generally use a command queue whenever you need a
  52 client to submit a request to a work loop.  A typical command gate action would
  53 check if the hardware is active, if so it will add the request to a pending
  54 queue internal to the device or the device's family.  Otherwise if the hardware
  55 is inactive then this request can be acted upon immediately.
  56 <br><br>
  57     CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context.
  58
  59 */
  60 class IOCommandGate : public IOEventSource
  61 {
  62     OSDeclareDefaultStructors(IOCommandGate)
  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 owner
  72         Target of the function, can be used as a refcon.  The owner is set
  73 during initialisation of the IOCommandGate instance.     Note if a C++ function
  74 was specified this parameter is implicitly the first paramter in the target
  75 member function's parameter list.
  76     @param arg0 Argument to action from run operation.
  77     @param arg1 Argument to action from run operation.
  78     @param arg2 Argument to action from run operation.
  79     @param arg3 Argument to action from run operation.
  80 */
  81     typedef IOReturn (*Action)(OSObject *owner,
  82                                void *arg0, void *arg1,
  83                                void *arg2, void *arg3);
  84
  85 protected:
  86 /*!
  87     @function checkForWork
  88     @abstract Not used, $link IOEventSource::checkForWork(). */
  89     virtual bool checkForWork();
  90
  91 /*! @struct ExpansionData
  92     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  93     */
  94     struct ExpansionData { };
  95
  96 /*! @var reserved
  97     Reserved for future use.  (Internal use only)  */
  98     ExpansionData *reserved;
  99
 100 public:
 101 /*! @function commandGate
 102     @abstract Factory method to create and initialise an IOCommandGate, See $link init.
 103     @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
 104     static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
 105
 106 /*! @function init
 107     @abstract Class initialiser.
 108     @discussion Initialiser for IOCommandGate operates only on newly 'newed'
 109 objects.  Shouldn't be used to re-init an existing instance.
 110     @param owner        Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
 111     @param action
 112         Pointer to a C function that is called whenever a client of the
 113 IOCommandGate calls runCommand.  NB Can be a C++ member function but caller
 114 must cast the member function to $link IOCommandGate::Action and they will get a
 115 compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
 116     @result True if inherited classes initialise successfully. */
 117     virtual bool init(OSObject *owner, Action action = 0);
 118
 119     // Superclass overrides
 120     virtual void free();
 121     virtual void setWorkLoop(IOWorkLoop *inWorkLoop);
 122
 123 /*! @function runCommand
 124     @abstract Single thread a command with the target work-loop.
 125     @discussion Client function that causes the current action to be called in
 126 a single threaded manner.  Beware the work-loop's gate is recursive and command
 127 gates can cause direct or indirect re-entrancy.  When the executing on a
 128 client's thread runCommand will sleep until the work-loop's gate opens for
 129 execution of client actions, the action is single threaded against all other
 130 work-loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 131     @param arg0 Parameter for action of command gate, defaults to 0.
 132     @param arg1 Parameter for action of command gate, defaults to 0.
 133     @param arg2 Parameter for action of command gate, defaults to 0.
 134     @param arg3 Parameter for action of command gate, defaults to 0.
 135     @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
 136 */
 137     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
 138                                 void *arg2 = 0, void *arg3 = 0);
 139
 140 /*! @function runAction
 141     @abstract Single thread a call to an action with the target work-loop.
 142     @discussion Client function that causes the given action to be called in
 143 a single threaded manner.  Beware the work-loop's gate is recursive and command
 144 gates can cause direct or indirect re-entrancy.  When the executing on a
 145 client's thread runAction will sleep until the work-loop's gate opens for
 146 execution of client actions, the action is single threaded against all other
 147 work-loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 148     @param action Pointer to function to be executed in work-loop context.
 149     @param arg0 Parameter for action parameter, defaults to 0.
 150     @param arg1 Parameter for action parameter, defaults to 0.
 151     @param arg2 Parameter for action parameter, defaults to 0.
 152     @param arg3 Parameter for action parameter, defaults to 0.
 153     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
 154 */
 155     virtual IOReturn runAction(Action action,
 156                                void *arg0 = 0, void *arg1 = 0,
 157                                void *arg2 = 0, void *arg3 = 0);
 158
 159 /*! @function attemptCommand
 160     @abstract Single thread a command with the target work-loop.
 161     @discussion Client function that causes the current action to be called in
 162 a single threaded manner.  When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed.
 163     @param arg0 Parameter for action of command gate, defaults to 0.
 164     @param arg1 Parameter for action of command gate, defaults to 0.
 165     @param arg2 Parameter for action of command gate, defaults to 0.
 166     @param arg3 Parameter for action of command gate, defaults to 0.
 167     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
 168 */
 169     virtual IOReturn attemptCommand(void *arg0 = 0, void *arg1 = 0,
 170                                     void *arg2 = 0, void *arg3 = 0);
 171
 172 /*! @function attemptAction
 173     @abstract Single thread a call to an action with the target work-loop.
 174     @discussion Client function that causes the given action to be called in
 175 a single threaded manner.  Beware the work-loop's gate is recursive and command
 176 gates can cause direct or indirect re-entrancy.  When the executing on a
 177 client's thread attemptCommand will fail if the work-loop's gate is closed.
 178     @param action Pointer to function to be executed in work-loop context.
 179     @param arg0 Parameter for action parameter, defaults to 0.
 180     @param arg1 Parameter for action parameter, defaults to 0.
 181     @param arg2 Parameter for action parameter, defaults to 0.
 182     @param arg3 Parameter for action parameter, defaults to 0.
 183     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
 184
 185 */
 186     virtual IOReturn attemptAction(Action action,
 187                                    void *arg0 = 0, void *arg1 = 0,
 188                                    void *arg2 = 0, void *arg3 = 0);
 189
 190 /*! @function commandSleep
 191     @abstract Put a thread that is currently holding the command gate to sleep.
 192     @discussion Put a thread to sleep waiting for an event but release the gate first.  If the event occurs then the commandGate is closed before the function returns.
 193     @param event Pointer to an address.
 194     @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE.  THREAD_UNINT specifies that the sleep cannot be interrupted by a signal.  THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal.  THREAD_ABORTSAFE (the default value) specifies that the sleep may be interrupted by any user signal.
 195     @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely, kIOReturnNotPermitted if the calling thread does not hold the command gate. */
 196     virtual IOReturn commandSleep(void *event,
 197                                   UInt32 interruptible = THREAD_ABORTSAFE);
 198
 199 /*! @function commandWakeup
 200     @abstract Wakeup one or more threads that are asleep on an event.
 201     @param event Pointer to an address.
 202     @param onlyOneThread true to only wake up at most one thread, false otherwise. */
 203     virtual void commandWakeup(void *event, bool oneThread = false);
 204
 205 /*! @function disable
 206     @abstract Disable the command gate
 207     @discussion When a command gate is disabled all future calls to runAction and runCommand will stall until the gate is enable()d later.  This can be used to block client threads when a system sleep is requested.  The IOWorkLoop thread itself will never stall, even when making runAction/runCommand calls.  This call must be made from a gated context, to clear potential race conditions.  */
 208     virtual void disable();
 209
 210 /*! @function enable
 211     @abstract Enable command gate, this will unblock any blocked Commands and Actions.
 212     @discussion  Enable the command gate.  The attemptAction/attemptCommand calls will now be enabled and can succeeed.  Stalled runCommand/runAction calls will be woken up. */
 213     virtual void enable();
 214
 215 /*! @function commandSleep
 216     @abstract Put a thread that is currently holding the command gate to sleep.
 217     @discussion Put a thread to sleep waiting for an event but release the gate first.  If the event occurs or timeout occurs then the commandGate is closed before the function returns.
 218     @param event Pointer to an address.
 219         @param deadline Clock deadline to timeout the sleep.
 220     @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE.  THREAD_UNINT specifies that the sleep cannot be interrupted by a signal.  THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal.  THREAD_ABORTSAFE specifies that the sleep may be interrupted by any user signal.
 221     @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely, kIOReturnNotPermitted if the calling thread does not hold the command gate. */
 222     virtual IOReturn commandSleep(void *event,
 223                                                                   AbsoluteTime deadline,
 224                                   UInt32 interruptible);
 225
 226 private:
 227 #if __LP64__
 228     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
 229 #else
 230     OSMetaClassDeclareReservedUsed(IOCommandGate, 0);
 231 #endif
 232     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
 233     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
 234     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
 235     OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
 236     OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
 237     OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
 238     OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
 239 };
 240
 241 #endif /* !_IOKIT_IOCOMMANDGATE_H */