[net-next-2.6.git] / Documentation / hpet.txt

		High Precision Event Timer Driver for Linux

The High Precision Event Timer (HPET) hardware is the future replacement for the 8254 and Real
Time Clock (RTC) periodic timer functionality.  Each HPET can have up two 32 timers.  It is possible
to configure the first two timers as legacy replacements for 8254 and RTC periodic.  A specification
done by INTEL and Microsoft can be found at http://www.intel.com/labs/platcomp/hpet/hpetspec.htm.

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/i386/kernel/time_hpet.c.

The driver provides two APIs which are very similar to the API found in the rtc.c driver.
There is a user space API and a kernel space API.  An example user space program is provided
below.

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <memory.h>
#include <malloc.h>
#include <time.h>
#include <ctype.h>
#include <sys/types.h>
#include <sys/wait.h>
#include <signal.h>
#include <fcntl.h>
#include <errno.h>
#include <sys/time.h>
#include <linux/hpet.h>


extern void hpet_open_close(int, const char **);
extern void hpet_info(int, const char **);
extern void hpet_poll(int, const char **);
extern void hpet_fasync(int, const char **);
extern void hpet_read(int, const char **);

#include <sys/poll.h>
#include <sys/ioctl.h>
#include <signal.h>

struct hpet_command {
	char		*command;
	void		(*func)(int argc, const char ** argv);
} hpet_command[] = {
	{
		"open-close",
		hpet_open_close
	},
	{
		"info",
		hpet_info
	},
	{
		"poll",
		hpet_poll
	},
	{
		"fasync",
		hpet_fasync
	},
};

int
main(int argc, const char ** argv)
{
	int	i;

	argc--;
	argv++;

	if (!argc) {
		fprintf(stderr, "-hpet: requires command\n");
		return -1;
	}


	for (i = 0; i < (sizeof (hpet_command) / sizeof (hpet_command[0])); i++)
		if (!strcmp(argv[0], hpet_command[i].command)) {
			argc--;
			argv++;
			fprintf(stderr, "-hpet: executing %s\n",
				hpet_command[i].command);
			hpet_command[i].func(argc, argv);
			return 0;
		}

	fprintf(stderr, "do_hpet: command %s not implemented\n", argv[0]);

	return -1;
}

void
hpet_open_close(int argc, const char **argv)
{
	int	fd;

	if (argc != 1) {
		fprintf(stderr, "hpet_open_close: device-name\n");
		return;
	}

	fd = open(argv[0], O_RDONLY);
	if (fd < 0)
		fprintf(stderr, "hpet_open_close: open failed\n");
	else
		close(fd);

	return;
}

void
hpet_info(int argc, const char **argv)
{
}

void
hpet_poll(int argc, const char **argv)
{
	unsigned long		freq;
	int			iterations, i, fd;
	struct pollfd		pfd;
	struct hpet_info	info;
	struct timeval		stv, etv;
	struct timezone		tz;
	long			usec;

	if (argc != 3) {
		fprintf(stderr, "hpet_poll: device-name freq iterations\n");
		return;
	}

	freq = atoi(argv[1]);
	iterations = atoi(argv[2]);

	fd = open(argv[0], O_RDONLY);

	if (fd < 0) {
		fprintf(stderr, "hpet_poll: open of %s failed\n", argv[0]);
		return;
	}

	if (ioctl(fd, HPET_IRQFREQ, freq) < 0) {
		fprintf(stderr, "hpet_poll: HPET_IRQFREQ failed\n");
		goto out;
	}

	if (ioctl(fd, HPET_INFO, &info) < 0) {
		fprintf(stderr, "hpet_poll: failed to get info\n");
		goto out;
	}

	fprintf(stderr, "hpet_poll: info.hi_flags 0x%lx\n", info.hi_flags);

	if (info.hi_flags && (ioctl(fd, HPET_EPI, 0) < 0)) {
		fprintf(stderr, "hpet_poll: HPET_EPI failed\n");
		goto out;
	}

	if (ioctl(fd, HPET_IE_ON, 0) < 0) {
		fprintf(stderr, "hpet_poll, HPET_IE_ON failed\n");
		goto out;
	}

	pfd.fd = fd;
	pfd.events = POLLIN;

	for (i = 0; i < iterations; i++) {
		pfd.revents = 0;
		gettimeofday(&stv, &tz);
		if (poll(&pfd, 1, -1) < 0)
			fprintf(stderr, "hpet_poll: poll failed\n");
		else {
			long 	data;

			gettimeofday(&etv, &tz);
			usec = stv.tv_sec * 1000000 + stv.tv_usec;
			usec = (etv.tv_sec * 1000000 + etv.tv_usec) - usec;

			fprintf(stderr,
				"hpet_poll: expired time = 0x%lx\n", usec);

			fprintf(stderr, "hpet_poll: revents = 0x%x\n",
				pfd.revents);

			if (read(fd, &data, sizeof(data)) != sizeof(data)) {
				fprintf(stderr, "hpet_poll: read failed\n");
			}
			else
				fprintf(stderr, "hpet_poll: data 0x%lx\n",
					data);
		}
	}

out:
	close(fd);
	return;
}

