xnu-2782.40.9.tar.gz

[apple/xnu.git] / iokit / IOKit / IOCommandGate.h

diff --git a/iokit/IOKit/IOCommandGate.h b/iokit/IOKit/IOCommandGate.h
index 13b6baccc594f7762a35084244b1068afc6d2d4b..d38c88670f020b78219f7338f52c9cb4dab214a3 100644 (file)
--- a/iokit/IOKit/IOCommandGate.h
+++ b/iokit/IOKit/IOCommandGate.h
@@ -1,31 +1,29 @@
 /*
 /*

- * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 1998-2009 Apple Inc. All rights reserved.

  *
  *

- * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
+ * @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 
+ * 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.
  * limitations under the License.

- *
- * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
+ * 
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@

  */
 /*[
     1999-8-10  Godfrey van der Linden(gvdl)
  */
 /*[
     1999-8-10  Godfrey van der Linden(gvdl)


@@ -46,7 +44,7 @@ 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
 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
+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
 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


@@ -56,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.
 <br><br>
 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 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
 
 */
 class IOCommandGate : public IOEventSource


@@ -85,10 +83,6 @@ member function's parameter list.
                               void *arg2, void *arg3);
 
 protected:
                               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
     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.


@@ -118,6 +112,10 @@ compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
     @result True if inherited classes initialise successfully. */
     virtual bool init(OSObject *owner, Action action = 0);
 
     @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
 /*! @function runCommand
     @abstract Single thread a command with the target work-loop.
     @discussion Client function that causes the current action to be called in


@@ -125,13 +123,12 @@ 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
 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.
+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.
     @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);
 */
     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
                                void *arg2 = 0, void *arg3 = 0);


@@ -143,13 +140,13 @@ 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
 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.
+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.
     @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.
+    @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,
 */
     virtual IOReturn runAction(Action action,
                               void *arg0 = 0, void *arg1 = 0,


@@ -158,9 +155,7 @@ work-loop event sources.
 /*! @function attemptCommand
     @abstract Single thread a command with the target work-loop.
     @discussion Client function that causes the current action to be called in
 /*! @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.  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.
     @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.


@@ -175,7 +170,7 @@ client's thread attemptCommand will fail if the work-loop's gate is open.
     @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
     @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 open.
+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 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.


@@ -190,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.
 
 /*! @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 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);
 
     virtual IOReturn commandSleep(void *event,
                                   UInt32 interruptible = THREAD_ABORTSAFE);
 


@@ -203,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);
 
     @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:
 private:

+#if __LP64__

     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);

+#else
+    OSMetaClassDeclareReservedUsed(IOCommandGate, 0);
+#endif

     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);