iokit/IOKit/IOCommandGate.h

   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     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 /*! @struct ExpansionData
  88     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  89     */
  90     struct ExpansionData { };
  91
  92 /*! @var reserved
  93     Reserved for future use.  (Internal use only)  */
  94     ExpansionData *reserved;
  95
  96 public:
  97 /*! @function commandGate
  98     @abstract Factory method to create and initialise an IOCommandGate, See $link init.
  99     @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
 100     static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
 101
 102 /*! @function init
 103     @abstract Class initialiser.
 104     @discussion Initialiser for IOCommandGate operates only on newly 'newed'
 105 objects.  Shouldn't be used to re-init an existing instance.
 106     @param owner        Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
 107     @param action
 108         Pointer to a C function that is called whenever a client of the
 109 IOCommandGate calls runCommand.  NB Can be a C++ member function but caller
 110 must cast the member function to $link IOCommandGate::Action and they will get a
 111 compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
 112     @result True if inherited classes initialise successfully. */
 113     virtual bool init(OSObject *owner, Action action = 0);
 114
 115     // Superclass overrides
 116     virtual void free();
 117     virtual void setWorkLoop(IOWorkLoop *inWorkLoop);
 118
 119 /*! @function runCommand
 120     @abstract Single thread a command with the target work-loop.
 121     @discussion Client function that causes the current action to be called in
 122 a single threaded manner.  Beware the work-loop's gate is recursive and command
 123 gates can cause direct or indirect re-entrancy.  When the executing on a
 124 client's thread runCommand will sleep until the work-loop's gate opens for
 125 execution of client actions, the action is single threaded against all other
 126 work-loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 127     @param arg0 Parameter for action of command gate, defaults to 0.
 128     @param arg1 Parameter for action of command gate, defaults to 0.
 129     @param arg2 Parameter for action of command gate, defaults to 0.
 130     @param arg3 Parameter for action of command gate, defaults to 0.
 131     @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
 132 */
 133     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
 134                                 void *arg2 = 0, void *arg3 = 0);
 135
 136 /*! @function runAction
 137     @abstract Single thread a call to an action with the target work-loop.
 138     @discussion Client function that causes the given action to be called in
 139 a single threaded manner.  Beware the work-loop's gate is recursive and command
 140 gates can cause direct or indirect re-entrancy.  When the executing on a
 141 client's thread runAction will sleep until the work-loop's gate opens for
 142 execution of client actions, the action is single threaded against all other
 143 work-loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 144     @param action Pointer to function to be executed in work-loop context.
 145     @param arg0 Parameter for action parameter, defaults to 0.
 146     @param arg1 Parameter for action parameter, defaults to 0.
 147     @param arg2 Parameter for action parameter, defaults to 0.
 148     @param arg3 Parameter for action parameter, defaults to 0.
 149     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
 150 */
 151     virtual IOReturn runAction(Action action,
 152                                void *arg0 = 0, void *arg1 = 0,
 153                                void *arg2 = 0, void *arg3 = 0);
 154
 155 /*! @function attemptCommand
 156     @abstract Single thread a command with the target work-loop.
 157     @discussion Client function that causes the current action to be called in
 158 a single threaded manner.  When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed.
 159     @param arg0 Parameter for action of command gate, defaults to 0.
 160     @param arg1 Parameter for action of command gate, defaults to 0.
 161     @param arg2 Parameter for action of command gate, defaults to 0.
 162     @param arg3 Parameter for action of command gate, defaults to 0.
 163     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
 164 */
 165     virtual IOReturn attemptCommand(void *arg0 = 0, void *arg1 = 0,
 166                                     void *arg2 = 0, void *arg3 = 0);
 167
 168 /*! @function attemptAction
 169     @abstract Single thread a call to an action with the target work-loop.
 170     @discussion Client function that causes the given action to be called in
 171 a single threaded manner.  Beware the work-loop's gate is recursive and command
 172 gates can cause direct or indirect re-entrancy.  When the executing on a
 173 client's thread attemptCommand will fail if the work-loop's gate is closed.
 174     @param action Pointer to function to be executed in work-loop context.
 175     @param arg0 Parameter for action parameter, defaults to 0.
 176     @param arg1 Parameter for action parameter, defaults to 0.
 177     @param arg2 Parameter for action parameter, defaults to 0.
 178     @param arg3 Parameter for action parameter, defaults to 0.
 179     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
 180
 181 */
 182     virtual IOReturn attemptAction(Action action,
 183                                    void *arg0 = 0, void *arg1 = 0,
 184                                    void *arg2 = 0, void *arg3 = 0);
 185
 186 /*! @function commandSleep
 187     @abstract Put a thread that is currently holding the command gate to sleep.
 188     @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.
 189     @param event Pointer to an address.
 190     @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.
 191     @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. */
 192     virtual IOReturn commandSleep(void *event,
 193                                   UInt32 interruptible = THREAD_ABORTSAFE);
 194
 195 /*! @function commandWakeup
 196     @abstract Wakeup one or more threads that are asleep on an event.
 197     @param event Pointer to an address.
 198     @param onlyOneThread true to only wake up at most one thread, false otherwise. */
 199     virtual void commandWakeup(void *event, bool oneThread = false);
 200
 201 /*! @function disable
 202     @abstract Disable the command gate
 203     @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.  */
 204     virtual void disable();
 205
 206 /*! @function enable
 207     @abstract Enable command gate, this will unblock any blocked Commands and Actions.
 208     @discussion  Enable the command gate.  The attemptAction/attemptCommand calls will now be enabled and can succeeed.  Stalled runCommand/runAction calls will be woken up. */
 209     virtual void enable();
 210
 211 /*! @function commandSleep
 212     @abstract Put a thread that is currently holding the command gate to sleep.
 213     @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.
 214     @param event Pointer to an address.
 215         @param deadline Clock deadline to timeout the sleep.
 216     @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.
 217     @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. */
 218     virtual IOReturn commandSleep(void *event,
 219                                                                   AbsoluteTime deadline,
 220                                   UInt32 interruptible);
 221
 222 private:
 223 #if __LP64__
 224     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
 225 #else
 226     OSMetaClassDeclareReservedUsed(IOCommandGate, 0);
 227 #endif
 228     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
 229     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
 230     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
 231     OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
 232     OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
 233     OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
 234     OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
 235 };
 236
 237 #endif /* !_IOKIT_IOCOMMANDGATE_H */