static int hpet_sigio_count;

static void
hpet_sigio(int val)
{
	fprintf(stderr, "hpet_sigio: called\n");
	hpet_sigio_count++;
}

void
hpet_fasync(int argc, const char **argv)
{
	unsigned long		freq;
	int			iterations, i, fd, value;
	sig_t			oldsig;
	struct hpet_info	info;

	hpet_sigio_count = 0;
	fd = -1;

	if ((oldsig = signal(SIGIO, hpet_sigio)) == SIG_ERR) {
		fprintf(stderr, "hpet_fasync: failed to set signal handler\n");
		return;
	}

	if (argc != 3) {
		fprintf(stderr, "hpet_fasync: device-name freq iterations\n");
		goto out;
	}

	fd = open(argv[0], O_RDONLY);

	if (fd < 0) {
		fprintf(stderr, "hpet_fasync: failed to open %s\n", argv[0]);
		return;
	}


	if ((fcntl(fd, F_SETOWN, getpid()) == 1) ||
		((value = fcntl(fd, F_GETFL)) == 1) ||
		(fcntl(fd, F_SETFL, value | O_ASYNC) == 1)) {
		fprintf(stderr, "hpet_fasync: fcntl failed\n");
		goto out;
	}

	freq = atoi(argv[1]);
	iterations = atoi(argv[2]);

	if (ioctl(fd, HPET_IRQFREQ, freq) < 0) {
		fprintf(stderr, "hpet_fasync: HPET_IRQFREQ failed\n");
		goto out;
	}

	if (ioctl(fd, HPET_INFO, &info) < 0) {
		fprintf(stderr, "hpet_fasync: failed to get info\n");
		goto out;
	}

	fprintf(stderr, "hpet_fasync: info.hi_flags 0x%lx\n", info.hi_flags);

	if (info.hi_flags && (ioctl(fd, HPET_EPI, 0) < 0)) {
		fprintf(stderr, "hpet_fasync: HPET_EPI failed\n");
		goto out;
	}

	if (ioctl(fd, HPET_IE_ON, 0) < 0) {
		fprintf(stderr, "hpet_fasync, HPET_IE_ON failed\n");
		goto out;
	}

	for (i = 0; i < iterations; i++) {
		(void) pause();
		fprintf(stderr, "hpet_fasync: count = %d\n", hpet_sigio_count);
	}

out:
	signal(SIGIO, oldsig);

	if (fd >= 0)
		close(fd);

	return;
}

The kernel API has three interfaces exported from the driver:

	hpet_register(struct hpet_task *tp, int periodic)
	hpet_unregister(struct hpet_task *tp)
	hpet_control(struct hpet_task *tp, unsigned int cmd, unsigned long arg)

