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.
  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 /*! @function runCommand
 114     @abstract Single thread a command with the target work-loop.
 115     @discussion Client function that causes the current action to be called in
 116 a single threaded manner.  Beware the work-loop's gate is recursive and command
 117 gates can cause direct or indirect re-entrancy.  When the executing on a
 118 client's thread runCommand will sleep until the work-loop's gate opens for
 119 execution of client actions, the action is single threaded against all other
 120 work-loop event sources.
 121     @param arg0 Parameter for action of command gate, defaults to 0.
 122     @param arg1 Parameter for action of command gate, defaults to 0.
 123     @param arg2 Parameter for action of command gate, defaults to 0.
 124     @param arg3 Parameter for action of command gate, defaults to 0.
 125     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this
 126 event source is currently disabled, kIOReturnNoResources if no action available.
 127 */
 128     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
 129                                 void *arg2 = 0, void *arg3 = 0);
 130
 131 /*! @function runAction
 132     @abstract Single thread a call to an action with the target work-loop.
 133     @discussion Client function that causes the given action to be called in
 134 a single threaded manner.  Beware the work-loop's gate is recursive and command
 135 gates can cause direct or indirect re-entrancy.  When the executing on a
 136 client's thread runAction will sleep until the work-loop's gate opens for
 137 execution of client actions, the action is single threaded against all other
 138 work-loop event sources.
 139     @param action Pointer to function to be executed in work-loop context.
 140     @param arg0 Parameter for action parameter, defaults to 0.
 141     @param arg1 Parameter for action parameter, defaults to 0.
 142     @param arg2 Parameter for action parameter, defaults to 0.
 143     @param arg3 Parameter for action parameter, defaults to 0.
 144     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled.
 145 */
 146     virtual IOReturn runAction(Action action,
 147                                void *arg0 = 0, void *arg1 = 0,
 148                                void *arg2 = 0, void *arg3 = 0);
 149
 150 /*! @function attemptCommand
 151     @abstract Single thread a command with the target work-loop.
 152     @discussion Client function that causes the current action to be called in
 153 a single threaded manner.  Beware the work-loop's gate is recursive and command
 154 gates can cause direct or indirect re-entrancy.  When the executing on a
 155 client's thread attemptCommand will fail if the work-loop's gate is open.
 156     @param arg0 Parameter for action of command gate, defaults to 0.
 157     @param arg1 Parameter for action of command gate, defaults to 0.
 158     @param arg2 Parameter for action of command gate, defaults to 0.
 159     @param arg3 Parameter for action of command gate, defaults to 0.
 160     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
 161 */
 162     virtual IOReturn attemptCommand(void *arg0 = 0, void *arg1 = 0,
 163                                     void *arg2 = 0, void *arg3 = 0);
 164
 165 /*! @function attemptAction
 166     @abstract Single thread a call to an action with the target work-loop.
 167     @discussion Client function that causes the given action to be called in
 168 a single threaded manner.  Beware the work-loop's gate is recursive and command
 169 gates can cause direct or indirect re-entrancy.  When the executing on a
 170 client's thread attemptCommand will fail if the work-loop's gate is open.
 171     @param action Pointer to function to be executed in work-loop context.
 172     @param arg0 Parameter for action parameter, defaults to 0.
 173     @param arg1 Parameter for action parameter, defaults to 0.
 174     @param arg2 Parameter for action parameter, defaults to 0.
 175     @param arg3 Parameter for action parameter, defaults to 0.
 176     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
 177
 178 */
 179     virtual IOReturn attemptAction(Action action,
 180                                    void *arg0 = 0, void *arg1 = 0,
 181                                    void *arg2 = 0, void *arg3 = 0);
 182
 183 /*! @function commandSleep
 184     @abstract Put a thread that is currently holding the command gate to sleep.
 185     @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.
 186     @param event Pointer to an address.
 187     @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE,  defaults to THREAD_ABORTSAFE.
 188     @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. */
 189     virtual IOReturn commandSleep(void *event,
 190                                   UInt32 interruptible = THREAD_ABORTSAFE);
 191
 192 /*! @function commandWakeup
 193     @abstract Wakeup one or more threads that are asleep on an event.
 194     @param event Pointer to an address.
 195     @param onlyOneThread true to only wake up at most one thread, false otherwise. */
 196     virtual void commandWakeup(void *event, bool oneThread = false);
 197
 198 private:
 199     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
 200     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
 201     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
 202     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
 203     OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
 204     OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
 205     OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
 206     OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
 207 };
 208
 209 #endif /* !_IOKIT_IOCOMMANDGATE_H */