[linux.git] / Documentation / arm / Interrupts

2.5.2-rmk5
----------

This is the first kernel that contains a major shake up of some of the
major architecture-specific subsystems.

Firstly, it contains some pretty major changes to the way we handle the
MMU TLB.  Each MMU TLB variant is now handled completely separately -
we have TLB v3, TLB v4 (without write buffer), TLB v4 (with write buffer),
and finally TLB v4 (with write buffer, with I TLB invalidate entry).
There is more assembly code inside each of these functions, mainly to
allow more flexible TLB handling for the future.

Secondly, the IRQ subsystem.

The 2.5 kernels will be having major changes to the way IRQs are handled.
Unfortunately, this means that machine types that touch the irq_desc[]
array (basically all machine types) will break, and this means every
machine type that we currently have.

Lets take an example.  On the Assabet with Neponset, we have:

                  GPIO25                 IRR:2
        SA1100 ------------> Neponset -----------> SA1111
                                         IIR:1
                                      -----------> USAR
                                         IIR:0
                                      -----------> SMC9196

The way stuff currently works, all SA1111 interrupts are mutually
exclusive of each other - if you're processing one interrupt from the
SA1111 and another comes in, you have to wait for that interrupt to
finish processing before you can service the new interrupt.  Eg, an
IDE PIO-based interrupt on the SA1111 excludes all other SA1111 and
SMC9196 interrupts until it has finished transferring its multi-sector
data, which can be a long time.  Note also that since we loop in the
SA1111 IRQ handler, SA1111 IRQs can hold off SMC9196 IRQs indefinitely.


The new approach brings several new ideas...

We introduce the concept of a "parent" and a "child".  For example,
to the Neponset handler, the "parent" is GPIO25, and the "children"d
are SA1111, SMC9196 and USAR.

