irq(4)

NAME
	irq - driver to delivery hardware interrupts to user space.

SYNOPSIS
	#include <linux/irq.h>

	int fd = open(devname, openflags);

	int rc = irq_request(int fd, int sig, int flags);
	int rc = irq_free(int fd);

	int rc = irq_enable(int fd);
	int rc = irq_disable(int fd);

	int rc = irq_skipping_on(int fd);
	int rc = irq_skipping_off(int fd);

	int rc = irq_skipping_consent(int fd);
	int rc = irq_skipping_inconsent(int fd);

	int rc = irq_simulate(int fd);

	void irq_simulate(int irq);

	int rc = irq_stat(int fd, struct irq_stat* stat);

	int nsel=select(int n,	fd_set* readfds,
				fd_set* writefds,
				fd_set* exceptfds,
				struct timeval* timeout);



DESCRIPTION
	irq[0-15] - character device which allow user space programs
	access to hardware interrupts (IRQ).


	int fd = open(devname, openflags);

		devname
			device file name ("/dev/irqN")

		N
			IRQ number: 0..NR_IRQS-1.
			NR_IRQS defined in <asm/irq.h>.

		openflags
			Can be only O_RDONLY or O_WRONLY or O_RDWR.
			See <asm/fcntl.h> and open(2).



	int rc = irq_request(int fd, int sig, int flags);

		It create interrupt notifications delivery channel for
		current process. One process can has one delivery
		channel only per IRQ simultaneously. To make this
		request the device must be opened with O_RDWR flag.
		All remaining functions except irq_simulate() and
		irq_stat() must be called only after successful
		irq_request() call.

		sig
			Signal number for interrupt notification of the
			process or -1 if select(2) only will be used.
			Usually SIGUSR1 or SIGUSR2 used.
			See sigaction(2) and signal(7).

		flags
			bitwise-or'd with one or more of the following:

			IRQ_SHARED
				The process agree to share IRQ with
				other system devices and processes
				which used this driver. Other devices
				or processes must be agree also to
				share this IRQ. If the process
				disagreed to share IRQ it must be first
				requester.

			IRQ_SKIPPING
				Sets interrupt skipping state for all
				processes which are agree with it.
				Disagreed processes will be receive all
				interrupts. See irq_skipping_on().

			IRQ_SKIPPING_CONSENT
				Sets agreement with interrupt skipping
				state. See irq_skipping_consent().


		See also request_irq(9) for details.

		Information about driver usage displayed by
		/proc/interrupts in form:

			irq:pid.sig
				for processes using signals

			or

			irq:pid
				for processes not using signals

		example:

$ cat /proc/interrupt

 0:    3294731   timer
 1:      70305   keyboard
 2:          0   cascade
 3:      78645 + serial
 4:          8 + serial
10:          0   irq:2589.12, irq:2592, irq:2594.12, irq:2596
12:     635424   NE2000
13:          1   math error
14:      99101 + ide0
15:          0 + ide1



	int rc = irq_free(int fd);

		Free IRQ. Complement to irq_request().
		See free_irq(9).



	int rc = irq_enable(int fd);
	int rc = irq_disable(int fd);

		Enable/disable interrupt in Programmable Interrupt
		Controller (PIC). To do it interrupt must not be
		shared. This is artificial driver's limitation.
		See enable_irq(9) and disable_irq(9).



	int rc = irq_skipping_on(int fd);
	int rc = irq_skipping_off(int fd);

		Turn interrupt skipping state on/off for all processes
		which are agree with it. Disagreed processes will be
		receive all interrupts. Nested calls allowed: number of
		off() calls must be equal to number of on() calls.
		irq_skipping_on() and irq_skipping_off() used to form
		critical section in some rare case.



	int rc = irq_skipping_consent(int fd);

		Sets interrupt skipping consent state.



	int rc = irq_skipping_inconsent(int fd);

		Unsets interrupt skipping consent state.



	int rc = irq_simulate(int fd);

		Interrupt simulation. All of interrupt requesters will
		receive interrupt notifications with take into account
		their skipping and skipping consent states but without
		take into account irq_disable().



	void irq_simulate(int irq);

		This function exported for other kernel modules only.
		Calls from other interrupt service routines allowed.



	int rc = irq_stat(int fd, struct irq_stat* stat);

		Not yet implemented.



	int nsel=select(int n,	fd_set* readfds,
				fd_set* writefds,
				fd_set* exceptfds,
				struct timeval* timeout);

		select(2) used to wait interrupts.
		File descriptor of device must be in read descriptor set.




RETURN VALUES

	fd
		File descriptor obtained from open(2) and used for rest
		of operations. See open(2).

	rc
		ioctl(2) return code,



ERRORS

	EBADFD	Assertion failed, driver developer's error,
		see kernel log for a message.


	open(2);

		ENXIO	No such device or address:
			IRQ number >= NR_IRQS
			This can mean that the device file was
			installed incorrectly.

		EINVAL	Invalid argument:
			openflags contains something out of O_ACCMODE.

		Rest of errno codes described in open(2).


	irq_request();

		EACCES	Permission denied:
			Device was opened without write mode.

		EINVAL	Invalid argument:
			Invalid signal number or unknown flag.

		EBUSY	Device or resource busy:
			This process already own this IRQ or

			other processes/device drivers already own this
			IRQ and their agreement of sharing do not
			coincide with this

			or there are other drivers which already own
			IRQ and agree to share it but their interrupt
			service routines are "fast" and IRQ driver use
			"slow" one only.


		ENOMEM	Out of memory:

			Insufficient kernel memory to create internal
			structures.


	irq_free();

		EPERM	Operation not permitted:
			IRQ was not requested.

		EACCES	Permission denied:
			This process does not own of this interrupt
			delivery channel.


	irq_enable();

		EPERM	Operation not permitted:
			IRQ not requested or IRQ not shared.

		EACCES	Permission denied:
			This process does not own of this interrupt
			delivery channel.


	irq_disable();

		EPERM	Operation not permitted:
			IRQ was not requested or IRQ not shared.

		EACCES	Permission denied:
			This process does not own of this interrupt
			delivery channel.


	irq_skipping_on();

		EPERM	Operation not permitted:
			IRQ not requested or IRQ not shared.

		EACCES	Permission denied:
			This process does not own of this interrupt
			delivery channel.


	irq_skipping_off();

		EPERM	Operation not permitted:
			IRQ was not requested or number of off() calls
			greater than number of on() calls.

		EACCES	Permission denied:
			This process does not own of this interrupt
			delivery channel.


	irq_skipping_consent();
	irq_skipping_inconsent();

		EPERM	Operation not permitted:
			IRQ not requested.

		EACCES	Permission denied:
			This process does not own of this interrupt
			delivery channel.


	irq_simulate();

		EACCES	Permission denied:
			Device was opened without write mode.



FILES
	/dev/irq[0-15]
	/proc/interrupts

AUTHOR
	(C) 1997 Dmitry A. Fedorov, fedorov@inp.nsk.su

BUGS
	irq_simulate() does not take into account IRQ disabled state
	(disable_irq(9)) because of officially impossible to know
	current state.

	irq_stat() not implemented.


$Id: irq.4.txt,v 1.8 2003/07/13 14:13:13 fedorov Exp $

