xnu-1699.32.7.tar.gz
[apple/xnu.git] / iokit / IOKit / IOCommandGate.h
1 /*
2 * Copyright (c) 1998-2009 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
39 /*!
40 @class IOCommandGate : public IOEventSource
41 @abstract Single-threaded work-loop client request mechanism.
42 @discussion An IOCommandGate instance is an extremely light way mechanism
43 that executes an action on the driver's work-loop. 'On the work-loop' is
44 actually a lie but the work-loop single threaded semantic is maintained for this
45 event source. Using the work-loop gate rather than execution by the workloop.
46 The command gate tests for a potential self dead lock by checking if the
47 runCommand request is made from the work-loop's thread, it doesn't check for a
48 mutual dead lock though where a pair of work loop's dead lock each other.
49 <br><br>
50 The IOCommandGate is a lighter weight version of the IOCommandQueue and
51 should be used in preference. Generally use a command queue whenever you need a
52 client to submit a request to a work loop. A typical command gate action would
53 check if the hardware is active, if so it will add the request to a pending
54 queue internal to the device or the device's family. Otherwise if the hardware
55 is inactive then this request can be acted upon immediately.
56 <br><br>
57 CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context.
58
59 */
60 class IOCommandGate : public IOEventSource
61 {
62 OSDeclareDefaultStructors(IOCommandGate)
63
64 public:
65 /*!
66 @typedef Action
67 @discussion Type and arguments of callout C function that is used when
68 a runCommand is executed by a client. Cast to this type when you want a C++
69 member function to be used. Note the arg1 - arg3 parameters are straight pass
70 through from the runCommand to the action callout.
71 @param owner
72 Target of the function, can be used as a refcon. The owner is set
73 during initialisation of the IOCommandGate instance. Note if a C++ function
74 was specified this parameter is implicitly the first paramter in the target
75 member function's parameter list.
76 @param arg0 Argument to action from run operation.
77 @param arg1 Argument to action from run operation.
78 @param arg2 Argument to action from run operation.
79 @param arg3 Argument to action from run operation.
80 */
81 typedef IOReturn (*Action)(OSObject *owner,
82 void *arg0, void *arg1,
83 void *arg2, void *arg3);
84
85 protected:
86
87 /*! @struct ExpansionData
88 @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
89 */
90 struct ExpansionData { };
91
92 /*! @var reserved
93 Reserved for future use. (Internal use only) */
94 ExpansionData *reserved;
95
96 public:
97 /*! @function commandGate
98 @abstract Factory method to create and initialise an IOCommandGate, See $link init.
99 @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
100 static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
101
102 /*! @function init
103 @abstract Class initialiser.
104 @discussion Initialiser for IOCommandGate operates only on newly 'newed'
105 objects. Shouldn't be used to re-init an existing instance.
106 @param owner Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
107 @param action
108 Pointer to a C function that is called whenever a client of the
109 IOCommandGate calls runCommand. NB Can be a C++ member function but caller
110 must cast the member function to $link IOCommandGate::Action and they will get a
111 compiler warning. Defaults to zero, see $link IOEventSource::setAction.
112 @result True if inherited classes initialise successfully. */
113 virtual bool init(OSObject *owner, Action action = 0);
114
115 // Superclass overrides
116 virtual void free();
117 virtual void setWorkLoop(IOWorkLoop *inWorkLoop);
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 function returns.
189 @param event Pointer to an address.
190 @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.
191 @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, 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 /*! @function disable
202 @abstract Disable the command gate
203 @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. */
204 virtual void disable();
205
206 /*! @function enable
207 @abstract Enable command gate, this will unblock any blocked Commands and Actions.
208 @discussion Enable the command gate. The attemptAction/attemptCommand calls will now be enabled and can succeeed. Stalled runCommand/runAction calls will be woken up. */
209 virtual void enable();
210
211 /*! @function commandSleep
212 @abstract Put a thread that is currently holding the command gate to sleep.
213 @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.
214 @param event Pointer to an address.
215 @param deadline Clock deadline to timeout the sleep.
216 @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.
217 @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely, kIOReturnNotPermitted if the calling thread does not hold the command gate. */
218 virtual IOReturn commandSleep(void *event,
219 AbsoluteTime deadline,
220 UInt32 interruptible);
221
222 private:
223 #if __LP64__
224 OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
225 #else
226 OSMetaClassDeclareReservedUsed(IOCommandGate, 0);
227 #endif
228 OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
229 OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
230 OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
231 OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
232 OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
233 OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
234 OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
235 };
236
237 #endif /* !_IOKIT_IOCOMMANDGATE_H */