X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/6601e61aa18bf4f09af135ff61fc7f4771d23b06..3e170ce000f1506b7b5d2c5c7faec85ceabb573d:/iokit/IOKit/IOCommandGate.h diff --git a/iokit/IOKit/IOCommandGate.h b/iokit/IOKit/IOCommandGate.h index 1bb549d8c..26624116f 100644 --- a/iokit/IOKit/IOCommandGate.h +++ b/iokit/IOKit/IOCommandGate.h @@ -1,23 +1,29 @@ /* - * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved. + * Copyright (c) 1998-2009 Apple Inc. All rights reserved. * - * @APPLE_LICENSE_HEADER_START@ + * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * - * The contents of this file constitute Original Code as defined in and - * are subject to the Apple Public Source License Version 1.1 (the - * "License"). You may not use this file except in compliance with the - * License. Please obtain a copy of the License at - * http://www.apple.com/publicsource and read it before using this file. + * 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. * - * This Original Code and all software distributed under the License are - * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * 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 OR NON-INFRINGEMENT. Please see the - * License for the specific language governing rights and limitations - * under the License. + * 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_LICENSE_HEADER_END@ + * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ /*[ 1999-8-10 Godfrey van der Linden(gvdl) @@ -32,14 +38,14 @@ /*! @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 doens't check for a -mutual dead lock though where a pair of work loop's dead lock each other. + @abstract Single-threaded work loop client request mechanism. + @discussion An IOCommandGate instance is an extremely lightweight mechanism +that executes an action on the driver's work loop. Although the code does not +technically execute on the work loop itself, a single-threaded work loop semantic +is maintained for this event source using the work loop gate. 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.

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 @@ -48,7 +54,7 @@ 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.

- CAUTION: The runAction and runCommand functions can not be called from an interrupt context. + CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context. */ class IOCommandGate : public IOEventSource @@ -77,10 +83,6 @@ member function's parameter list. 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. @@ -110,49 +112,50 @@ 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() APPLE_KEXT_OVERRIDE; + virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE; + /*! @function runCommand - @abstract Single thread a command with the target work-loop. + @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 +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 +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. +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. kIOReturnNotPermitted if this -event source is currently disabled, kIOReturnNoResources if no action available. + @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. + @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 +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 +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. - @param action Pointer to function to be executed in work-loop context. +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 the context of the work loop. @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. + @result The return value of action if it was called, 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. + @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 attemptCommand will fail if the work-loop's gate is open. +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. @@ -163,12 +166,12 @@ client's thread attemptCommand will fail if the work-loop's gate is open. void *arg2 = 0, void *arg3 = 0); /*! @function attemptAction - @abstract Single thread a call to an action with the target work-loop. + @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 +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 open. - @param action Pointer to function to be executed in work-loop context. +client's thread attemptCommand will fail if the work loop's gate is closed. + @param action Pointer to function to be executed in context of the work loop. @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. @@ -182,10 +185,10 @@ client's thread attemptCommand will fail if the work-loop's gate is open. /*! @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 returns. + @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, defaults to THREAD_ABORTSAFE. - @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. */ + @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); @@ -195,8 +198,33 @@ client's thread attemptCommand will fail if the work-loop's gate is open. @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() APPLE_KEXT_OVERRIDE; + +/*! @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() APPLE_KEXT_OVERRIDE; + +/*! @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);