[linux-block.git] / Documentation / timers / hpet.rst

===========================================
High Precision Event Timer Driver for Linux
===========================================

The High Precision Event Timer (HPET) hardware follows a specification
by Intel and Microsoft, revision 1.

Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision")
and up to 32 comparators.  Normally three or more comparators are provided,
each of which can generate oneshot interrupts and at least one of which has
additional hardware to support periodic interrupts.  The comparators are
also called "timers", which can be misleading since usually timers are
independent of each other ... these share a counter, complicating resets.

HPET devices can support two interrupt routing modes.  In one mode, the
comparators are additional interrupt sources with no particular system
role.  Many x86 BIOS writers don't route HPET interrupts at all, which
prevents use of that mode.  They support the other "legacy replacement"
mode where the first two comparators block interrupts from 8254 timers
and from the RTC.

The driver supports detection of HPET driver allocation and initialization
of the HPET before the driver module_init routine is called.  This enables
platform code which uses timer 0 or 1 as the main timer to intercept HPET
initialization.  An example of this initialization can be found in
arch/x86/kernel/hpet.c.

The driver provides a userspace API which resembles the API found in the
RTC driver framework.  An example user space program is provided in
file:samples/timers/hpet_example.c
Commit	Line	Data
458f69ef MCC	1	===========================================
	2	High Precision Event Timer Driver for Linux
	3	===========================================
1da177e4	4
64a76f66	5	The High Precision Event Timer (HPET) hardware follows a specification
4e7f9df2	6	by Intel and Microsoft, revision 1.
64a76f66 DB	7
	8	Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision")
	9	and up to 32 comparators. Normally three or more comparators are provided,
19f59460	10	each of which can generate oneshot interrupts and at least one of which has
64a76f66 DB	11	additional hardware to support periodic interrupts. The comparators are
	12	also called "timers", which can be misleading since usually timers are
	13	independent of each other ... these share a counter, complicating resets.
	14
	15	HPET devices can support two interrupt routing modes. In one mode, the
	16	comparators are additional interrupt sources with no particular system
	17	role. Many x86 BIOS writers don't route HPET interrupts at all, which
	18	prevents use of that mode. They support the other "legacy replacement"
	19	mode where the first two comparators block interrupts from 8254 timers
	20	and from the RTC.
8a0d4900 RD	21
	22	The driver supports detection of HPET driver allocation and initialization
	23	of the HPET before the driver module_init routine is called. This enables
	24	platform code which uses timer 0 or 1 as the main timer to intercept HPET
	25	initialization. An example of this initialization can be found in
64a76f66	26	arch/x86/kernel/hpet.c.
1da177e4	27
64a76f66	28	The driver provides a userspace API which resembles the API found in the
e6186309	29	RTC driver framework. An example user space program is provided in
155fe001	30	file:samples/timers/hpet_example.c