1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="Generic-IRQ-Guide">
6 <bookinfo>
7  <title>Linux generic IRQ handling</title>
8
9  <authorgroup>
10   <author>
11    <firstname>Thomas</firstname>
12    <surname>Gleixner</surname>
13    <affiliation>
14     <address>
15      <email>tglx@linutronix.de</email>
16     </address>
17    </affiliation>
18   </author>
19   <author>
20    <firstname>Ingo</firstname>
21    <surname>Molnar</surname>
22    <affiliation>
23     <address>
24      <email>mingo@elte.hu</email>
25     </address>
26    </affiliation>
27   </author>
28  </authorgroup>
29
30  <copyright>
31   <year>2005-2006</year>
32   <holder>Thomas Gleixner</holder>
33  </copyright>
34  <copyright>
35   <year>2005-2006</year>
36   <holder>Ingo Molnar</holder>
37  </copyright>
38
39  <legalnotice>
40   <para>
41     This documentation is free software; you can redistribute
42     it and/or modify it under the terms of the GNU General Public
43     License version 2 as published by the Free Software Foundation.
44   </para>
45
46   <para>
47     This program is distributed in the hope that it will be
48     useful, but WITHOUT ANY WARRANTY; without even the implied
49     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
50     See the GNU General Public License for more details.
51   </para>
52
53   <para>
54     You should have received a copy of the GNU General Public
55     License along with this program; if not, write to the Free
56     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
57     MA 02111-1307 USA
58   </para>
59
60   <para>
61     For more details see the file COPYING in the source
62     distribution of Linux.
63   </para>
64  </legalnotice>
65 </bookinfo>
66
67<toc></toc>
68
69  <chapter id="intro">
70    <title>Introduction</title>
71    <para>
72	The generic interrupt handling layer is designed to provide a
73	complete abstraction of interrupt handling for device drivers.
74	It is able to handle all the different types of interrupt controller
75	hardware. Device drivers use generic API functions to request, enable,
76	disable and free interrupts. The drivers do not have to know anything
77	about interrupt hardware details, so they can be used on different
78	platforms without code changes.
79    </para>
80    <para>
81  	This documentation is provided to developers who want to implement
82	an interrupt subsystem based for their architecture, with the help
83	of the generic IRQ handling layer.
84    </para>
85  </chapter>
86
87  <chapter id="rationale">
88    <title>Rationale</title>
89	<para>
90	The original implementation of interrupt handling in Linux is using
91	the __do_IRQ() super-handler, which is able to deal with every
92	type of interrupt logic.
93	</para>
94	<para>
95	Originally, Russell King identified different types of handlers to
96	build a quite universal set for the ARM interrupt handler
97	implementation in Linux 2.5/2.6. He distinguished between:
98	<itemizedlist>
99	  <listitem><para>Level type</para></listitem>
100	  <listitem><para>Edge type</para></listitem>
101	  <listitem><para>Simple type</para></listitem>
102	</itemizedlist>
103	In the SMP world of the __do_IRQ() super-handler another type
104	was identified:
105	<itemizedlist>
106	  <listitem><para>Per CPU type</para></listitem>
107	</itemizedlist>
108	</para>
109	<para>
110	This split implementation of highlevel IRQ handlers allows us to
111	optimize the flow of the interrupt handling for each specific
112	interrupt type. This reduces complexity in that particular codepath
113	and allows the optimized handling of a given type.
114	</para>
115	<para>
116	The original general IRQ implementation used hw_interrupt_type
117	structures and their ->ack(), ->end() [etc.] callbacks to
118	differentiate the flow control in the super-handler. This leads to
119	a mix of flow logic and lowlevel hardware logic, and it also leads
120	to unnecessary code duplication: for example in i386, there is a
121	ioapic_level_irq and a ioapic_edge_irq irq-type which share many
122	of the lowlevel details but have different flow handling.
123	</para>
124	<para>
125	A more natural abstraction is the clean separation of the
126	'irq flow' and the 'chip details'.
127	</para>
128	<para>
129	Analysing a couple of architecture's IRQ subsystem implementations
130	reveals that most of them can use a generic set of 'irq flow'
131	methods and only need to add the chip level specific code.
132	The separation is also valuable for (sub)architectures
133	which need specific quirks in the irq flow itself but not in the
134	chip-details - and thus provides a more transparent IRQ subsystem
135	design.
136	</para>
137	<para>
138	Each interrupt descriptor is assigned its own highlevel flow
139	handler, which is normally one of the generic
140	implementations. (This highlevel flow handler implementation also
141	makes it simple to provide demultiplexing handlers which can be
142	found in embedded platforms on various architectures.)
143	</para>
144	<para>
145	The separation makes the generic interrupt handling layer more
146	flexible and extensible. For example, an (sub)architecture can
147	use a generic irq-flow implementation for 'level type' interrupts
148	and add a (sub)architecture specific 'edge type' implementation.
149	</para>
150	<para>
151	To make the transition to the new model easier and prevent the
152	breakage of existing implementations, the __do_IRQ() super-handler
153	is still available. This leads to a kind of duality for the time
154	being. Over time the new model should be used in more and more
155	architectures, as it enables smaller and cleaner IRQ subsystems.
156	</para>
157  </chapter>
158  <chapter id="bugs">
159    <title>Known Bugs And Assumptions</title>
160    <para>
161	None (knock on wood).
162    </para>
163  </chapter>
164
165  <chapter id="Abstraction">
166    <title>Abstraction layers</title>
167    <para>
168	There are three main levels of abstraction in the interrupt code:
169	<orderedlist>
170	  <listitem><para>Highlevel driver API</para></listitem>
171	  <listitem><para>Highlevel IRQ flow handlers</para></listitem>
172	  <listitem><para>Chiplevel hardware encapsulation</para></listitem>
173	</orderedlist>
174    </para>
175    <sect1>
176	<title>Interrupt control flow</title>
177	<para>
178	Each interrupt is described by an interrupt descriptor structure
179	irq_desc. The interrupt is referenced by an 'unsigned int' numeric
180	value which selects the corresponding interrupt decription structure
181	in the descriptor structures array.
182	The descriptor structure contains status information and pointers
183	to the interrupt flow method and the interrupt chip structure
184	which are assigned to this interrupt.
185	</para>
186	<para>
187	Whenever an interrupt triggers, the lowlevel arch code calls into
188	the generic interrupt code by calling desc->handle_irq().
189	This highlevel IRQ handling function only uses desc->chip primitives
190	referenced by the assigned chip descriptor structure.
191	</para>
192    </sect1>
193    <sect1>
194	<title>Highlevel Driver API</title>
195	<para>
196	  The highlevel Driver API consists of following functions:
197	  <itemizedlist>
198	  <listitem><para>request_irq()</para></listitem>
199	  <listitem><para>free_irq()</para></listitem>
200	  <listitem><para>disable_irq()</para></listitem>
201	  <listitem><para>enable_irq()</para></listitem>
202	  <listitem><para>disable_irq_nosync() (SMP only)</para></listitem>
203	  <listitem><para>synchronize_irq() (SMP only)</para></listitem>
204	  <listitem><para>set_irq_type()</para></listitem>
205	  <listitem><para>set_irq_wake()</para></listitem>
206	  <listitem><para>set_irq_data()</para></listitem>
207	  <listitem><para>set_irq_chip()</para></listitem>
208	  <listitem><para>set_irq_chip_data()</para></listitem>
209          </itemizedlist>
210	  See the autogenerated function documentation for details.
211	</para>
212    </sect1>
213    <sect1>
214	<title>Highlevel IRQ flow handlers</title>
215	<para>
216	  The generic layer provides a set of pre-defined irq-flow methods:
217	  <itemizedlist>
218	  <listitem><para>handle_level_irq</para></listitem>
219	  <listitem><para>handle_edge_irq</para></listitem>
220	  <listitem><para>handle_simple_irq</para></listitem>
221	  <listitem><para>handle_percpu_irq</para></listitem>
222	  </itemizedlist>
223	  The interrupt flow handlers (either predefined or architecture
224	  specific) are assigned to specific interrupts by the architecture
225	  either during bootup or during device initialization.
226	</para>
227	<sect2>
228	<title>Default flow implementations</title>
229	    <sect3>
230	 	<title>Helper functions</title>
231		<para>
232		The helper functions call the chip primitives and
233		are used by the default flow implementations.
234		The following helper functions are implemented (simplified excerpt):
235		<programlisting>
236default_enable(irq)
237{
238	desc->chip->unmask(irq);
239}
240
241default_disable(irq)
242{
243	if (!delay_disable(irq))
244		desc->chip->mask(irq);
245}
246
247default_ack(irq)
248{
249	chip->ack(irq);
250}
251
252default_mask_ack(irq)
253{
254	if (chip->mask_ack) {
255		chip->mask_ack(irq);
256	} else {
257		chip->mask(irq);
258		chip->ack(irq);
259	}
260}
261
262noop(irq)
263{
264}
265
266		</programlisting>
267	        </para>
268	    </sect3>
269	</sect2>
270	<sect2>
271	<title>Default flow handler implementations</title>
272	    <sect3>
273	 	<title>Default Level IRQ flow handler</title>
274		<para>
275		handle_level_irq provides a generic implementation
276		for level-triggered interrupts.
277		</para>
278		<para>
279		The following control flow is implemented (simplified excerpt):
280		<programlisting>
281desc->chip->start();
282handle_IRQ_event(desc->action);
283desc->chip->end();
284		</programlisting>
285		</para>
286   	    </sect3>
287	    <sect3>
288	 	<title>Default Edge IRQ flow handler</title>
289		<para>
290		handle_edge_irq provides a generic implementation
291		for edge-triggered interrupts.
292		</para>
293		<para>
294		The following control flow is implemented (simplified excerpt):
295		<programlisting>
296if (desc->status &amp; running) {
297	desc->chip->hold();
298	desc->status |= pending | masked;
299	return;
300}
301desc->chip->start();
302desc->status |= running;
303do {
304	if (desc->status &amp; masked)
305		desc->chip->enable();
306	desc->status &amp;= ~pending;
307	handle_IRQ_event(desc->action);
308} while (status &amp; pending);
309desc->status &amp;= ~running;
310desc->chip->end();
311		</programlisting>
312		</para>
313   	    </sect3>
314	    <sect3>
315	 	<title>Default simple IRQ flow handler</title>
316		<para>
317		handle_simple_irq provides a generic implementation
318		for simple interrupts.
319		</para>
320		<para>
321		Note: The simple flow handler does not call any
322		handler/chip primitives.
323		</para>
324		<para>
325		The following control flow is implemented (simplified excerpt):
326		<programlisting>
327handle_IRQ_event(desc->action);
328		</programlisting>
329		</para>
330   	    </sect3>
331	    <sect3>
332	 	<title>Default per CPU flow handler</title>
333		<para>
334		handle_percpu_irq provides a generic implementation
335		for per CPU interrupts.
336		</para>
337		<para>
338		Per CPU interrupts are only available on SMP and
339		the handler provides a simplified version without
340		locking.
341		</para>
342		<para>
343		The following control flow is implemented (simplified excerpt):
344		<programlisting>
345desc->chip->start();
346handle_IRQ_event(desc->action);
347desc->chip->end();
348		</programlisting>
349		</para>
350   	    </sect3>
351	</sect2>
352	<sect2>
353	<title>Quirks and optimizations</title>
354	<para>
355	The generic functions are intended for 'clean' architectures and chips,
356	which have no platform-specific IRQ handling quirks. If an architecture
357	needs to implement quirks on the 'flow' level then it can do so by
358	overriding the highlevel irq-flow handler.
359	</para>
360	</sect2>
361	<sect2>
362	<title>Delayed interrupt disable</title>
363	<para>
364	This per interrupt selectable feature, which was introduced by Russell
365	King in the ARM interrupt implementation, does not mask an interrupt
366	at the hardware level when disable_irq() is called. The interrupt is
367	kept enabled and is masked in the flow handler when an interrupt event
368	happens. This prevents losing edge interrupts on hardware which does
369	not store an edge interrupt event while the interrupt is disabled at
370	the hardware level. When an interrupt arrives while the IRQ_DISABLED
371	flag is set, then the interrupt is masked at the hardware level and
372	the IRQ_PENDING bit is set. When the interrupt is re-enabled by
373	enable_irq() the pending bit is checked and if it is set, the
374	interrupt is resent either via hardware or by a software resend
375	mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when
376	you want to use the delayed interrupt disable feature and your
377	hardware is not capable of retriggering	an interrupt.)
378	The delayed interrupt disable can be runtime enabled, per interrupt,
379	by setting the IRQ_DELAYED_DISABLE flag in the irq_desc status field.
380	</para>
381	</sect2>
382    </sect1>
383    <sect1>
384	<title>Chiplevel hardware encapsulation</title>
385	<para>
386	The chip level hardware descriptor structure irq_chip
387	contains all the direct chip relevant functions, which
388	can be utilized by the irq flow implementations.
389	  <itemizedlist>
390	  <listitem><para>ack()</para></listitem>
391	  <listitem><para>mask_ack() - Optional, recommended for performance</para></listitem>
392	  <listitem><para>mask()</para></listitem>
393	  <listitem><para>unmask()</para></listitem>
394	  <listitem><para>retrigger() - Optional</para></listitem>
395	  <listitem><para>set_type() - Optional</para></listitem>
396	  <listitem><para>set_wake() - Optional</para></listitem>
397	  </itemizedlist>
398	These primitives are strictly intended to mean what they say: ack means
399	ACK, masking means masking of an IRQ line, etc. It is up to the flow
400	handler(s) to use these basic units of lowlevel functionality.
401	</para>
402    </sect1>
403  </chapter>
404
405  <chapter id="doirq">
406     <title>__do_IRQ entry point</title>
407     <para>
408 	The original implementation __do_IRQ() is an alternative entry
409	point for all types of interrupts.
410     </para>
411     <para>
412	This handler turned out to be not suitable for all
413	interrupt hardware and was therefore reimplemented with split
414	functionality for egde/level/simple/percpu interrupts. This is not
415	only a functional optimization. It also shortens code paths for
416	interrupts.
417      </para>
418      <para>
419	To make use of the split implementation, replace the call to
420	__do_IRQ by a call to desc->chip->handle_irq() and associate
421        the appropriate handler function to desc->chip->handle_irq().
422	In most cases the generic handler implementations should
423	be sufficient.
424     </para>
425  </chapter>
426
427  <chapter id="locking">
428     <title>Locking on SMP</title>
429     <para>
430	The locking of chip registers is up to the architecture that
431	defines the chip primitives. There is a chip->lock field that can be used
432	for serialization, but the generic layer does not touch it. The per-irq
433	structure is protected via desc->lock, by the generic layer.
434     </para>
435  </chapter>
436  <chapter id="structs">
437     <title>Structures</title>
438     <para>
439     This chapter contains the autogenerated documentation of the structures which are
440     used in the generic IRQ layer.
441     </para>
442!Iinclude/linux/irq.h
443  </chapter>
444
445  <chapter id="pubfunctions">
446     <title>Public Functions Provided</title>
447     <para>
448     This chapter contains the autogenerated documentation of the kernel API functions
449      which are exported.
450     </para>
451!Ekernel/irq/manage.c
452!Ekernel/irq/chip.c
453  </chapter>
454
455  <chapter id="intfunctions">
456     <title>Internal Functions Provided</title>
457     <para>
458     This chapter contains the autogenerated documentation of the internal functions.
459     </para>
460!Ikernel/irq/handle.c
461!Ikernel/irq/chip.c
462  </chapter>
463
464  <chapter id="credits">
465     <title>Credits</title>
466	<para>
467		The following people have contributed to this document:
468		<orderedlist>
469			<listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
470			<listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem>
471		</orderedlist>
472	</para>
473  </chapter>
474</book>
475