[apple/xnu.git] / iokit / IOKit / IOTimerEventSource.h

/*
 * Copyright (c) 1998-2016 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*
 * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved. 
 *
 * IOTimerEventSource.h
 *
 * HISTORY
 * 2-Feb-1999		Joe Liu (jliu) created.
 *
 */

#ifndef _IOTIMEREVENTSOURCE
#define _IOTIMEREVENTSOURCE

#include <sys/cdefs.h>

__BEGIN_DECLS
#include <kern/clock.h>
__END_DECLS

#include <IOKit/IOEventSource.h>
#include <IOKit/IOTypes.h>

/*!
	@enum IOTimerEventSource constructor options
	@abstract Constants defining behavior of the IOTimerEventSource.
	@constant kIOTimerEventSourceOptionsPriorityHigh Importance above everything but realtime.
	Thread calls allocated with this priority execute at extremely high priority,
	above everything but realtime threads.  They are generally executed in serial.
	Though they may execute concurrently under some circumstances, no fan-out is implied.
	These work items should do very small amounts of work or risk disrupting system
	responsiveness.
	@constant kIOTimerEventSourceOptionsPriorityKernelHigh Importance higher than most kernel
	threads.
	@constant kIOTimerEventSourceOptionsPriorityKernel Importance similar to that of normal kernel
	threads.
	@constant kIOTimerEventSourceOptionsPriorityUser Importance similar to that of normal user threads.
	@constant kIOTimerEventSourceOptionsPriorityLow Very low importance.
	@constant kIOTimerEventSourceOptionsPriorityWorkLoop Run the callout on the thread of the IOWorkLoop
	the event source has been added to.
	@constant kIOTimerEventSourceOptionsAllowReenter Allow the callout to be rescheduled and potentially
	re-entered, if the IOWorkLoop lock has been released (eg. with commandSleep) during its invocation.
	@constant kIOTimerEventSourceOptionsDefault Recommended default options.
 */
enum
{
    kIOTimerEventSourceOptionsPriorityMask       = 0x000000ff,
    kIOTimerEventSourceOptionsPriorityHigh       = 0x00000000,
    kIOTimerEventSourceOptionsPriorityKernelHigh = 0x00000001,
    kIOTimerEventSourceOptionsPriorityKernel     = 0x00000002,
    kIOTimerEventSourceOptionsPriorityUser       = 0x00000003,
    kIOTimerEventSourceOptionsPriorityLow        = 0x00000004,
    kIOTimerEventSourceOptionsPriorityWorkLoop   = 0x000000ff,

    kIOTimerEventSourceOptionsAllowReenter       = 0x00000100,

    kIOTimerEventSourceOptionsDefault            = kIOTimerEventSourceOptionsPriorityKernelHigh
};

#define IOTIMEREVENTSOURCEOPTIONS_DEFINED	1

/*!
	@enum IOTimerEventSource setTimeout/wakeAtTime options
	@abstract Constants defining behavior of a scheduled call from IOTimerEventSource.
	@constant kIOTimeOptionsWithLeeway Use the leeway parameter to the call.
	@constant kIOTimeOptionsContinuous Use mach_continuous_time() to generate the callback.
*/
enum
{
    kIOTimeOptionsWithLeeway = 0x00000020,
    kIOTimeOptionsContinuous = 0x00000100,
};

/*!
    @class IOTimerEventSource : public IOEventSource
    @abstract Time based event source mechanism.
    @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.
<br><br>
	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.
<br><br>
	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.
*/

class IOTimerEventSource : public IOEventSource
{
    OSDeclareDefaultStructors(IOTimerEventSource)

protected:
/*! @var calloutEntry thread_call entry for preregistered thread callouts */
    void *calloutEntry;

/*! @var abstime time to wake up next, see enable. */
    AbsoluteTime abstime;

/*! @struct ExpansionData
    @discussion This structure is private to the IOTimerEventSource implementation.
    */    
    struct ExpansionData
    {
        SInt32	     calloutGeneration;
        SInt32	     calloutGenerationSignaled;
        IOWorkLoop * workLoop;
    };

/*! @var reserved
    Reserved for future use.  (Internal use only)  */
    ExpansionData *reserved;

/*! @function timeout
    @abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
    @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.
    @param self This argument will be cast to an IOTimerEventSource. */
    static void timeout(void *self);

/*! @function setTimeoutFunc
    @abstract Set's timeout as the function of calloutEntry.
    @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. */
    virtual void setTimeoutFunc();

/*! @function free
    @abstract Sub-class implementation of free method, frees calloutEntry */
    virtual void free() APPLE_KEXT_OVERRIDE;

