xnu-4903.221.2.tar.gz

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

diff --git a/iokit/IOKit/IOCommandGate.h b/iokit/IOKit/IOCommandGate.h
index 1bb549d8cf95976647727d1f477b34be661ab088..431f179d46507dd46fae4d76260c600008b13ac0 100644 (file)
--- 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-2016 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,
  * 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)
  */
 /*[
     1999-8-10  Godfrey van der Linden(gvdl)


@@ -32,14 +38,14 @@
 
 /*!
     @class IOCommandGate : public IOEventSource
 
 /*!
     @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.

 <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
 <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


@@ -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.
 <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


@@ -77,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.


@@ -89,7 +91,9 @@ protected:
 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */
 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */

+    APPLE_KEXT_WSHADOW_PUSH;

     ExpansionData *reserved;
     ExpansionData *reserved;

+    APPLE_KEXT_WSHADOW_POP;

 
 public:
 /*! @function commandGate
 
 public:
 /*! @function commandGate


@@ -110,49 +114,65 @@ 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() APPLE_KEXT_OVERRIDE;
+    virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE;
+

 /*! @function runCommand
 /*! @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
     @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
 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
 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);
 
 /*! @function runAction
 */
     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
     @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
 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
 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.
     @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);
 
 */
     virtual IOReturn runAction(Action action,
                               void *arg0 = 0, void *arg1 = 0,
                               void *arg2 = 0, void *arg3 = 0);
 

+#ifdef __BLOCKS__
+/*! @function runActionBlock
+    @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 Block to be executed in the context of the work loop.
+    @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.
+*/
+    IOReturn runActionBlock(ActionBlock action);
+#endif /* __BLOCKS__ */
+

 /*! @function attemptCommand
 /*! @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
     @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.


@@ -163,12 +183,12 @@ client's thread attemptCommand will fail if the work-loop's gate is open.
                                     void *arg2 = 0, void *arg3 = 0);
 
 /*! @function attemptAction
                                     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
     @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
 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.
     @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,21 +202,46 @@ 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. If the thread does not hold the gate, panic.

     @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. */

     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.
     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. */
+    @param oneThread true to only wake up at most one thread, false otherwise. */

     virtual void commandWakeup(void *event, bool oneThread = false);
 
     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.  If the thread does not hold the gate, panic.
+    @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. */
+    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);