| 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 */␊ |
| 242 | |