    virtual void setWorkLoop(IOWorkLoop *workLoop) APPLE_KEXT_OVERRIDE;

public:

/*! @typedef Action
    @discussion 'C' Function pointer defining the callout routine of this event source.
    @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.
    @param sender The object that timed out. */
    typedef void (*Action)(OSObject *owner, IOTimerEventSource *sender);

    static IOTimerEventSource *
	timerEventSource(OSObject *owner, Action action = 0);

/*! @function timerEventSource
    @abstract Allocates and returns an initialized timer instance.
    @param options Mask of kIOTimerEventSourceOptions* options.
    @param owner The object that that will be passed to the Action callback.
    @param action 'C' Function pointer for the callout routine of this event source.
    */
    static IOTimerEventSource *
	timerEventSource(uint32_t options, OSObject *owner, Action action = 0);

/*! @function init
    @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
    */
    virtual bool init(OSObject *owner, Action action = 0);

/*! @function enable
    @abstract Enables a call to the action.
    @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. */
    virtual void enable() APPLE_KEXT_OVERRIDE;

/*! @function disable
    @abstract Disable a timed callout.
    @discussion When disable returns the action will not be called until the next time enable(qv) is called. */
    virtual void disable() APPLE_KEXT_OVERRIDE;

/*! @function checkForWork
    @abstract Pure Virtual member function used by IOWorkLoop for issuing a client calls.
    @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.
    @result Return true if this function needs to be called again before all its outstanding events have been processed. */
    virtual bool checkForWork() APPLE_KEXT_OVERRIDE;

/*! @function setTimeoutTicks
    @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).
    @param ticks Delay from now to wake up, in scheduler ticks, whatever that may be.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn setTimeoutTicks(UInt32 ticks);

/*! @function setTimeoutMS
    @abstract Setup a callback at after the delay in milliseconds.  See wakeAtTime(AbsoluteTime).
    @param ms Delay from now to wake up, time in milliseconds.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn setTimeoutMS(UInt32 ms);

/*! @function setTimeoutUS
        @abstract Setup a callback at after the delay in microseconds.	 See wakeAtTime(AbsoluteTime).
    @param us Delay from now to wake up, time in microseconds.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn setTimeoutUS(UInt32 us);

/*! @function setTimeout
    @abstract Setup a callback at after the delay in some unit.	 See wakeAtTime(AbsoluteTime).
    @param interval Delay from now to wake up in some defined unit.
    @param scale_factor Define the unit of interval, default to nanoseconds.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn setTimeout(UInt32 interval,
				UInt32 scale_factor = kNanosecondScale);

#if !defined(__LP64__)
    virtual IOReturn setTimeout(mach_timespec_t interval)
	APPLE_KEXT_DEPRECATED;
#endif

/*! @function setTimeout
    @abstract Setup a callback at after the delay in decrementer ticks.	 See wakeAtTime(AbsoluteTime).
    @param interval Delay from now to wake up in decrementer ticks.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn setTimeout(AbsoluteTime interval);

/*! @function wakeAtTimeTicks
    @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
    @param ticks Time to wake up in scheduler quantums, whatever that is?
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn wakeAtTimeTicks(UInt32 ticks);

/*! @function wakeAtTimeMS
    @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
    @param ms Time to wake up in milliseconds.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn wakeAtTimeMS(UInt32 ms);

/*! @function wakeAtTimeUS
    @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
    @param us Time to wake up in microseconds.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn wakeAtTimeUS(UInt32 us);

/*! @function wakeAtTime
    @abstract Setup a callback at this absolute time.  See wakeAtTime(AbsoluteTime).
    @param abstime Time to wake up in some unit.
    @param scale_factor Define the unit of abstime, default to nanoseconds.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn wakeAtTime(UInt32 abstime,
				UInt32 scale_factor = kNanosecondScale);

#if !defined(__LP64__)
    virtual IOReturn wakeAtTime(mach_timespec_t abstime)
	APPLE_KEXT_DEPRECATED;
#endif

/*! @function wakeAtTime
    @abstract Setup a callback at this absolute time.
    @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.
    @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
    virtual IOReturn wakeAtTime(AbsoluteTime abstime);

/*! @function cancelTimeout
    @abstract Disable any outstanding calls to this event source.
    @discussion Clear down any oustanding calls.  By the time this function completes it is guaranteed that the action will not be called again. */
   virtual void cancelTimeout();

/*! @function init
    @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
    */
    virtual bool init(uint32_t options, OSObject *inOwner, Action inAction);

/*! @function setTimeout
    @abstract Setup a callback at after the delay in decrementer ticks.	 See wakeAtTime(AbsoluteTime).
    @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
    @param interval Delay from now to wake up in decrementer ticks.
    @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
    virtual IOReturn setTimeout(uint32_t options, AbsoluteTime interval, AbsoluteTime leeway);

/*! @function wakeAtTime
    @abstract Setup a callback at this absolute time.
    @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.
    @param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
    @param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
    @param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
    @result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
    virtual IOReturn wakeAtTime(uint32_t options, AbsoluteTime abstime, AbsoluteTime leeway);

private:
    static void timeoutAndRelease(void *self, void *c);
    static void timeoutSignaled(void *self, void *c);

private:
    OSMetaClassDeclareReservedUsed(IOTimerEventSource, 0);
    OSMetaClassDeclareReservedUsed(IOTimerEventSource, 1);
    OSMetaClassDeclareReservedUsed(IOTimerEventSource, 2);
    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
    OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
};

#endif /* !_IOTIMEREVENTSOURCE */
Commit	Line	Data
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,
8f6c56a5 A	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	*/
	71	enum
	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	*/
	94	enum
	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	110	class IOTimerEventSource : public IOEventSource
	111	{
	112	OSDeclareDefaultStructors(IOTimerEventSource)
	113
	114	protected:
	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;
91447636 A	129	};
1c79356b A	130
	131	/*! @var reserved
	132	Reserved for future use. (Internal use only) */
	133	ExpansionData *reserved;
	134
	135	/*! @function timeout
	136	@abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
	137	@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.
	138	@param self This argument will be cast to an IOTimerEventSource. */
	139	static void timeout(void *self);
	140
	141	/*! @function setTimeoutFunc
	142	@abstract Set's timeout as the function of calloutEntry.
	143	@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. */
	144	virtual void setTimeoutFunc();
	145
	146	/*! @function free
	147	@abstract Sub-class implementation of free method, frees calloutEntry */
3e170ce0	148	virtual void free() APPLE_KEXT_OVERRIDE;
1c79356b	149
3e170ce0	150	virtual void setWorkLoop(IOWorkLoop *workLoop) APPLE_KEXT_OVERRIDE;
91447636	151
1c79356b A	152	public:
	153
	154	/*! @typedef Action
	155	@discussion 'C' Function pointer defining the callout routine of this event source.
	156	@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.
	157	@param sender The object that timed out. */
	158	typedef void (Action)(OSObject owner, IOTimerEventSource *sender);
	159
5ba3f43e A	160	static IOTimerEventSource *
	161	timerEventSource(OSObject *owner, Action action = 0);
	162
1c79356b A	163	/*! @function timerEventSource
1c79356b A	164	@abstract Allocates and returns an initialized timer instance.
5ba3f43e A	165	@param options Mask of kIOTimerEventSourceOptions* options.
	166	@param owner The object that that will be passed to the Action callback.
	167	@param action 'C' Function pointer for the callout routine of this event source.
39037602	168	*/
1c79356b	169	static IOTimerEventSource *
5ba3f43e	170	timerEventSource(uint32_t options, OSObject *owner, Action action = 0);
1c79356b A	171
	172	/*! @function init
	173	@abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
39037602	174	*/
1c79356b A	175	virtual bool init(OSObject *owner, Action action = 0);
	176
	177	/*! @function enable
	178	@abstract Enables a call to the action.
	179	@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	180	virtual void enable() APPLE_KEXT_OVERRIDE;
1c79356b A	181
	182	/*! @function disable
	183	@abstract Disable a timed callout.
	184	@discussion When disable returns the action will not be called until the next time enable(qv) is called. */
3e170ce0	185	virtual void disable() APPLE_KEXT_OVERRIDE;
1c79356b	186
5ba3f43e A	187	/*! @function checkForWork
	188	@abstract Pure Virtual member function used by IOWorkLoop for issuing a client calls.
	189	@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.
	190	@result Return true if this function needs to be called again before all its outstanding events have been processed. */
	191	virtual bool checkForWork() APPLE_KEXT_OVERRIDE;
1c79356b A	192
	193	/*! @function setTimeoutTicks
	194	@abstract Setup a callback at after the delay in scheduler ticks. See wakeAtTime(AbsoluteTime).
39037602	195	@param ticks Delay from now to wake up, in scheduler ticks, whatever that may be.
1c79356b A	196	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	197	virtual IOReturn setTimeoutTicks(UInt32 ticks);
	198
	199	/*! @function setTimeoutMS
	200	@abstract Setup a callback at after the delay in milliseconds. See wakeAtTime(AbsoluteTime).
39037602	201	@param ms Delay from now to wake up, time in milliseconds.
1c79356b A	202	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	203	virtual IOReturn setTimeoutMS(UInt32 ms);
	204
	205	/*! @function setTimeoutUS
	206	@abstract Setup a callback at after the delay in microseconds. See wakeAtTime(AbsoluteTime).
39037602	207	@param us Delay from now to wake up, time in microseconds.
1c79356b A	208	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	209	virtual IOReturn setTimeoutUS(UInt32 us);
	210
	211	/*! @function setTimeout
	212	@abstract Setup a callback at after the delay in some unit. See wakeAtTime(AbsoluteTime).
	213	@param interval Delay from now to wake up in some defined unit.
	214	@param scale_factor Define the unit of interval, default to nanoseconds.
	215	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	216	virtual IOReturn setTimeout(UInt32 interval,
	217	UInt32 scale_factor = kNanosecondScale);
	218
b0d623f7 A	219	#if !defined(__LP64__)
	220	virtual IOReturn setTimeout(mach_timespec_t interval)
	221	APPLE_KEXT_DEPRECATED;
	222	#endif
1c79356b A	223
	224	/*! @function setTimeout
	225	@abstract Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
	226	@param interval Delay from now to wake up in decrementer ticks.
	227	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	228	virtual IOReturn setTimeout(AbsoluteTime interval);
	229
	230	/*! @function wakeAtTimeTicks
	231	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
39037602	232	@param ticks Time to wake up in scheduler quantums, whatever that is?
1c79356b A	233	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	234	virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
	235
	236	/*! @function wakeAtTimeMS
	237	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
39037602	238	@param ms Time to wake up in milliseconds.
1c79356b A	239	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	240	virtual IOReturn wakeAtTimeMS(UInt32 ms);
	241
	242	/*! @function wakeAtTimeUS
	243	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
39037602	244	@param us Time to wake up in microseconds.
1c79356b A	245	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	246	virtual IOReturn wakeAtTimeUS(UInt32 us);
	247
	248	/*! @function wakeAtTime
	249	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
	250	@param abstime Time to wake up in some unit.
	251	@param scale_factor Define the unit of abstime, default to nanoseconds.
	252	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	253	virtual IOReturn wakeAtTime(UInt32 abstime,
	254	UInt32 scale_factor = kNanosecondScale);
	255
b0d623f7 A	256	#if !defined(__LP64__)
	257	virtual IOReturn wakeAtTime(mach_timespec_t abstime)
	258	APPLE_KEXT_DEPRECATED;
	259	#endif
1c79356b A	260
	261	/*! @function wakeAtTime
	262	@abstract Setup a callback at this absolute time.
5ba3f43e	263	@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	264	@param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
	265	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
	266	virtual IOReturn wakeAtTime(AbsoluteTime abstime);
	267
	268	/*! @function cancelTimeout
	269	@abstract Disable any outstanding calls to this event source.
	270	@discussion Clear down any oustanding calls. By the time this function completes it is guaranteed that the action will not be called again. */
	271	virtual void cancelTimeout();
	272
5ba3f43e A	273	/*! @function init
	274	@abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
	275	*/
	276	virtual bool init(uint32_t options, OSObject *inOwner, Action inAction);
	277
	278	/*! @function setTimeout
	279	@abstract Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
	280	@param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
	281	@param interval Delay from now to wake up in decrementer ticks.
	282	@param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
	283	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	284	virtual IOReturn setTimeout(uint32_t options, AbsoluteTime interval, AbsoluteTime leeway);
	285
	286	/*! @function wakeAtTime
	287	@abstract Setup a callback at this absolute time.
	288	@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.
	289	@param options see kIOTimeOptionsWithLeeway and kIOTimeOptionsContinuous
	290	@param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
	291	@param leeway Allowable leeway to wake time, if the kIOTimeOptionsWithLeeway option is set
	292	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
	293	virtual IOReturn wakeAtTime(uint32_t options, AbsoluteTime abstime, AbsoluteTime leeway);
	294
91447636	295	private:
5ba3f43e A	296	static void timeoutAndRelease(void self, void c);
5ba3f43e A	297	static void timeoutSignaled(void self, void c);
91447636	298
1c79356b	299	private:
5ba3f43e A	300	OSMetaClassDeclareReservedUsed(IOTimerEventSource, 0);
	301	OSMetaClassDeclareReservedUsed(IOTimerEventSource, 1);
	302	OSMetaClassDeclareReservedUsed(IOTimerEventSource, 2);
1c79356b A	303	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
	304	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
	305	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
	306	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
	307	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
	308	};
	309
	310	#endif /* !_IOTIMEREVENTSOURCE */