Root/
Source at commit 1275 created 12 years 11 months ago. By meklort, Remove unused file. Fixup makefiles some more - boot2 compiles again. | |
---|---|
1 | /*␊ |
2 | * Copyright (c) 1998-2009 Apple Computer, 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 | @function checkForWork␊ |
88 | @abstract Not used, $link IOEventSource::checkForWork(). */␊ |
89 | virtual bool checkForWork();␊ |
90 | ␊ |
91 | /*! @struct ExpansionData␊ |
92 | @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.␊ |
93 | */ ␊ |
94 | struct ExpansionData { };␊ |
95 | ␊ |
96 | /*! @var reserved␊ |
97 | Reserved for future use. (Internal use only) */␊ |
98 | ExpansionData *reserved;␊ |
99 | ␊ |
100 | public:␊ |
101 | /*! @function commandGate␊ |
102 | @abstract Factory method to create and initialise an IOCommandGate, See $link init.␊ |
103 | @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */␊ |
104 | static IOCommandGate *commandGate(OSObject *owner, Action action = 0);␊ |
105 | ␊ |
106 | /*! @function init␊ |
107 | @abstract Class initialiser.␊ |
108 | @discussion Initialiser for IOCommandGate operates only on newly 'newed'␊ |
109 | objects. Shouldn't be used to re-init an existing instance.␊ |
110 | @param owner ␉Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.␊ |
111 | @param action␊ |
112 | ␉Pointer to a C function that is called whenever a client of the␊ |
113 | IOCommandGate calls runCommand.␉ NB Can be a C++ member function but caller␊ |
114 | must cast the member function to $link IOCommandGate::Action and they will get a␊ |
115 | compiler warning. Defaults to zero, see $link IOEventSource::setAction.␊ |
116 | @result True if inherited classes initialise successfully. */␊ |
117 | virtual bool init(OSObject *owner, Action action = 0);␊ |
118 | ␊ |
119 | // Superclass overrides␊ |
120 | virtual void free();␊ |
121 | virtual void setWorkLoop(IOWorkLoop *inWorkLoop);␊ |
122 | ␊ |
123 | /*! @function runCommand␊ |
124 | @abstract Single thread a command with the target work-loop.␊ |
125 | @discussion Client function that causes the current action to be called in␊ |
126 | a single threaded manner. Beware the work-loop's gate is recursive and command␊ |
127 | gates can cause direct or indirect re-entrancy.␉ When the executing on a␊ |
128 | client's thread runCommand will sleep until the work-loop's gate opens for␊ |
129 | execution of client actions, the action is single threaded against all other␊ |
130 | work-loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called.␊ |
131 | @param arg0 Parameter for action of command gate, defaults to 0.␊ |
132 | @param arg1 Parameter for action of command gate, defaults to 0.␊ |
133 | @param arg2 Parameter for action of command gate, defaults to 0.␊ |
134 | @param arg3 Parameter for action of command gate, defaults to 0.␊ |
135 | @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.␊ |
136 | */␊ |
137 | virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,␊ |
138 | ␉␉␉␉void *arg2 = 0, void *arg3 = 0);␊ |
139 | ␊ |
140 | /*! @function runAction␊ |
141 | @abstract Single thread a call to an action with the target work-loop.␊ |
142 | @discussion Client function that causes the given action to be called in␊ |
143 | a single threaded manner. Beware the work-loop's gate is recursive and command␊ |
144 | gates can cause direct or indirect re-entrancy.␉ When the executing on a␊ |
145 | client's thread runAction will sleep until the work-loop's gate opens for␊ |
146 | execution of client actions, the action is single threaded against all other␊ |
147 | work-loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called.␊ |
148 | @param action Pointer to function to be executed in work-loop context.␊ |
149 | @param arg0 Parameter for action parameter, defaults to 0.␊ |
150 | @param arg1 Parameter for action parameter, defaults to 0.␊ |
151 | @param arg2 Parameter for action parameter, defaults to 0.␊ |
152 | @param arg3 Parameter for action parameter, defaults to 0.␊ |
153 | @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.␊ |
154 | */␊ |
155 | virtual IOReturn runAction(Action action,␊ |
156 | ␉␉␉ void *arg0 = 0, void *arg1 = 0,␊ |
157 | ␉␉␉ void *arg2 = 0, void *arg3 = 0);␊ |
158 | ␊ |
159 | /*! @function attemptCommand␊ |
160 | @abstract Single thread a command with the target work-loop.␊ |
161 | @discussion Client function that causes the current action to be called in␊ |
162 | a single threaded manner. When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed.␊ |
163 | @param arg0 Parameter for action of command gate, defaults to 0.␊ |
164 | @param arg1 Parameter for action of command gate, defaults to 0.␊ |
165 | @param arg2 Parameter for action of command gate, defaults to 0.␊ |
166 | @param arg3 Parameter for action of command gate, defaults to 0.␊ |
167 | @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.␊ |
168 | */␊ |
169 | virtual IOReturn attemptCommand(void *arg0 = 0, void *arg1 = 0,␊ |
170 | void *arg2 = 0, void *arg3 = 0);␊ |
171 | ␊ |
172 | /*! @function attemptAction␊ |
173 | @abstract Single thread a call to an action with the target work-loop.␊ |
174 | @discussion Client function that causes the given action to be called in␊ |
175 | a single threaded manner. Beware the work-loop's gate is recursive and command␊ |
176 | gates can cause direct or indirect re-entrancy.␉ When the executing on a␊ |
177 | client's thread attemptCommand will fail if the work-loop's gate is closed.␊ |
178 | @param action Pointer to function to be executed in work-loop context.␊ |
179 | @param arg0 Parameter for action parameter, defaults to 0.␊ |
180 | @param arg1 Parameter for action parameter, defaults to 0.␊ |
181 | @param arg2 Parameter for action parameter, defaults to 0.␊ |
182 | @param arg3 Parameter for action parameter, defaults to 0.␊ |
183 | @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.␊ |
184 | ␊ |
185 | */␊ |
186 | virtual IOReturn attemptAction(Action action,␊ |
187 | void *arg0 = 0, void *arg1 = 0,␊ |
188 | void *arg2 = 0, void *arg3 = 0);␊ |
189 | ␊ |
190 | /*! @function commandSleep ␊ |
191 | @abstract Put a thread that is currently holding the command gate to sleep.␊ |
192 | @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.␊ |
193 | @param event Pointer to an address.␊ |
194 | @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.␊ |
195 | @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. */␊ |
196 | virtual IOReturn commandSleep(void *event,␊ |
197 | UInt32 interruptible = THREAD_ABORTSAFE);␊ |
198 | ␊ |
199 | /*! @function commandWakeup␊ |
200 | @abstract Wakeup one or more threads that are asleep on an event.␊ |
201 | @param event Pointer to an address.␊ |
202 | @param onlyOneThread true to only wake up at most one thread, false otherwise. */␊ |
203 | virtual void commandWakeup(void *event, bool oneThread = false);␊ |
204 | ␊ |
205 | /*! @function disable␊ |
206 | @abstract Disable the command gate␊ |
207 | @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. */␊ |
208 | virtual void disable();␊ |
209 | ␊ |
210 | /*! @function enable␊ |
211 | @abstract Enable command gate, this will unblock any blocked Commands and Actions.␊ |
212 | @discussion Enable the command gate. The attemptAction/attemptCommand calls will now be enabled and can succeeed. Stalled runCommand/runAction calls will be woken up. */␊ |
213 | virtual void enable();␊ |
214 | ␊ |
215 | /*! @function commandSleep ␊ |
216 | @abstract Put a thread that is currently holding the command gate to sleep.␊ |
217 | @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.␊ |
218 | @param event Pointer to an address.␊ |
219 | ␉@param deadline Clock deadline to timeout the sleep.␊ |
220 | @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.␊ |
221 | @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. */␊ |
222 | virtual IOReturn commandSleep(void *event,␊ |
223 | ␉␉␉␉␉␉␉␉ AbsoluteTime deadline,␊ |
224 | UInt32 interruptible);␊ |
225 | ␊ |
226 | private:␊ |
227 | #if __LP64__␊ |
228 | OSMetaClassDeclareReservedUnused(IOCommandGate, 0);␊ |
229 | #else␊ |
230 | OSMetaClassDeclareReservedUsed(IOCommandGate, 0);␊ |
231 | #endif␊ |
232 | OSMetaClassDeclareReservedUnused(IOCommandGate, 1);␊ |
233 | OSMetaClassDeclareReservedUnused(IOCommandGate, 2);␊ |
234 | OSMetaClassDeclareReservedUnused(IOCommandGate, 3);␊ |
235 | OSMetaClassDeclareReservedUnused(IOCommandGate, 4);␊ |
236 | OSMetaClassDeclareReservedUnused(IOCommandGate, 5);␊ |
237 | OSMetaClassDeclareReservedUnused(IOCommandGate, 6);␊ |
238 | OSMetaClassDeclareReservedUnused(IOCommandGate, 7);␊ |
239 | };␊ |
240 | ␊ |
241 | #endif /* !_IOKIT_IOCOMMANDGATE_H */␊ |
242 |