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 43that executes an action on the driver's work-loop. 'On the work-loop' is 44actually a lie but the work-loop single threaded semantic is maintained for this 45event source. Using the work-loop gate rather than execution by the workloop. 46The command gate tests for a potential self dead lock by checking if the 47runCommand request is made from the work-loop's thread, it doesn't check for a 48mutual 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 51should be used in preference. Generally use a command queue whenever you need a 52client to submit a request to a work loop. A typical command gate action would 53check if the hardware is active, if so it will add the request to a pending 54queue internal to the device or the device's family. Otherwise if the hardware 55is 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*/ 60class IOCommandGate : public IOEventSource 61{ 62 OSDeclareDefaultStructors(IOCommandGate) 63 64public: 65/*! 66 @typedef Action 67 @discussion Type and arguments of callout C function that is used when 68a runCommand is executed by a client. Cast to this type when you want a C++ 69member function to be used. Note the arg1 - arg3 parameters are straight pass 70through 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 73during initialisation of the IOCommandGate instance. Note if a C++ function 74was specified this parameter is implicitly the first paramter in the target 75member 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 85protected: 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 96public: 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' 105objects. 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 109IOCommandGate calls runCommand. NB Can be a C++ member function but caller 110must cast the member function to $link IOCommandGate::Action and they will get a 111compiler 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 122a single threaded manner. Beware the work-loop's gate is recursive and command 123gates can cause direct or indirect re-entrancy. When the executing on a 124client's thread runCommand will sleep until the work-loop's gate opens for 125execution of client actions, the action is single threaded against all other 126work-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 139a single threaded manner. Beware the work-loop's gate is recursive and command 140gates can cause direct or indirect re-entrancy. When the executing on a 141client's thread runAction will sleep until the work-loop's gate opens for 142execution of client actions, the action is single threaded against all other 143work-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 158a 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 171a single threaded manner. Beware the work-loop's gate is recursive and command 172gates can cause direct or indirect re-entrancy. When the executing on a 173client'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 222private: 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 */ 238