KTIMER

The KTIMER is the kernel’s representation of a timer object. Like all dispatcher objects, timers can be waited on until they get signalled. As an elaboration that is not supported for all dispatcher objects, a timer’s usefulness comes not just from being waitable. It can also be configured so that signalling causes a Deferred Procedure Call (DPC) to be scheduled. For timers, signalling is done by the kernel on noticing that a specified time has been reached. This specified time can be absolute or relative, the former being a system time, the latter being a difference from the current interrupt time.

Kernel-mode code allocates space for a KTIMER and gets it ready for use by calling either KeInitializeTimer or the newer, more capable, KeInitializeTimerEx. Thereafter, conditions for the timer’s expiration can be specified through the progressively newer and more capable functions KeSetTimer, KeSetTimerEx and KeSetCoalescableTimer. These functions each reset the timer to be non-signalled.

The kernel itself exposes timer objects to the Object Manager. Code in both kernel mode and user mode can call NtCreateTimer or ZwCreateTimer, as appropriate, to get the kernel to create a KTIMER within an ETIMER, which is then made accessible through a handle. A timer that is created this way can have a name, such that another handle can be obtained, most usefully in another process, by calling NtOpenTimer or ZwOpenTimer. Of course, well-behaved user-mode code doesn’t call these native API functions directly but instead goes through such higher-level functions as CreateWaitableTimerEx and OpenWaitableTimer which are exported from KERNEL32.

Layout

In all versions, the KTIMER is 0x28 and 0x40 bytes in 32-bit and 64-bit Windows respectively.

DISPATCHER_HEADER Header;

ULARGE_INTEGER DueTime;

LIST_ENTRY TimerListEntry;

KDPC *Dpc;

ULONG Processor;

USHORT Processor;

USHORT TimerType;

BOOLEAN Inserted;

LONG Period;

ULONG Period;

The DueTime is the interrupt time at which the timer is set to expire.

Of several expansions of functionality that Windows NT 4.0 brought to timers, automatically restarting the timer at repeating intervals required more storage in the KTIMER. Three bytes had been left undefined as a side-effect of alignment after the Inserted member. To find four bytes for saving the whole Period that could be given to the new KeSetTimerEx function, the Inserted member was moved into the DISPATCHER_HEADER, taking space from the Size.

Dispatcher Header

Much of the new functionality in successive versions has been accommodated by finding space inside the Header. The DISPATCHER_HEADER is a complex structure that begins all kernel objects that can be waited on. The following tables simplify by disregarding the nested unions, extracting only the branches that apply to timers.

SHORT Type;

UCHAR Type;

UCHAR TimerType;

UCHAR Spare;

UCHAR Absolute;

union {
    UCHAR TimerControlFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

SHORT Size;

USHORT Size;

UCHAR Size;

UCHAR Hand;

UCHAR Inserted;

union {
    UCHAR TimerMiscFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

LONG SignalState;

LIST_ENTRY WaitListHead;

As for all dispatchable objects, the low 7 bits of the Type—or all 8 bits in version 3.51—are from the KOBJECTS enumeration. For the KTIMER specifically, these bits are 0x08 (TimerNotificationObject) or 0x09 (TimerSynchronizationObject) according to whether NotificationTimer or SynchronizationTimer is given as the Type argument when initialising the timer through the KeInitializeTimerEx function.