/* * Copyright (c) 1998-2009 Apple Computer, Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ /*[ 1999-8-10 Godfrey van der Linden(gvdl) Created. ]*/ /*! @language embedded-c++ */ #ifndef _IOKIT_IOCOMMANDGATE_H #define _IOKIT_IOCOMMANDGATE_H #include <IOKit/IOEventSource.h> /*! @class IOCommandGate : public IOEventSource @abstract Single-threaded work-loop client request mechanism. @discussion An IOCommandGate instance is an extremely light way mechanism that executes an action on the driver's work-loop. 'On the work-loop' is actually a lie but the work-loop single threaded semantic is maintained for this event source. Using the work-loop gate rather than execution by the workloop. The command gate tests for a potential self dead lock by checking if the runCommand request is made from the work-loop's thread, it doesn't check for a mutual dead lock though where a pair of work loop's dead lock each other. <br><br> The IOCommandGate is a lighter weight version of the IOCommandQueue and should be used in preference. Generally use a command queue whenever you need a client to submit a request to a work loop. A typical command gate action would check if the hardware is active, if so it will add the request to a pending queue internal to the device or the device's family. Otherwise if the hardware is inactive then this request can be acted upon immediately. <br><br> CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context. */ class IOCommandGate : public IOEventSource { OSDeclareDefaultStructors(IOCommandGate) public: /*! @typedef Action @discussion Type and arguments of callout C function that is used when a runCommand is executed by a client. Cast to this type when you want a C++ member function to be used. Note the arg1 - arg3 parameters are straight pass through from the runCommand to the action callout. @param owner Target of the function, can be used as a refcon. The owner is set during initialisation of the IOCommandGate instance. Note if a C++ function was specified this parameter is implicitly the first paramter in the target member function's parameter list. @param arg0 Argument to action from run operation. @param arg1 Argument to action from run operation. @param arg2 Argument to action from run operation. @param arg3 Argument to action from run operation. */ typedef IOReturn (*Action)(OSObject *owner, void *arg0, void *arg1, void *arg2, void *arg3); protected: /*! @function checkForWork @abstract Not used, $link IOEventSource::checkForWork(). */ virtual bool checkForWork(); /*! @struct ExpansionData @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future. */ struct ExpansionData { }; /*! @var reserved Reserved for future use. (Internal use only) */ ExpansionData *reserved; public: /*! @function commandGate @abstract Factory method to create and initialise an IOCommandGate, See $link init. @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */ static IOCommandGate *commandGate(OSObject *owner, Action action = 0); /*! @function init @abstract Class initialiser. @discussion Initialiser for IOCommandGate operates only on newly 'newed' objects. Shouldn't be used to re-init an existing instance. @param owner Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout. @param action Pointer to a C function that is called whenever a client of the IOCommandGate calls runCommand. NB Can be a C++ member function but caller must cast the member function to $link IOCommandGate::Action and they will get a compiler warning. Defaults to zero, see $link IOEventSource::setAction. @result True if inherited classes initialise successfully. */ virtual bool init(OSObject *owner, Action action = 0); // Superclass overrides virtual void free(); virtual void setWorkLoop(IOWorkLoop *inWorkLoop); /*! @function runCommand @abstract Single thread a command with the target work-loop. @discussion Client function that causes the current action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread runCommand will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called. @param arg0 Parameter for action of command gate, defaults to 0. @param arg1 Parameter for action of command gate, defaults to 0. @param arg2 Parameter for action of command gate, defaults to 0. @param arg3 Parameter for action of command gate, defaults to 0. @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available. */ virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0, void *arg2 = 0, void *arg3 = 0); /*! @function runAction @abstract Single thread a call to an action with the target work-loop. @discussion Client function that causes the given action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread runAction will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called. @param action Pointer to function to be executed in work-loop context. @param arg0 Parameter for action parameter, defaults to 0. @param arg1 Parameter for action parameter, defaults to 0. @param arg2 Parameter for action parameter, defaults to 0. @param arg3 Parameter for action parameter, defaults to 0. @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled. */ virtual IOReturn runAction(Action action, void *arg0 = 0, void *arg1 = 0, void *arg2 = 0, void *arg3 = 0); /*! @function attemptCommand @abstract Single thread a command with the target work-loop. @discussion Client function that causes the current action to be called in a single threaded manner. When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed. @param arg0 Parameter for action of command gate, defaults to 0. @param arg1 Parameter for action of command gate, defaults to 0. @param arg2 Parameter for action of command gate, defaults to 0. @param arg3 Parameter for action of command gate, defaults to 0. @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails. */ virtual IOReturn attemptCommand(void *arg0 = 0, void *arg1 = 0, void *arg2 = 0, void *arg3 = 0); /*! @function attemptAction @abstract Single thread a call to an action with the target work-loop. @discussion Client function that causes the given action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed. @param action Pointer to function to be executed in work-loop context. @param arg0 Parameter for action parameter, defaults to 0. @param arg1 Parameter for action parameter, defaults to 0. @param arg2 Parameter for action parameter, defaults to 0. @param arg3 Parameter for action parameter, defaults to 0. @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails. */ virtual IOReturn attemptAction(Action action, void *arg0 = 0, void *arg1 = 0, void *arg2 = 0, void *arg3 = 0); /*! @function commandSleep @abstract Put a thread that is currently holding the command gate to sleep. @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. @param event Pointer to an address. @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. @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. */ virtual IOReturn commandSleep(void *event, UInt32 interruptible = THREAD_ABORTSAFE); /*! @function commandWakeup @abstract Wakeup one or more threads that are asleep on an event. @param event Pointer to an address. @param onlyOneThread true to only wake up at most one thread, false otherwise. */ virtual void commandWakeup(void *event, bool oneThread = false); /*! @function disable @abstract Disable the command gate @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. */ virtual void disable(); /*! @function enable @abstract Enable command gate, this will unblock any blocked Commands and Actions. @discussion Enable the command gate. The attemptAction/attemptCommand calls will now be enabled and can succeeed. Stalled runCommand/runAction calls will be woken up. */ virtual void enable(); /*! @function commandSleep @abstract Put a thread that is currently holding the command gate to sleep. @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. @param event Pointer to an address. @param deadline Clock deadline to timeout the sleep. @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. @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. */ virtual IOReturn commandSleep(void *event, AbsoluteTime deadline, UInt32 interruptible); private: #if __LP64__ OSMetaClassDeclareReservedUnused(IOCommandGate, 0); #else OSMetaClassDeclareReservedUsed(IOCommandGate, 0); #endif OSMetaClassDeclareReservedUnused(IOCommandGate, 1); OSMetaClassDeclareReservedUnused(IOCommandGate, 2); OSMetaClassDeclareReservedUnused(IOCommandGate, 3); OSMetaClassDeclareReservedUnused(IOCommandGate, 4); OSMetaClassDeclareReservedUnused(IOCommandGate, 5); OSMetaClassDeclareReservedUnused(IOCommandGate, 6); OSMetaClassDeclareReservedUnused(IOCommandGate, 7); }; #endif /* !_IOKIT_IOCOMMANDGATE_H */