]> git.saurik.com Git - apple/xnu.git/blame - iokit/IOKit/IOTimerEventSource.h
xnu-4570.71.2.tar.gz
[apple/xnu.git] / iokit / IOKit / IOTimerEventSource.h
CommitLineData
1c79356b 1/*
39037602 2 * Copyright (c) 1998-2016 Apple Inc. All rights reserved.
1c79356b 3 *
2d21ac55 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b 5 *
2d21ac55
A
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.
8f6c56a5 14 *
2d21ac55
A
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
8f6c56a5
A
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55
A
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.
8f6c56a5 25 *
2d21ac55 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b
A
27 */
28/*
29 * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
30 *
31 * IOTimerEventSource.h
32 *
33 * HISTORY
34 * 2-Feb-1999 Joe Liu (jliu) created.
35 *
36 */
37
38#ifndef _IOTIMEREVENTSOURCE
39#define _IOTIMEREVENTSOURCE
40
41#include <sys/cdefs.h>
42
43__BEGIN_DECLS
44#include <kern/clock.h>
45__END_DECLS
46
47#include <IOKit/IOEventSource.h>
48#include <IOKit/IOTypes.h>
49
5ba3f43e
A
50/*!
51 @enum IOTimerEventSource constructor options
52 @abstract Constants defining behavior of the IOTimerEventSource.
53 @constant kIOTimerEventSourceOptionsPriorityHigh Importance above everything but realtime.
54 Thread calls allocated with this priority execute at extremely high priority,
55 above everything but realtime threads. They are generally executed in serial.
56 Though they may execute concurrently under some circumstances, no fan-out is implied.
57 These work items should do very small amounts of work or risk disrupting system
58 responsiveness.
59 @constant kIOTimerEventSourceOptionsPriorityKernelHigh Importance higher than most kernel
60 threads.
61 @constant kIOTimerEventSourceOptionsPriorityKernel Importance similar to that of normal kernel
62 threads.
63 @constant kIOTimerEventSourceOptionsPriorityUser Importance similar to that of normal user threads.
64 @constant kIOTimerEventSourceOptionsPriorityLow Very low importance.
65 @constant kIOTimerEventSourceOptionsPriorityWorkLoop Run the callout on the thread of the IOWorkLoop
66 the event source has been added to.
67 @constant kIOTimerEventSourceOptionsAllowReenter Allow the callout to be rescheduled and potentially
68 re-entered, if the IOWorkLoop lock has been released (eg. with commandSleep) during its invocation.
69 @constant kIOTimerEventSourceOptionsDefault Recommended default options.
70 */
71enum
72{
73 kIOTimerEventSourceOptionsPriorityMask = 0x000000ff,
74 kIOTimerEventSourceOptionsPriorityHigh = 0x00000000,
75 kIOTimerEventSourceOptionsPriorityKernelHigh = 0x00000001,
76 kIOTimerEventSourceOptionsPriorityKernel = 0x00000002,
77 kIOTimerEventSourceOptionsPriorityUser = 0x00000003,
78 kIOTimerEventSourceOptionsPriorityLow = 0x00000004,
79 kIOTimerEventSourceOptionsPriorityWorkLoop = 0x000000ff,
80
81 kIOTimerEventSourceOptionsAllowReenter = 0x00000100,
82
83 kIOTimerEventSourceOptionsDefault = kIOTimerEventSourceOptionsPriorityKernelHigh
84};
85
86#define IOTIMEREVENTSOURCEOPTIONS_DEFINED 1
87
88/*!
89 @enum IOTimerEventSource setTimeout/wakeAtTime options
90 @abstract Constants defining behavior of a scheduled call from IOTimerEventSource.
91 @constant kIOTimeOptionsWithLeeway Use the leeway parameter to the call.
92 @constant kIOTimeOptionsContinuous Use mach_continuous_time() to generate the callback.
93*/
94enum
95{
96 kIOTimeOptionsWithLeeway = 0x00000020,
97 kIOTimeOptionsContinuous = 0x00000100,
98};
99
1c79356b
A
100/*!
101 @class IOTimerEventSource : public IOEventSource
102 @abstract Time based event source mechanism.
103 @discussion An event source that implements a simple timer. A timeout handler is called once the timeout period expires. This timeout handler will be called by the work-loop that this event source is attached to.
104<br><br>
105 Usually a timer event source will be used to implement a timeout. In general when a driver makes a request it will need to setup a call to keep track of when the I/O doesn't complete. This class is designed to make that somewhat easier.
106<br><br>
107 Remember the system doesn't guarantee the accuracy of the callout. It is possible that a higher priority thread is running which will delay the execution of the action routine. In fact the thread will be made runable at the exact requested time, within the accuracy of the CPU's decrementer based interrupt, but the scheduler will then control execution.
108*/
5ba3f43e 109
1c79356b
A
110class IOTimerEventSource : public IOEventSource
111{
112 OSDeclareDefaultStructors(IOTimerEventSource)
113
114protected:
115/*! @var calloutEntry thread_call entry for preregistered thread callouts */
116 void *calloutEntry;
117
118/*! @var abstime time to wake up next, see enable. */
119 AbsoluteTime abstime;
120
121/*! @struct ExpansionData
91447636 122 @discussion This structure is private to the IOTimerEventSource implementation.
1c79356b 123 */
91447636
A
124 struct ExpansionData
125 {
126 SInt32 calloutGeneration;
5ba3f43e 127 SInt32 calloutGenerationSignaled;
91447636
A
128 IOWorkLoop * workLoop;
129 };
1c79356b
A
130
131/*! @var reserved
132 Reserved for future use. (Internal use only) */
a39ff7e2 133 APPLE_KEXT_WSHADOW_PUSH;
1c79356b 134 ExpansionData *reserved;
a39ff7e2 135 APPLE_KEXT_WSHADOW_POP;
1c79356b
A
136
137/*! @function timeout
138 @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
139 @discussion timeout will normally not be called nor overridden by a subclass. If the event source is enabled then close the work-loop's gate and call the action routine.
140 @param self This argument will be cast to an IOTimerEventSource. */
141 static void timeout(void *self);
142
143/*! @function setTimeoutFunc
144 @abstract Set's timeout as the function of calloutEntry.
145 @discussion IOTimerEventSource is based upon the kern/thread_call.h APIs currently. This function allocates the calloutEntry member variable by using thread_call_allocate(timeout, this). If you need to write your own subclass of IOTimerEventSource you probably should override this method to allocate an entry that points to your own timeout routine. */
146 virtual void setTimeoutFunc();
147
148/*! @function free
149 @abstract Sub-class implementation of free method, frees calloutEntry */
3e170ce0 150 virtual void free() APPLE_KEXT_OVERRIDE;
1c79356b 151
3e170ce0 152 virtual void setWorkLoop(IOWorkLoop *workLoop) APPLE_KEXT_OVERRIDE;
91447636 153
1c79356b
A
154public:
155
156/*! @typedef Action
157 @discussion 'C' Function pointer defining the callout routine of this event source.
158 @param owner Owning target object. Note by a startling coincidence the first parameter in a C callout is currently used to define the target of a C++ member function.
159 @param sender The object that timed out. */
160 typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);
161
5ba3f43e
A
162 static IOTimerEventSource *
163 timerEventSource(OSObject *owner, Action action = 0);
164
1c79356b
A
165/*! @function timerEventSource
166 @abstract Allocates and returns an initialized timer instance.
5ba3f43e
A
167 @param options Mask of kIOTimerEventSourceOptions* options.
168 @param owner The object that that will be passed to the Action callback.
169 @param action 'C' Function pointer for the callout routine of this event source.
39037602 170 */
1c79356b 171 static IOTimerEventSource *
5ba3f43e 172 timerEventSource(uint32_t options, OSObject *owner, Action action = 0);
1c79356b
A
173
174/*! @function init
175 @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
39037602 176 */
1c79356b
A
177 virtual bool init(OSObject *owner, Action action = 0);
178
179/*! @function enable
180 @abstract Enables a call to the action.
181 @discussion Allows the action function to be called. If the timer event source was disabled while a call was outstanding and the call wasn't cancelled then it will be rescheduled. So a disable/enable pair will disable calls from this event source. */
3e170ce0 182 virtual void enable() APPLE_KEXT_OVERRIDE;
1c79356b
A
183
184/*! @function disable
185 @abstract Disable a timed callout.
186 @discussion When disable returns the action will not be called until the next time enable(qv) is called. */
3e170ce0 187 virtual void disable() APPLE_KEXT_OVERRIDE;
1c79356b 188
5ba3f43e
A
189/*! @function checkForWork
190 @abstract Pure Virtual member function used by IOWorkLoop for issuing a client calls.
191 @discussion This function called when the work-loop is ready to check for any work to do and then to call out the owner/action.
192 @result Return true if this function needs to be called again before all its outstanding events have been processed. */
193 virtual bool checkForWork() APPLE_KEXT_OVERRIDE;
1c79356b
A
194
195/*! @function setTimeoutTicks
196 @abstract Setup a callback at after the delay in scheduler ticks. See wakeAtTime(AbsoluteTime).
39037602 197 @param ticks Delay from now to wake up, in scheduler ticks, whatever that may be.
1c79356b
A
198 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
199 virtual IOReturn setTimeoutTicks(UInt32 ticks);
200
201/*! @function setTimeoutMS
202 @abstract Setup a callback at after the delay in milliseconds. See wakeAtTime(AbsoluteTime).
39037602 203 @param ms Delay from now to wake up, time in milliseconds.
1c79356b
A
204 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
205 virtual IOReturn setTimeoutMS(UInt32 ms);
206
207/*! @function setTimeoutUS
208 @abstract Setup a callback at after the delay in microseconds. See wakeAtTime(AbsoluteTime).
39037602 209 @param us Delay from now to wake up, time in microseconds.
1c79356b
A
210 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
211 virtual IOReturn setTimeoutUS(UInt32 us);
212
213/*! @function setTimeout
214 @abstract Setup a callback at after the delay in some unit. See wakeAtTime(AbsoluteTime).
215 @param interval Delay from now to wake up in some defined unit.
216 @param scale_factor Define the unit of interval, default to nanoseconds.
217 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
218 virtual IOReturn setTimeout(UInt32 interval,
219 UInt32 scale_factor = kNanosecondScale);
220
b0d623f7
A
221#if !defined(__LP64__)
222 virtual IOReturn setTimeout(mach_timespec_t interval)
223 APPLE_KEXT_DEPRECATED;
224#endif
1c79356b
A
225
226/*! @function setTimeout
227 @abstract Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
228 @param interval Delay from now to wake up in decrementer ticks.
229 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
230 virtual IOReturn setTimeout(AbsoluteTime interval);
231
232/*! @function wakeAtTimeTicks
233 @abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
39037602 234 @param ticks Time to wake up in scheduler quantums, whatever that is?
1c79356b
A
235 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
236 virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
237
238/*! @function wakeAtTimeMS
239 @abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
39037602 240 @param ms Time to wake up in milliseconds.
1c79356b
A
241 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
242 virtual IOReturn wakeAtTimeMS(UInt32 ms);
243
244/*! @function wakeAtTimeUS
245 @abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
39037602 246 @param us Time to wake up in microseconds.
1c79356b
A
247 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
248 virtual IOReturn wakeAtTimeUS(UInt32 us);
249
250/*! @function wakeAtTime
251 @abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
252 @param abstime Time to wake up in some unit.
253 @param scale_factor Define the unit of abstime, default to nanoseconds.
254 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
255 virtual IOReturn wakeAtTime(UInt32 abstime,
256 UInt32 scale_factor = kNanosecondScale);
257
b0d623f7
A
258#if !defined(__LP64__)
259 virtual IOReturn wakeAtTime(mach_timespec_t abstime)
260 APPLE_KEXT_DEPRECATED;
261#endif
1c79356b
A
262
263/*! @function wakeAtTime
264 @abstract Setup a callback at this absolute time.
5ba3f43e 265 @discussion Starts the timer, which will expire at abstime. After it expires, the timer will call the 'action' registered in the init() function. This timer is not periodic, a further call is needed to reset and restart the timer after it expires.
1c79356b
A
266 @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
267 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
268 virtual IOReturn wakeAtTime(AbsoluteTime abstime);
269
270/*! @function cancelTimeout
271 @abstract Disable any outstanding calls to this event source.
272 @discussion Clear down any oustanding calls. By the time this function completes it is guaranteed that the action will not be called again. */
273 virtual void cancelTimeout();
274
5ba3f43e
A
275/*! @function init
276 @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
277 */
278 virtual bool init(uint32_t options, OSObject *inOwner, Action inAction);
279
280/*! @function setTimeout
281 @abstract Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
282 @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
283 @param interval Delay from now to wake up in decrementer ticks.
284 @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
285 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
286 virtual IOReturn setTimeout(uint32_t options, AbsoluteTime interval, AbsoluteTime leeway);
287
288/*! @function wakeAtTime
289 @abstract Setup a callback at this absolute time.
290 @discussion Starts the timer, which will expire at abstime. After it expires, the timer will call the 'action' registered in the init() function. This timer is not periodic, a further call is needed to reset and restart the timer after it expires.
291 @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
292 @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
293 @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
294 @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
295 virtual IOReturn wakeAtTime(uint32_t options, AbsoluteTime abstime, AbsoluteTime leeway);
296
91447636 297private:
5ba3f43e
A
298 static void timeoutAndRelease(void *self, void *c);
299 static void timeoutSignaled(void *self, void *c);
91447636 300
1c79356b 301private:
5ba3f43e
A
302 OSMetaClassDeclareReservedUsed(IOTimerEventSource, 0);
303 OSMetaClassDeclareReservedUsed(IOTimerEventSource, 1);
304 OSMetaClassDeclareReservedUsed(IOTimerEventSource, 2);
1c79356b
A
305 OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
306 OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
307 OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
308 OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
309 OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
310};
311
312#endif /* !_IOTIMEREVENTSOURCE */