iokit/IOKit/IOCommandGate.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*[
  23     1999-8-10   Godfrey van der Linden(gvdl)
  24         Created.
  25 ]*/
  26 /*! @language embedded-c++ */
  27
  28 #ifndef _IOKIT_IOCOMMANDGATE_H
  29 #define _IOKIT_IOCOMMANDGATE_H
  30
  31 #include <IOKit/IOEventSource.h>
  32
  33 /*!
  34     @class IOCommandGate : public IOEventSource
  35     @abstract Single-threaded work-loop client request mechanism.
  36     @discussion An IOCommandGate instance is an extremely light way mechanism
  37 that executes an action on the driver's work-loop.  'On the work-loop' is
  38 actually a lie but the work-loop single threaded semantic is maintained for this
  39 event source.  Using the work-loop gate rather than execution by the workloop.
  40 The command gate tests for a potential self dead lock by checking if the
  41 runCommand request is made from the work-loop's thread, it doens't check for a
  42 mutual dead lock though where a pair of work loop's dead lock each other.
  43 <br><br>
  44         The IOCommandGate is a lighter weight version of the IOCommandQueue and
  45 should be used in preference.  Generally use a command queue whenever you need a
  46 client to submit a request to a work loop.  A typical command gate action would
  47 check if the hardware is active, if so it will add the request to a pending
  48 queue internal to the device or the device's family.  Otherwise if the hardware
  49 is inactive then this request can be acted upon immediately.
  50 <br><br>
  51     CAUTION: The runAction and runCommand functions can not be called from an interrupt context. But attemptCommand can, though it may return an error
  52
  53 */
  54 class IOCommandGate : public IOEventSource
  55 {
  56     OSDeclareDefaultStructors(IOCommandGate)
  57
  58 public:
  59 /*!
  60     @typedef Action
  61     @discussion Type and arguments of callout C function that is used when
  62 a runCommand is executed by a client.  Cast to this type when you want a C++
  63 member function to be used.  Note the arg1 - arg3 parameters are straight pass
  64 through from the runCommand to the action callout.
  65     @param owner
  66         Target of the function, can be used as a refcon.  The owner is set
  67 during initialisation of the IOCommandGate instance.     Note if a C++ function
  68 was specified this parameter is implicitly the first paramter in the target
  69 member function's parameter list.
  70     @param arg0 Argument to action from run operation.
  71     @param arg1 Argument to action from run operation.
  72     @param arg2 Argument to action from run operation.
  73     @param arg3 Argument to action from run operation.
  74 */
  75     typedef IOReturn (*Action)(OSObject *owner,
  76                                void *arg0, void *arg1,
  77                                void *arg2, void *arg3);
  78
  79 protected:
  80 /*!
  81     @function checkForWork
  82     @abstract Not used, $link IOEventSource::checkForWork(). */
  83     virtual bool checkForWork();
  84
  85 /*! @struct ExpansionData
  86     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  87     */
  88     struct ExpansionData { };
  89
  90 /*! @var reserved
  91     Reserved for future use.  (Internal use only)  */
  92     ExpansionData *reserved;
  93
  94 public:
  95 /*! @function commandGate
  96     @abstract Factory method to create and initialise an IOCommandGate, See $link init.
  97     @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
  98     static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
  99
 100 /*! @function init
 101     @abstract Class initialiser.
 102     @discussion Initialiser for IOCommandGate operates only on newly 'newed'
 103 objects.  Shouldn't be used to re-init an existing instance.
 104     @param owner        Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
 105     @param action
 106         Pointer to a C function that is called whenever a client of the
 107 IOCommandGate calls runCommand.  NB Can be a C++ member function but caller
 108 must cast the member function to $link IOCommandGate::Action and they will get a
 109 compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
 110     @result True if inherited classes initialise successfully. */
 111     virtual bool init(OSObject *owner, Action action = 0);
 112
 113 #if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
 114     // Superclass overrides
 115     virtual void free();
 116     virtual void setWorkLoop(IOWorkLoop *inWorkLoop);
 117 #endif
 118
 119 /*! @function runCommand
 120     @abstract Single thread a command with the target work-loop.
 121     @discussion Client function that causes the current action to be called in
 122 a single threaded manner.  Beware the work-loop's gate is recursive and command
 123 gates can cause direct or indirect re-entrancy.  When the executing on a
 124 client's thread runCommand will sleep until the work-loop's gate opens for
 125 execution of client actions, the action is single threaded against all other
 126 work-loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 127     @param arg0 Parameter for action of command gate, defaults to 0.
 128     @param arg1 Parameter for action of command gate, defaults to 0.
 129     @param arg2 Parameter for action of command gate, defaults to 0.
 130     @param arg3 Parameter for action of command gate, defaults to 0.
 131     @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
 132 */
 133     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
 134                                 void *arg2 = 0, void *arg3 = 0);
 135
 136 /*! @function runAction
 137     @abstract Single thread a call to an action with the target work-loop.
 138     @discussion Client function that causes the given action to be called in
 139 a single threaded manner.  Beware the work-loop's gate is recursive and command
 140 gates can cause direct or indirect re-entrancy.  When the executing on a
 141 client's thread runAction will sleep until the work-loop's gate opens for
 142 execution of client actions, the action is single threaded against all other
 143 work-loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 144     @param action Pointer to function to be executed in work-loop context.
 145     @param arg0 Parameter for action parameter, defaults to 0.
 146     @param arg1 Parameter for action parameter, defaults to 0.
 147     @param arg2 Parameter for action parameter, defaults to 0.
 148     @param arg3 Parameter for action parameter, defaults to 0.
 149     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
 150 */
 151     virtual IOReturn runAction(Action action,
 152                                void *arg0 = 0, void *arg1 = 0,
 153                                void *arg2 = 0, void *arg3 = 0);
 154
 155 /*! @function attemptCommand
 156     @abstract Single thread a command with the target work-loop.
 157     @discussion Client function that causes the current action to be called in
 158 a single threaded manner.  When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed.
 159     @param arg0 Parameter for action of command gate, defaults to 0.
 160     @param arg1 Parameter for action of command gate, defaults to 0.
 161     @param arg2 Parameter for action of command gate, defaults to 0.
 162     @param arg3 Parameter for action of command gate, defaults to 0.
 163     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
 164 */
 165     virtual IOReturn attemptCommand(void *arg0 = 0, void *arg1 = 0,
 166                                     void *arg2 = 0, void *arg3 = 0);
 167
 168 /*! @function attemptAction
 169     @abstract Single thread a call to an action with the target work-loop.
 170     @discussion Client function that causes the given action to be called in
 171 a single threaded manner.  Beware the work-loop's gate is recursive and command
 172 gates can cause direct or indirect re-entrancy.  When the executing on a
 173 client's thread attemptCommand will fail if the work-loop's gate is closed.
 174     @param action Pointer to function to be executed in work-loop context.
 175     @param arg0 Parameter for action parameter, defaults to 0.
 176     @param arg1 Parameter for action parameter, defaults to 0.
 177     @param arg2 Parameter for action parameter, defaults to 0.
 178     @param arg3 Parameter for action parameter, defaults to 0.
 179     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
 180
 181 */
 182     virtual IOReturn attemptAction(Action action,
 183                                    void *arg0 = 0, void *arg1 = 0,
 184                                    void *arg2 = 0, void *arg3 = 0);
 185
 186 /*! @function commandSleep
 187     @abstract Put a thread that is currently holding the command gate to sleep.
 188     @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.
 189     @param event Pointer to an address.
 190     @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE,  defaults to THREAD_ABORTSAFE.
 191     @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. */
 192     virtual IOReturn commandSleep(void *event,
 193                                   UInt32 interruptible = THREAD_ABORTSAFE);
 194
 195 /*! @function commandWakeup
 196     @abstract Wakeup one or more threads that are asleep on an event.
 197     @param event Pointer to an address.
 198     @param onlyOneThread true to only wake up at most one thread, false otherwise. */
 199     virtual void commandWakeup(void *event, bool oneThread = false);
 200
 201 #if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
 202 /*! @function disable
 203     @abstract Disable the command gate
 204     @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.  */
 205     virtual void disable();
 206
 207 /*! @function enable
 208     @abstract Enable command gate, this will unblock any blocked Commands and Actions.
 209     @discussion  Enable the command gate.  The attemptAction/attemptCommand calls will now be enabled and can succeeed.  Stalled runCommand/runAction calls will be woken up. */
 210     virtual void enable();
 211 #endif
 212
 213 private:
 214     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
 215     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
 216     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
 217     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
 218     OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
 219     OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
 220     OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
 221     OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
 222 };
 223
 224 #endif /* !_IOKIT_IOCOMMANDGATE_H */