iokit/IOKit/IOCommandGate.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*[
  26     1999-8-10   Godfrey van der Linden(gvdl)
  27         Created.
  28 ]*/
  29 /*! @language embedded-c++ */
  30
  31 #ifndef _IOKIT_IOCOMMANDGATE_H
  32 #define _IOKIT_IOCOMMANDGATE_H
  33
  34 #include <IOKit/IOEventSource.h>
  35
  36 /*!
  37     @class IOCommandGate : public IOEventSource
  38     @abstract Single-threaded work-loop client request mechanism.
  39     @discussion An IOCommandGate instance is an extremely light way mechanism
  40 that executes an action on the driver's work-loop.  'On the work-loop' is
  41 actually a lie but the work-loop single threaded semantic is maintained for this
  42 event source.  Using the work-loop gate rather than execution by the workloop.
  43 The command gate tests for a potential self dead lock by checking if the
  44 runCommand request is made from the work-loop's thread, it doens't check for a
  45 mutual dead lock though where a pair of work loop's dead lock each other.
  46 <br><br>
  47         The IOCommandGate is a lighter weight version of the IOCommandQueue and
  48 should be used in preference.  Generally use a command queue whenever you need a
  49 client to submit a request to a work loop.  A typical command gate action would
  50 check if the hardware is active, if so it will add the request to a pending
  51 queue internal to the device or the device's family.  Otherwise if the hardware
  52 is inactive then this request can be acted upon immediately.
  53 <br><br>
  54         CAUTION: The runAction and runCommand functions can not be called from an interrupt context.
  55
  56 */
  57 class IOCommandGate : public IOEventSource
  58 {
  59     OSDeclareDefaultStructors(IOCommandGate)
  60
  61 public:
  62 /*!
  63     @typedef Action
  64     @discussion Type and arguments of callout C function that is used when
  65 a runCommand is executed by a client.  Cast to this type when you want a C++
  66 member function to be used.  Note the arg1 - arg3 parameters are straight pass
  67 through from the runCommand to the action callout.
  68     @param owner
  69         Target of the function, can be used as a refcon.  The owner is set
  70 during initialisation of the IOCommandGate instance.     Note if a C++ function
  71 was specified this parameter is implicitly the first paramter in the target
  72 member function's parameter list.
  73     @param arg0 Argument to action from run operation.
  74     @param arg1 Argument to action from run operation.
  75     @param arg2 Argument to action from run operation.
  76     @param arg3 Argument to action from run operation.
  77 */
  78     typedef IOReturn (*Action)(OSObject *owner,
  79                                void *arg0, void *arg1,
  80                                void *arg2, void *arg3);
  81
  82 protected:
  83 /*!
  84     @function checkForWork
  85     @abstract Not used, $link IOEventSource::checkForWork(). */
  86     virtual bool checkForWork();
  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     ExpansionData *reserved;
  96
  97 public:
  98 /*! @function commandGate
  99     @abstract Factory method to create and initialise an IOCommandGate, See $link init.
 100     @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
 101     static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
 102
 103 /*! @function init
 104     @abstract Class initialiser.
 105     @discussion Initialiser for IOCommandGate operates only on newly 'newed'
 106 objects.  Shouldn't be used to re-init an existing instance.
 107     @param owner        Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
 108     @param action
 109         Pointer to a C function that is called whenever a client of the
 110 IOCommandGate calls runCommand.  NB Can be a C++ member function but caller
 111 must cast the member function to $link IOCommandGate::Action and they will get a
 112 compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
 113     @result True if inherited classes initialise successfully. */
 114     virtual bool init(OSObject *owner, Action action = 0);
 115
 116 /*! @function runCommand
 117     @abstract Single thread a command with the target work-loop.
 118     @discussion Client function that causes the current action to be called in
 119 a single threaded manner.  Beware the work-loop's gate is recursive and command
 120 gates can cause direct or indirect re-entrancy.  When the executing on a
 121 client's thread runCommand will sleep until the work-loop's gate opens for
 122 execution of client actions, the action is single threaded against all other
 123 work-loop event sources.
 124     @param arg0 Parameter for action of command gate, defaults to 0.
 125     @param arg1 Parameter for action of command gate, defaults to 0.
 126     @param arg2 Parameter for action of command gate, defaults to 0.
 127     @param arg3 Parameter for action of command gate, defaults to 0.
 128     @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this
 129 event source is currently disabled, kIOReturnNoResources if no action available.
 130 */
 131     virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
 132                                 void *arg2 = 0, void *arg3 = 0);
 133
 134 /*! @function runAction
 135     @abstract Single thread a call to an action with the target work-loop.
 136     @discussion Client function that causes the given action to be called in
 137 a single threaded manner.  Beware the work-loop's gate is recursive and command
 138 gates can cause direct or indirect re-entrancy.  When the executing on a
 139 client's thread runAction will sleep until the work-loop's gate opens for
 140 execution of client actions, the action is single threaded against all other
 141 work-loop event sources.
 142     @param action Pointer to function to be executed in work-loop context.
 143     @param arg0 Parameter for action parameter, defaults to 0.
 144     @param arg1 Parameter for action parameter, defaults to 0.
 145     @param arg2 Parameter for action parameter, defaults to 0.
 146     @param arg3 Parameter for action parameter, defaults to 0.
 147     @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled.
 148 */
 149     virtual IOReturn runAction(Action action,
 150                                void *arg0 = 0, void *arg1 = 0,
 151                                void *arg2 = 0, void *arg3 = 0);
 152
 153 /*! @function attemptCommand
 154     @abstract Single thread a command with the target work-loop.
 155     @discussion Client function that causes the current action to be called in
 156 a single threaded manner.  Beware the work-loop's gate is recursive and command
 157 gates can cause direct or indirect re-entrancy.  When the executing on a
 158 client's thread attemptCommand will fail if the work-loop's gate is open.
 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 open.
 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 private:
 202     OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
 203     OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
 204     OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
 205     OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
 206     OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
 207     OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
 208     OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
 209     OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
 210 };
 211
 212 #endif /* !_IOKIT_IOCOMMANDGATE_H */