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

/*
 * Copyright (c) 1998-2000, 2009 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>

/*!
    @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;
        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();

    virtual void setWorkLoop(IOWorkLoop *workLoop);

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);

/*! @function timerEventSource
    @abstract Allocates and returns an initialized timer instance.
    @param owner
    @param action */
    static IOTimerEventSource *
	timerEventSource(OSObject *owner, Action action = 0);

/*! @function init
    @abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
    @param owner 
    @param action */
    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();

/*! @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();


/*! @function setTimeoutTicks
    @abstract Setup a callback at after the delay in scheduler ticks.  See wakeAtTime(AbsoluteTime).
    @param interval 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 interval 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 interval 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 abstime 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 abstime 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 abstime 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();

private:
    static void timeoutAndRelease(void *self, void *wl);

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

#endif /* !_IOTIMEREVENTSOURCE */
Commit	Line	Data
1c79356b	1	/*
6d2010ae	2	* Copyright (c) 1998-2000, 2009 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
	50	/*!
	51	@class IOTimerEventSource : public IOEventSource
	52	@abstract Time based event source mechanism.
	53	@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.
	54	<br><br>
	55	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.
	56	<br><br>
	57	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.
	58	*/
	59	class IOTimerEventSource : public IOEventSource
	60	{
	61	OSDeclareDefaultStructors(IOTimerEventSource)
	62
	63	protected:
	64	/! @var calloutEntry thread_call entry for preregistered thread callouts /
	65	void *calloutEntry;
	66
	67	/! @var abstime time to wake up next, see enable. /
	68	AbsoluteTime abstime;
	69
	70	/*! @struct ExpansionData
91447636	71	@discussion This structure is private to the IOTimerEventSource implementation.
1c79356b	72	*/
91447636 A	73	struct ExpansionData
	74	{
	75	SInt32 calloutGeneration;
	76	IOWorkLoop * workLoop;
	77	};
1c79356b A	78
	79	/*! @var reserved
	80	Reserved for future use. (Internal use only) */
	81	ExpansionData *reserved;
	82
	83	/*! @function timeout
	84	@abstract Function that routes the call from the OS' timeout mechanism into a work-loop context.
	85	@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.
	86	@param self This argument will be cast to an IOTimerEventSource. */
	87	static void timeout(void *self);
	88
	89	/*! @function setTimeoutFunc
	90	@abstract Set's timeout as the function of calloutEntry.
	91	@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. */
	92	virtual void setTimeoutFunc();
	93
	94	/*! @function free
	95	@abstract Sub-class implementation of free method, frees calloutEntry */
	96	virtual void free();
	97
91447636 A	98	virtual void setWorkLoop(IOWorkLoop *workLoop);
91447636 A	99
1c79356b A	100	public:
	101
	102	/*! @typedef Action
	103	@discussion 'C' Function pointer defining the callout routine of this event source.
	104	@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.
	105	@param sender The object that timed out. */
	106	typedef void (Action)(OSObject owner, IOTimerEventSource *sender);
	107
	108	/*! @function timerEventSource
	109	@abstract Allocates and returns an initialized timer instance.
	110	@param owner
	111	@param action */
	112	static IOTimerEventSource *
	113	timerEventSource(OSObject *owner, Action action = 0);
	114
	115	/*! @function init
	116	@abstract Initializes the timer with an owner, and a handler to call when the timeout expires.
	117	@param owner
	118	@param action */
	119	virtual bool init(OSObject *owner, Action action = 0);
	120
	121	/*! @function enable
	122	@abstract Enables a call to the action.
	123	@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. */
	124	virtual void enable();
	125
	126	/*! @function disable
	127	@abstract Disable a timed callout.
	128	@discussion When disable returns the action will not be called until the next time enable(qv) is called. */
	129	virtual void disable();
	130
	131
	132	/*! @function setTimeoutTicks
	133	@abstract Setup a callback at after the delay in scheduler ticks. See wakeAtTime(AbsoluteTime).
	134	@param interval Delay from now to wake up, in scheduler ticks, whatever that may be.
	135	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	136	virtual IOReturn setTimeoutTicks(UInt32 ticks);
	137
	138	/*! @function setTimeoutMS
	139	@abstract Setup a callback at after the delay in milliseconds. See wakeAtTime(AbsoluteTime).
	140	@param interval Delay from now to wake up, time in milliseconds.
	141	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	142	virtual IOReturn setTimeoutMS(UInt32 ms);
	143
	144	/*! @function setTimeoutUS
	145	@abstract Setup a callback at after the delay in microseconds. See wakeAtTime(AbsoluteTime).
	146	@param interval Delay from now to wake up, time in microseconds.
	147	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	148	virtual IOReturn setTimeoutUS(UInt32 us);
	149
	150	/*! @function setTimeout
	151	@abstract Setup a callback at after the delay in some unit. See wakeAtTime(AbsoluteTime).
	152	@param interval Delay from now to wake up in some defined unit.
	153	@param scale_factor Define the unit of interval, default to nanoseconds.
	154	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	155	virtual IOReturn setTimeout(UInt32 interval,
	156	UInt32 scale_factor = kNanosecondScale);
	157
b0d623f7 A	158	#if !defined(__LP64__)
	159	virtual IOReturn setTimeout(mach_timespec_t interval)
	160	APPLE_KEXT_DEPRECATED;
	161	#endif
1c79356b A	162
	163	/*! @function setTimeout
	164	@abstract Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
	165	@param interval Delay from now to wake up in decrementer ticks.
	166	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	167	virtual IOReturn setTimeout(AbsoluteTime interval);
	168
	169	/*! @function wakeAtTimeTicks
	170	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
	171	@param abstime Time to wake up in scheduler quantums, whatever that is?
	172	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	173	virtual IOReturn wakeAtTimeTicks(UInt32 ticks);
	174
	175	/*! @function wakeAtTimeMS
	176	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
	177	@param abstime Time to wake up in milliseconds.
	178	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	179	virtual IOReturn wakeAtTimeMS(UInt32 ms);
	180
	181	/*! @function wakeAtTimeUS
	182	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
	183	@param abstime Time to wake up in microseconds.
	184	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	185	virtual IOReturn wakeAtTimeUS(UInt32 us);
	186
	187	/*! @function wakeAtTime
	188	@abstract Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
	189	@param abstime Time to wake up in some unit.
	190	@param scale_factor Define the unit of abstime, default to nanoseconds.
	191	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared. */
	192	virtual IOReturn wakeAtTime(UInt32 abstime,
	193	UInt32 scale_factor = kNanosecondScale);
	194
b0d623f7 A	195	#if !defined(__LP64__)
	196	virtual IOReturn wakeAtTime(mach_timespec_t abstime)
	197	APPLE_KEXT_DEPRECATED;
	198	#endif
1c79356b A	199
	200	/*! @function wakeAtTime
	201	@abstract Setup a callback at this absolute time.
	202	@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.
	203	@param abstime Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.
	204	@result kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv). */
	205	virtual IOReturn wakeAtTime(AbsoluteTime abstime);
	206
	207	/*! @function cancelTimeout
	208	@abstract Disable any outstanding calls to this event source.
	209	@discussion Clear down any oustanding calls. By the time this function completes it is guaranteed that the action will not be called again. */
	210	virtual void cancelTimeout();
	211
91447636 A	212	private:
	213	static void timeoutAndRelease(void self, void wl);
	214
1c79356b A	215	private:
	216	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 0);
	217	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 1);
	218	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 2);
	219	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 3);
	220	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 4);
	221	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 5);
	222	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 6);
	223	OSMetaClassDeclareReservedUnused(IOTimerEventSource, 7);
	224	};
	225
	226	#endif /* !_IOTIMEREVENTSOURCE */