ExXxxTimer Routines and EX_TIMER Objects - Windows drivers (original) (raw)
Starting with Windows 8.1, a comprehensive set of Ex_Xxx_Timer routines is available to manage timers. These routines use timer objects that are based on the EX_TIMER structure. The Ex_Xxx_Timer routines are replacements for the Ke_Xxx_Timer routines, which are available starting with Windows 2000. Drivers intended to run only on Windows 8.1 and later versions of Windows can use the Ex_Xxx_Timer routines instead of the Ke_Xxx_Timer routines. Windows 8.1 and later versions of Windows continue to support the Ke_Xxx_Timer routines.
The Ex_Xxx_Timer routines have all the important capabilities that are provided by the Ke_Xxx_Timer routines. In addition, the Ex_Xxx_Timer routines support two timer types, high-resolution timers and no-wake timers, that are not supported by the Ke_Xxx_Timer routines. High-resolution timers are timers whose expiration times can be specified with higher accuracy than those of timers whose accuracy is limited by the default resolution of the system clock. No-wake timers are timers that avoid unnecessarily waking processors from low-power states. For more information, see the following topics:
Starting with Windows 8.1, the following Ex_Xxx_Timer routines are available:
The ExSetTimer routine can be used instead of the KeSetTimer or KeSetTimerEx routine. The ExCancelTimer routine can be used instead of the KeCancelTimer routine.
The ExAllocateTimer and ExDeleteTimer routines have no direct Ke_Xxx_Timer counterparts. These two routines allocate and free a timer object. This timer object is a system-allocated EX_TIMER structure whose members are opaque to drivers. In contrast, the timer object used by the Ke_Xxx_Timer routines is a driver-allocated KTIMER structure. The driver calls the KeInitializeTimer or KeInitializeTimerEx routine to initialize this object. ExAllocateTimer initializes the timer objects that it allocates. For more information about ExDeleteTimer, see Deleting a System-Allocated Timer Object.
EX_TIMER and KTIMER structures are waitable objects. After a driver calls ExSetTimer, KeSetTimer, or KeSetTimerEx to set a timer, the driver can call a routine such as KeWaitForSingleObject or KeWaitForMultipleObjects to wait for the timer to expire. The timer object is signaled when the timer expires. As an option, a driver can supply a pointer to a driver-implemented ExTimerCallback or CustomTimerDpc callback routine that the operating system calls after the timer expires.
The Ke_Xxx_Timer routines have two capabilities that are not provided by the Ex_Xxx_Timer routines, but these capabilities are not needed by most drivers.
First, the KTIMER structure used as a timer object by the Ke_Xxx_Timer routines is driver-allocated. The driver can preallocate this object to ensure that the object is available even in circumstances in which resources are constrained and memory allocations can fail. In contrast, a call to ExAllocateTimer to allocate a timer object might fail in a resource-constrained environment. However, few drivers need to be designed to operate in environments in which memory allocations fail, and most drivers benefit from the convenience of an ExAllocateTimer routine that both allocates and initializes a timer object.
Second, there is no Ex_Xxx_Timer equivalent of the KeReadStateTimer routine, which indicates whether a timer object is in the signaled state. However, this routine is rarely used. If necessary, a driver that uses the Ex_Xxx_Timer routines can check whether a timer object is in the signaled state by reading a Boolean value that is set by the ExTimerCallback callback routine that the driver supplies to the ExAllocateTimer routine.