1/* 2 * Copyright (c) 1998-2000 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 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 doens'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 and runCommand functions can not be called from an interrupt context. But attemptCommand can, though it may return an error 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 @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 100public: 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' 109objects. 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 113IOCommandGate calls runCommand. NB Can be a C++ member function but caller 114must cast the member function to $link IOCommandGate::Action and they will get a 115compiler 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 126a single threaded manner. Beware the work-loop's gate is recursive and command 127gates can cause direct or indirect re-entrancy. When the executing on a 128client's thread runCommand will sleep until the work-loop's gate opens for 129execution of client actions, the action is single threaded against all other 130work-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 143a single threaded manner. Beware the work-loop's gate is recursive and command 144gates can cause direct or indirect re-entrancy. When the executing on a 145client's thread runAction will sleep until the work-loop's gate opens for 146execution of client actions, the action is single threaded against all other 147work-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 162a 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 175a single threaded manner. Beware the work-loop's gate is recursive and command 176gates can cause direct or indirect re-entrancy. When the executing on a 177client'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 returns. 193 @param event Pointer to an address. 194 @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE, defaults to THREAD_ABORTSAFE. 195 @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted by clear_wait, 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 215private: 216 OSMetaClassDeclareReservedUnused(IOCommandGate, 0); 217 OSMetaClassDeclareReservedUnused(IOCommandGate, 1); 218 OSMetaClassDeclareReservedUnused(IOCommandGate, 2); 219 OSMetaClassDeclareReservedUnused(IOCommandGate, 3); 220 OSMetaClassDeclareReservedUnused(IOCommandGate, 4); 221 OSMetaClassDeclareReservedUnused(IOCommandGate, 5); 222 OSMetaClassDeclareReservedUnused(IOCommandGate, 6); 223 OSMetaClassDeclareReservedUnused(IOCommandGate, 7); 224}; 225 226#endif /* !_IOKIT_IOCOMMANDGATE_H */ 227