We also bring the idea of an IRQ "chip" (mainly to reduce the size of
the irqdesc array).  This doesn't have to be a real "IC"; indeed the
SA11x0 IRQs are handled by two separate "chip" structures, one for
GPIO0-10, and another for all the rest.  It is just a container for
the various operations (maybe this'll change to a better name).
This structure has the following operations:

struct irqchip {
        /*
         * Acknowledge the IRQ.
         * If this is a level-based IRQ, then it is expected to mask the IRQ
         * as well.
         */
        void (*ack)(unsigned int irq);
        /*
         * Mask the IRQ in hardware.
         */
        void (*mask)(unsigned int irq);
        /*
         * Unmask the IRQ in hardware.
         */
        void (*unmask)(unsigned int irq);
        /*
         * Re-run the IRQ
         */
        void (*rerun)(unsigned int irq);
        /*
         * Set the type of the IRQ.
         */
        int (*type)(unsigned int irq, unsigned int, type);
};

ack    - required.  May be the same function as mask for IRQs
         handled by do_level_IRQ.
mask   - required.
unmask - required.
rerun  - optional.  Not required if you're using do_level_IRQ for all
         IRQs that use this 'irqchip'.  Generally expected to re-trigger
         the hardware IRQ if possible.  If not, may call the handler
	 directly.
type   - optional.  If you don't support changing the type of an IRQ,
         it should be null so people can detect if they are unable to
         set the IRQ type.

For each IRQ, we keep the following information:

        - "disable" depth (number of disable_irq()s without enable_irq()s)
        - flags indicating what we can do with this IRQ (valid, probe,
          noautounmask) as before
        - status of the IRQ (probing, enable, etc)
        - chip
        - per-IRQ handler
        - irqaction structure list

The handler can be one of the 3 standard handlers - "level", "edge" and
"simple", or your own specific handler if you need to do something special.

The "level" handler is what we currently have - its pretty simple.
"edge" knows about the brokenness of such IRQ implementations - that you
need to leave the hardware IRQ enabled while processing it, and queueing
further IRQ events should the IRQ happen again while processing.  The
"simple" handler is very basic, and does not perform any hardware
manipulation, nor state tracking.  This is useful for things like the
SMC9196 and USAR above.

So, what's changed?

1. Machine implementations must not write to the irqdesc array.

2. New functions to manipulate the irqdesc array.  The first 4 are expected
   to be useful only to machine specific code.  The last is recommended to
   only be used by machine specific code, but may be used in drivers if
   absolutely necessary.

        set_irq_chip(irq,chip)

                Set the mask/unmask methods for handling this IRQ

        set_irq_handler(irq,handler)

                Set the handler for this IRQ (level, edge, simple)

        set_irq_chained_handler(irq,handler)

                Set a "chained" handler for this IRQ - automatically
                enables this IRQ (eg, Neponset and SA1111 handlers).

        set_irq_flags(irq,flags)

                Set the valid/probe/noautoenable flags.

        set_irq_type(irq,type)

                Set active the IRQ edge(s)/level.  This replaces the
                SA1111 INTPOL manipulation, and the set_GPIO_IRQ_edge()
                function.  Type should be one of IRQ_TYPE_xxx defined in
		<linux/irq.h>

3. set_GPIO_IRQ_edge() is obsolete, and should be replaced by set_irq_type.

4. Direct access to SA1111 INTPOL is deprecated.  Use set_irq_type instead.

5. A handler is expected to perform any necessary acknowledgement of the
   parent IRQ via the correct chip specific function.  For instance, if
   the SA1111 is directly connected to a SA1110 GPIO, then you should
   acknowledge the SA1110 IRQ each time you re-read the SA1111 IRQ status.

6. For any child which doesn't have its own IRQ enable/disable controls
   (eg, SMC9196), the handler must mask or acknowledge the parent IRQ
   while the child handler is called, and the child handler should be the
   "simple" handler (not "edge" nor "level").  After the handler completes,
   the parent IRQ should be unmasked, and the status of all children must
   be re-checked for pending events.  (see the Neponset IRQ handler for
   details).

7. fixup_irq() is gone, as is arch/arm/mach-*/include/mach/irq.h

Please note that this will not solve all problems - some of them are
hardware based.  Mixing level-based and edge-based IRQs on the same
parent signal (eg neponset) is one such area where a software based
solution can't provide the full answer to low IRQ latency.
Commit	Line	Data
1da177e4 LT	1	2.5.2-rmk5
	2	----------
	3
	4	This is the first kernel that contains a major shake up of some of the
	5	major architecture-specific subsystems.
	6
	7	Firstly, it contains some pretty major changes to the way we handle the
	8	MMU TLB. Each MMU TLB variant is now handled completely separately -
	9	we have TLB v3, TLB v4 (without write buffer), TLB v4 (with write buffer),
	10	and finally TLB v4 (with write buffer, with I TLB invalidate entry).
	11	There is more assembly code inside each of these functions, mainly to
	12	allow more flexible TLB handling for the future.
	13
	14	Secondly, the IRQ subsystem.
	15
	16	The 2.5 kernels will be having major changes to the way IRQs are handled.
	17	Unfortunately, this means that machine types that touch the irq_desc[]
	18	array (basically all machine types) will break, and this means every
	19	machine type that we currently have.
	20
	21	Lets take an example. On the Assabet with Neponset, we have:
	22
	23	GPIO25 IRR:2
	24	SA1100 ------------> Neponset -----------> SA1111
	25	IIR:1
	26	-----------> USAR
	27	IIR:0
	28	-----------> SMC9196
	29
	30	The way stuff currently works, all SA1111 interrupts are mutually
	31	exclusive of each other - if you're processing one interrupt from the
	32	SA1111 and another comes in, you have to wait for that interrupt to
	33	finish processing before you can service the new interrupt. Eg, an
	34	IDE PIO-based interrupt on the SA1111 excludes all other SA1111 and
	35	SMC9196 interrupts until it has finished transferring its multi-sector
	36	data, which can be a long time. Note also that since we loop in the
	37	SA1111 IRQ handler, SA1111 IRQs can hold off SMC9196 IRQs indefinitely.
	38
	39
	40	The new approach brings several new ideas...
	41
	42	We introduce the concept of a "parent" and a "child". For example,
	43	to the Neponset handler, the "parent" is GPIO25, and the "children"d
	44	are SA1111, SMC9196 and USAR.
	45
	46	We also bring the idea of an IRQ "chip" (mainly to reduce the size of
	47	the irqdesc array). This doesn't have to be a real "IC"; indeed the
	48	SA11x0 IRQs are handled by two separate "chip" structures, one for
	49	GPIO0-10, and another for all the rest. It is just a container for
	50	the various operations (maybe this'll change to a better name).
	51	This structure has the following operations:
	52
	53	struct irqchip {
	54	/*
	55	* Acknowledge the IRQ.
	56	* If this is a level-based IRQ, then it is expected to mask the IRQ
	57	* as well.
	58	*/
	59	void (*ack)(unsigned int irq);
	60	/*
	61	* Mask the IRQ in hardware.
	62	*/
	63	void (*mask)(unsigned int irq);
	64	/*
65	* Unmask the IRQ in hardware.
66	*/
67	void (*unmask)(unsigned int irq);
68	/*
69	* Re-run the IRQ
70	*/
71	void (*rerun)(unsigned int irq);
72	/*
73	* Set the type of the IRQ.
74	*/
75	int (*type)(unsigned int irq, unsigned int, type);
76	};
77
78	ack - required. May be the same function as mask for IRQs
79	handled by do_level_IRQ.
80	mask - required.
81	unmask - required.
82	rerun - optional. Not required if you're using do_level_IRQ for all
83	IRQs that use this 'irqchip'. Generally expected to re-trigger
84	the hardware IRQ if possible. If not, may call the handler
85	directly.
86	type - optional. If you don't support changing the type of an IRQ,
87	it should be null so people can detect if they are unable to
88	set the IRQ type.
89
90	For each IRQ, we keep the following information:
91
92	- "disable" depth (number of disable_irq()s without enable_irq()s)
93	- flags indicating what we can do with this IRQ (valid, probe,
94	noautounmask) as before
95	- status of the IRQ (probing, enable, etc)
96	- chip
97	- per-IRQ handler
98	- irqaction structure list
99
100	The handler can be one of the 3 standard handlers - "level", "edge" and
101	"simple", or your own specific handler if you need to do something special.
102
103	The "level" handler is what we currently have - its pretty simple.
104	"edge" knows about the brokenness of such IRQ implementations - that you
105	need to leave the hardware IRQ enabled while processing it, and queueing
106	further IRQ events should the IRQ happen again while processing. The
107	"simple" handler is very basic, and does not perform any hardware
108	manipulation, nor state tracking. This is useful for things like the
109	SMC9196 and USAR above.
110
111	So, what's changed?
112
113	1. Machine implementations must not write to the irqdesc array.
114
115	2. New functions to manipulate the irqdesc array. The first 4 are expected
116	to be useful only to machine specific code. The last is recommended to
117	only be used by machine specific code, but may be used in drivers if
118	absolutely necessary.
119
120	set_irq_chip(irq,chip)
121
122	Set the mask/unmask methods for handling this IRQ
123
124	set_irq_handler(irq,handler)
125
126	Set the handler for this IRQ (level, edge, simple)
127
128	set_irq_chained_handler(irq,handler)
129
130	Set a "chained" handler for this IRQ - automatically
131	enables this IRQ (eg, Neponset and SA1111 handlers).
132
133	set_irq_flags(irq,flags)
134
135	Set the valid/probe/noautoenable flags.
136
137	set_irq_type(irq,type)
138
139	Set active the IRQ edge(s)/level. This replaces the
140	SA1111 INTPOL manipulation, and the set_GPIO_IRQ_edge()
6cab4860 DB	141	function. Type should be one of IRQ_TYPE_xxx defined in
6cab4860 DB	142	<linux/irq.h>
1da177e4 LT	143
	144	3. set_GPIO_IRQ_edge() is obsolete, and should be replaced by set_irq_type.
	145
1591275c	146	4. Direct access to SA1111 INTPOL is deprecated. Use set_irq_type instead.
1da177e4 LT	147
	148	5. A handler is expected to perform any necessary acknowledgement of the
	149	parent IRQ via the correct chip specific function. For instance, if
	150	the SA1111 is directly connected to a SA1110 GPIO, then you should
	151	acknowledge the SA1110 IRQ each time you re-read the SA1111 IRQ status.
	152
	153	6. For any child which doesn't have its own IRQ enable/disable controls
	154	(eg, SMC9196), the handler must mask or acknowledge the parent IRQ
	155	while the child handler is called, and the child handler should be the
	156	"simple" handler (not "edge" nor "level"). After the handler completes,
	157	the parent IRQ should be unmasked, and the status of all children must
	158	be re-checked for pending events. (see the Neponset IRQ handler for
	159	details).
	160
a09e64fb	161	7. fixup_irq() is gone, as is arch/arm/mach-*/include/mach/irq.h
1da177e4 LT	162
	163	Please note that this will not solve all problems - some of them are
	164	hardware based. Mixing level-based and edge-based IRQs on the same
	165	parent signal (eg neponset) is one such area where a software based
	166	solution can't provide the full answer to low IRQ latency.
	167