The kernel module using this interface fills in the ht_func and ht_data members of the
hpet_task structure before calling hpet_register.  hpet_control simply vectors to the hpet_ioctl
routine and has the same commands and respective arguments as the user API.  hpet_unregister
is used to terminate usage of the HPET timer reserved by hpet_register.
Commit	Line	Data
1da177e4 LT	1	High Precision Event Timer Driver for Linux
	2
	3	The High Precision Event Timer (HPET) hardware is the future replacement for the 8254 and Real
	4	Time Clock (RTC) periodic timer functionality. Each HPET can have up two 32 timers. It is possible
	5	to configure the first two timers as legacy replacements for 8254 and RTC periodic. A specification
	6	done by INTEL and Microsoft can be found at http://www.intel.com/labs/platcomp/hpet/hpetspec.htm.
	7
	8	The driver supports detection of HPET driver allocation and initialization of the HPET before the
	9	driver module_init routine is called. This enables platform code which uses timer 0 or 1 as the
	10	main timer to intercept HPET initialization. An example of this initialization can be found in
	11	arch/i386/kernel/time_hpet.c.
	12
	13	The driver provides two APIs which are very similar to the API found in the rtc.c driver.
	14	There is a user space API and a kernel space API. An example user space program is provided
	15	below.
	16
	17	#include <stdio.h>
	18	#include <stdlib.h>
	19	#include <unistd.h>
	20	#include <fcntl.h>
	21	#include <string.h>
	22	#include <memory.h>
	23	#include <malloc.h>
	24	#include <time.h>
	25	#include <ctype.h>
	26	#include <sys/types.h>
	27	#include <sys/wait.h>
	28	#include <signal.h>
	29	#include <fcntl.h>
	30	#include <errno.h>
	31	#include <sys/time.h>
	32	#include <linux/hpet.h>
	33
	34
	35	extern void hpet_open_close(int, const char **);
	36	extern void hpet_info(int, const char **);
	37	extern void hpet_poll(int, const char **);
	38	extern void hpet_fasync(int, const char **);
	39	extern void hpet_read(int, const char **);
	40
	41	#include <sys/poll.h>
	42	#include <sys/ioctl.h>
	43	#include <signal.h>
	44
	45	struct hpet_command {
	46	char *command;
	47	void (func)(int argc, const char * argv);
	48	} hpet_command[] = {
	49	{
	50	"open-close",
	51	hpet_open_close
	52	},
	53	{
	54	"info",
	55	hpet_info
	56	},
	57	{
	58	"poll",
	59	hpet_poll
	60	},
	61	{
	62	"fasync",
	63	hpet_fasync
	64	},
65	};
66
67	int
68	main(int argc, const char ** argv)
69	{
70	int i;
71
72	argc--;
73	argv++;
74
75	if (!argc) {
76	fprintf(stderr, "-hpet: requires command\n");
77	return -1;
78	}
79
80
81	for (i = 0; i < (sizeof (hpet_command) / sizeof (hpet_command[0])); i++)
82	if (!strcmp(argv[0], hpet_command[i].command)) {
83	argc--;
84	argv++;
85	fprintf(stderr, "-hpet: executing %s\n",
86	hpet_command[i].command);
87	hpet_command[i].func(argc, argv);
88	return 0;
89	}
90
91	fprintf(stderr, "do_hpet: command %s not implemented\n", argv[0]);
92
93	return -1;
94	}
95
96	void
97	hpet_open_close(int argc, const char **argv)
98	{
99	int fd;
100
101	if (argc != 1) {
102	fprintf(stderr, "hpet_open_close: device-name\n");
103	return;
104	}
105
106	fd = open(argv[0], O_RDONLY);
107	if (fd < 0)
108	fprintf(stderr, "hpet_open_close: open failed\n");
109	else
110	close(fd);
111
112	return;
113	}
114
115	void
116	hpet_info(int argc, const char **argv)
117	{
118	}
119
120	void
121	hpet_poll(int argc, const char **argv)
122	{
123	unsigned long freq;
124	int iterations, i, fd;
125	struct pollfd pfd;
126	struct hpet_info info;
127	struct timeval stv, etv;
128	struct timezone tz;
129	long usec;
130
131	if (argc != 3) {
132	fprintf(stderr, "hpet_poll: device-name freq iterations\n");
133	return;
134	}
135
136	freq = atoi(argv[1]);
137	iterations = atoi(argv[2]);
138
139	fd = open(argv[0], O_RDONLY);
140
141	if (fd < 0) {
142	fprintf(stderr, "hpet_poll: open of %s failed\n", argv[0]);
143	return;
144	}
145
146	if (ioctl(fd, HPET_IRQFREQ, freq) < 0) {
147	fprintf(stderr, "hpet_poll: HPET_IRQFREQ failed\n");
148	goto out;
149	}
150
151	if (ioctl(fd, HPET_INFO, &info) < 0) {
152	fprintf(stderr, "hpet_poll: failed to get info\n");
153	goto out;
154	}
155
156	fprintf(stderr, "hpet_poll: info.hi_flags 0x%lx\n", info.hi_flags);
157
158	if (info.hi_flags && (ioctl(fd, HPET_EPI, 0) < 0)) {
159	fprintf(stderr, "hpet_poll: HPET_EPI failed\n");
160	goto out;
161	}
162
163	if (ioctl(fd, HPET_IE_ON, 0) < 0) {
164	fprintf(stderr, "hpet_poll, HPET_IE_ON failed\n");
165	goto out;
166	}
167
168	pfd.fd = fd;
169	pfd.events = POLLIN;
170
171	for (i = 0; i < iterations; i++) {
172	pfd.revents = 0;
173	gettimeofday(&stv, &tz);
174	if (poll(&pfd, 1, -1) < 0)
175	fprintf(stderr, "hpet_poll: poll failed\n");
176	else {
177	long data;
178
179	gettimeofday(&etv, &tz);
180	usec = stv.tv_sec * 1000000 + stv.tv_usec;
181	usec = (etv.tv_sec * 1000000 + etv.tv_usec) - usec;
182
183	fprintf(stderr,
184	"hpet_poll: expired time = 0x%lx\n", usec);
185
186	fprintf(stderr, "hpet_poll: revents = 0x%x\n",
187	pfd.revents);
188
189	if (read(fd, &data, sizeof(data)) != sizeof(data)) {
190	fprintf(stderr, "hpet_poll: read failed\n");
191	}
192	else
193	fprintf(stderr, "hpet_poll: data 0x%lx\n",
194	data);
195	}
196	}
197
198	out:
199	close(fd);
200	return;
201	}
202
203	static int hpet_sigio_count;
204
205	static void
206	hpet_sigio(int val)
207	{
208	fprintf(stderr, "hpet_sigio: called\n");
209	hpet_sigio_count++;
210	}
211
212	void
213	hpet_fasync(int argc, const char **argv)
214	{
215	unsigned long freq;
216	int iterations, i, fd, value;
217	sig_t oldsig;
218	struct hpet_info info;
219
220	hpet_sigio_count = 0;
221	fd = -1;
222
223	if ((oldsig = signal(SIGIO, hpet_sigio)) == SIG_ERR) {
224	fprintf(stderr, "hpet_fasync: failed to set signal handler\n");
225	return;
226	}
227
228	if (argc != 3) {
229	fprintf(stderr, "hpet_fasync: device-name freq iterations\n");
230	goto out;
231	}
232
233	fd = open(argv[0], O_RDONLY);
234
235	if (fd < 0) {
236	fprintf(stderr, "hpet_fasync: failed to open %s\n", argv[0]);
237	return;
238	}
239
240
241	if ((fcntl(fd, F_SETOWN, getpid()) == 1) \|\|
242	((value = fcntl(fd, F_GETFL)) == 1) \|\|
243	(fcntl(fd, F_SETFL, value \| O_ASYNC) == 1)) {
244	fprintf(stderr, "hpet_fasync: fcntl failed\n");
245	goto out;
246	}
247
248	freq = atoi(argv[1]);
249	iterations = atoi(argv[2]);
250
251	if (ioctl(fd, HPET_IRQFREQ, freq) < 0) {
252	fprintf(stderr, "hpet_fasync: HPET_IRQFREQ failed\n");
253	goto out;
254	}
255
256	if (ioctl(fd, HPET_INFO, &info) < 0) {
257	fprintf(stderr, "hpet_fasync: failed to get info\n");
258	goto out;
259	}
260
261	fprintf(stderr, "hpet_fasync: info.hi_flags 0x%lx\n", info.hi_flags);
262
263	if (info.hi_flags && (ioctl(fd, HPET_EPI, 0) < 0)) {
264	fprintf(stderr, "hpet_fasync: HPET_EPI failed\n");
265	goto out;
266	}
267
268	if (ioctl(fd, HPET_IE_ON, 0) < 0) {
269	fprintf(stderr, "hpet_fasync, HPET_IE_ON failed\n");
270	goto out;
271	}
272
273	for (i = 0; i < iterations; i++) {
274	(void) pause();
275	fprintf(stderr, "hpet_fasync: count = %d\n", hpet_sigio_count);
276	}
277
278	out:
279	signal(SIGIO, oldsig);
280
281	if (fd >= 0)
282	close(fd);
283
284	return;
285	}
286
287	The kernel API has three interfaces exported from the driver:
288
289	hpet_register(struct hpet_task *tp, int periodic)
290	hpet_unregister(struct hpet_task *tp)
291	hpet_control(struct hpet_task *tp, unsigned int cmd, unsigned long arg)
292
293	The kernel module using this interface fills in the ht_func and ht_data members of the
294	hpet_task structure before calling hpet_register. hpet_control simply vectors to the hpet_ioctl
295	routine and has the same commands and respective arguments as the user API. hpet_unregister
296	is used to terminate usage of the HPET timer reserved by hpet_register.
297
298