iokit/IOKit/IOCommandGate.h

   1 /*
   2  * Copyright (c) 1998-2019 Apple 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 #include <libkern/c++/OSPtr.h>
  39
  40 /*!
  41  *   @class IOCommandGate : public IOEventSource
  42  *   @abstract Single-threaded work loop client request mechanism.
  43  *   @discussion An IOCommandGate instance is an extremely lightweight mechanism
  44  *  that executes an action on the driver's work loop.  Although the code does not
  45  *  technically execute on the work loop itself, a single-threaded work loop semantic
  46  *  is maintained for this event source using the work loop gate.  The command gate
  47  *  tests for a potential self dead lock by checking if the runCommand request is
  48  *  made from the work loop's thread, it doesn't check for a mutual dead lock though
  49  *  where a pair of work loop's dead lock each other.
  50  *  <br><br>
  51  *       The IOCommandGate is a lighter weight version of the IOCommandQueue and
  52  *  should be used in preference.  Generally use a command queue whenever you need a
  53  *  client to submit a request to a work loop.  A typical command gate action would
  54  *  check if the hardware is active, if so it will add the request to a pending
  55  *  queue internal to the device or the device's family.  Otherwise if the hardware
  56  *  is inactive then this request can be acted upon immediately.
  57  *  <br><br>
  58  *   CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context.
  59  *
  60  */
  61 class IOCommandGate : public IOEventSource
  62 {
  63         OSDeclareDefaultStructors(IOCommandGate);
  64
  65 public:
  66 /*!
  67  *   @typedef Action
  68  *   @discussion Type and arguments of callout C function that is used when
  69  *  a runCommand is executed by a client.  Cast to this type when you want a C++
  70  *  member function to be used.  Note the arg1 - arg3 parameters are straight pass
  71  *  through from the runCommand to the action callout.
  72  *   @param owner
  73  *       Target of the function, can be used as a refcon.  The owner is set
  74  *  during initialisation of the IOCommandGate instance.         Note if a C++ function
  75  *  was specified this parameter is implicitly the first paramter in the target
  76  *  member function's parameter list.
  77  *   @param arg0 Argument to action from run operation.
  78  *   @param arg1 Argument to action from run operation.
  79  *   @param arg2 Argument to action from run operation.
  80  *   @param arg3 Argument to action from run operation.
  81  */
  82         typedef IOReturn (*Action)(OSObject *owner,
  83             void *arg0, void *arg1,
  84             void *arg2, void *arg3);
  85
  86 protected:
  87
  88 /*! @struct ExpansionData
  89  *   @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  90  */
  91         struct ExpansionData { };
  92
  93 /*! @var reserved
  94  *   Reserved for future use.  (Internal use only)  */
  95         APPLE_KEXT_WSHADOW_PUSH;
  96         ExpansionData *reserved;
  97         APPLE_KEXT_WSHADOW_POP;
  98
  99 public:
 100 /*! @function commandGate
 101  *   @abstract Factory method to create and initialise an IOCommandGate, See $link init.
 102  *   @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
 103         static OSPtr<IOCommandGate> commandGate(OSObject *owner, Action action = NULL);
 104
 105 /*! @function init
 106  *   @abstract Class initialiser.
 107  *   @discussion Initialiser for IOCommandGate operates only on newly 'newed'
 108  *  objects.  Shouldn't be used to re-init an existing instance.
 109  *   @param owner       Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
 110  *   @param action
 111  *       Pointer to a C function that is called whenever a client of the
 112  *  IOCommandGate calls runCommand.      NB Can be a C++ member function but caller
 113  *  must cast the member function to $link IOCommandGate::Action and they will get a
 114  *  compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
 115  *   @result True if inherited classes initialise successfully. */
 116         virtual bool init(OSObject *owner, Action action = NULL);
 117
 118 // Superclass overrides
 119         virtual void free() APPLE_KEXT_OVERRIDE;
 120         virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE;
 121
 122 /*! @function runCommand
 123  *   @abstract Single thread a command with the target work loop.
 124  *   @discussion Client function that causes the current action to be called in
 125  *  a single threaded manner.  Beware the work loop's gate is recursive and command
 126  *  gates can cause direct or indirect re-entrancy.      When the executing on a
 127  *  client's thread runCommand will sleep until the work loop's gate opens for
 128  *  execution of client actions, the action is single threaded against all other
 129  *  work loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 130  *   @param arg0 Parameter for action of command gate, defaults to 0.
 131  *   @param arg1 Parameter for action of command gate, defaults to 0.
 132  *   @param arg2 Parameter for action of command gate, defaults to 0.
 133  *   @param arg3 Parameter for action of command gate, defaults to 0.
 134  *   @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
 135  */
 136         virtual IOReturn runCommand(void *arg0 = NULL, void *arg1 = NULL,
 137             void *arg2 = NULL, void *arg3 = NULL);
 138
 139 /*! @function runAction
 140  *   @abstract Single thread a call to an action with the target work loop.
 141  *   @discussion Client function that causes the given action to be called in
 142  *  a single threaded manner.  Beware the work loop's gate is recursive and command
 143  *  gates can cause direct or indirect re-entrancy.      When the executing on a
 144  *  client's thread runAction will sleep until the work loop's gate opens for
 145  *  execution of client actions, the action is single threaded against all other
 146  *  work loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 147  *   @param action Pointer to function to be executed in the context of the work loop.
 148  *   @param arg0 Parameter for action parameter, defaults to 0.
 149  *   @param arg1 Parameter for action parameter, defaults to 0.
 150  *   @param arg2 Parameter for action parameter, defaults to 0.
 151  *   @param arg3 Parameter for action parameter, defaults to 0.
 152  *   @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.
 153  */
 154         virtual IOReturn runAction(Action action,
 155             void *arg0 = NULL, void *arg1 = NULL,
 156             void *arg2 = NULL, void *arg3 = NULL);
 157
 158 #ifdef __BLOCKS__
 159 /*! @function runActionBlock
 160  *   @abstract Single thread a call to an action with the target work loop.
 161  *   @discussion Client function that causes the given action to be called in
 162  *  a single threaded manner.  Beware the work loop's gate is recursive and command
 163  *  gates can cause direct or indirect re-entrancy.      When the executing on a
 164  *  client's thread runAction will sleep until the work loop's gate opens for
 165  *  execution of client actions, the action is single threaded against all other
 166  *  work loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 167  *   @param action Block to be executed in the context of the work loop.
 168  *   @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.
 169  */
 170         IOReturn runActionBlock(ActionBlock action);
 171 #endif /* __BLOCKS__ */
 172
 173 /*! @function attemptCommand
 174  *   @abstract Single thread a command with the target work loop.
 175  *   @discussion Client function that causes the current action to be called in
 176  *  a single threaded manner.  When the executing on a client's thread attemptCommand will fail if the work loop's gate is closed.
 177  *   @param arg0 Parameter for action of command gate, defaults to 0.
 178  *   @param arg1 Parameter for action of command gate, defaults to 0.
 179  *   @param arg2 Parameter for action of command gate, defaults to 0.
 180  *   @param arg3 Parameter for action of command gate, defaults to 0.
 181  *   @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
 182  */
 183         virtual IOReturn attemptCommand(void *arg0 = NULL, void *arg1 = NULL,
 184             void *arg2 = NULL, void *arg3 = NULL);
 185
 186 /*! @function attemptAction
 187  *   @abstract Single thread a call to an action with the target work loop.
 188  *   @discussion Client function that causes the given action to be called in
 189  *  a single threaded manner.  Beware the work loop's gate is recursive and command
 190  *  gates can cause direct or indirect re-entrancy.      When the executing on a
 191  *  client's thread attemptCommand will fail if the work loop's gate is closed.
 192  *   @param action Pointer to function to be executed in context of the work loop.
 193  *   @param arg0 Parameter for action parameter, defaults to 0.
 194  *   @param arg1 Parameter for action parameter, defaults to 0.
 195  *   @param arg2 Parameter for action parameter, defaults to 0.
 196  *   @param arg3 Parameter for action parameter, defaults to 0.
 197  *   @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
 198  *
 199  */
 200         virtual IOReturn attemptAction(Action action,
 201             void *arg0 = NULL, void *arg1 = NULL,
 202             void *arg2 = NULL, void *arg3 = NULL);
 203
 204 /*! @function commandSleep
 205  *   @abstract Put a thread that is currently holding the command gate to sleep.
 206  *   @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.
 207  *   @param event Pointer to an address.
 208  *   @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.
 209  *   @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely. */
 210         virtual IOReturn commandSleep(void *event,
 211             UInt32 interruptible = THREAD_ABORTSAFE);
 212
 213 /*! @function commandWakeup
 214  *   @abstract Wakeup one or more threads that are asleep on an event.
 215  *   @param event Pointer to an address.
 216  *   @param oneThread true to only wake up at most one thread, false otherwise. */
 217         virtual void commandWakeup(void *event, bool oneThread = false);
 218
 219 /*! @function disable
 220  *   @abstract Disable the command gate
 221  *   @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.  */
 222         virtual void disable() APPLE_KEXT_OVERRIDE;
 223
 224 /*! @function enable
 225  *   @abstract Enable command gate, this will unblock any blocked Commands and Actions.
 226  *   @discussion  Enable the command gate.  The attemptAction/attemptCommand calls will now be enabled and can succeeed.  Stalled runCommand/runAction calls will be woken up. */
 227         virtual void enable() APPLE_KEXT_OVERRIDE;
 228
 229 /*! @function commandSleep
 230  *   @abstract Put a thread that is currently holding the command gate to sleep.
 231  *   @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.
 232  *   @param event Pointer to an address.
 233  *       @param deadline Clock deadline to timeout the sleep.
 234  *   @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.
 235  *   @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely. */
 236         virtual IOReturn commandSleep(void *event,
 237             AbsoluteTime deadline,
 238             UInt32 interruptible);
 239
 240 private:
 241 #if __LP64__
 242         OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
 243 #else
 244         OSMetaClassDeclareReservedUsedX86(IOCommandGate, 0);
 245 #endif
 246         OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
 247         OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
 248         OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
 249         OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
 250         OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
 251         OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
 252         OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
 253 };
 254
 255 #endif /* !_IOKIT_IOCOMMANDGATE_H */