blob: 59fb5c077541b15f6f319a17cbf259195c9849f0 [file] [log] [blame]
Thomas Gleixner11c869e2006-06-29 02:24:47 -07001<?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>
Thomas Gleixner25ade602010-09-30 20:33:11 +020031 <year>2005-2010</year>
Thomas Gleixner11c869e2006-06-29 02:24:47 -070032 <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>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -070090 The original implementation of interrupt handling in Linux uses
Thomas Gleixner11c869e2006-06-29 02:24:47 -070091 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>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200103 During the implementation we identified another type:
104 <itemizedlist>
105 <listitem><para>Fast EOI type</para></listitem>
106 </itemizedlist>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700107 In the SMP world of the __do_IRQ() super-handler another type
108 was identified:
109 <itemizedlist>
110 <listitem><para>Per CPU type</para></listitem>
111 </itemizedlist>
112 </para>
113 <para>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700114 This split implementation of high-level IRQ handlers allows us to
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700115 optimize the flow of the interrupt handling for each specific
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700116 interrupt type. This reduces complexity in that particular code path
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700117 and allows the optimized handling of a given type.
118 </para>
119 <para>
120 The original general IRQ implementation used hw_interrupt_type
121 structures and their ->ack(), ->end() [etc.] callbacks to
122 differentiate the flow control in the super-handler. This leads to
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700123 a mix of flow logic and low-level hardware logic, and it also leads
124 to unnecessary code duplication: for example in i386, there is an
125 ioapic_level_irq and an ioapic_edge_irq IRQ-type which share many
126 of the low-level details but have different flow handling.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700127 </para>
128 <para>
129 A more natural abstraction is the clean separation of the
130 'irq flow' and the 'chip details'.
131 </para>
132 <para>
133 Analysing a couple of architecture's IRQ subsystem implementations
134 reveals that most of them can use a generic set of 'irq flow'
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700135 methods and only need to add the chip-level specific code.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700136 The separation is also valuable for (sub)architectures
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700137 which need specific quirks in the IRQ flow itself but not in the
138 chip details - and thus provides a more transparent IRQ subsystem
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700139 design.
140 </para>
141 <para>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700142 Each interrupt descriptor is assigned its own high-level flow
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700143 handler, which is normally one of the generic
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700144 implementations. (This high-level flow handler implementation also
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700145 makes it simple to provide demultiplexing handlers which can be
146 found in embedded platforms on various architectures.)
147 </para>
148 <para>
149 The separation makes the generic interrupt handling layer more
150 flexible and extensible. For example, an (sub)architecture can
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700151 use a generic IRQ-flow implementation for 'level type' interrupts
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700152 and add a (sub)architecture specific 'edge type' implementation.
153 </para>
154 <para>
155 To make the transition to the new model easier and prevent the
156 breakage of existing implementations, the __do_IRQ() super-handler
157 is still available. This leads to a kind of duality for the time
158 being. Over time the new model should be used in more and more
159 architectures, as it enables smaller and cleaner IRQ subsystems.
Thomas Gleixner25ade602010-09-30 20:33:11 +0200160 It's deprecated for three years now and about to be removed.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700161 </para>
162 </chapter>
163 <chapter id="bugs">
164 <title>Known Bugs And Assumptions</title>
165 <para>
166 None (knock on wood).
167 </para>
168 </chapter>
169
170 <chapter id="Abstraction">
171 <title>Abstraction layers</title>
172 <para>
173 There are three main levels of abstraction in the interrupt code:
174 <orderedlist>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700175 <listitem><para>High-level driver API</para></listitem>
176 <listitem><para>High-level IRQ flow handlers</para></listitem>
177 <listitem><para>Chip-level hardware encapsulation</para></listitem>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700178 </orderedlist>
179 </para>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800180 <sect1 id="Interrupt_control_flow">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700181 <title>Interrupt control flow</title>
182 <para>
183 Each interrupt is described by an interrupt descriptor structure
184 irq_desc. The interrupt is referenced by an 'unsigned int' numeric
Masanari Iida0ba4f6e2014-07-12 09:55:28 -0700185 value which selects the corresponding interrupt description structure
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700186 in the descriptor structures array.
187 The descriptor structure contains status information and pointers
188 to the interrupt flow method and the interrupt chip structure
189 which are assigned to this interrupt.
190 </para>
191 <para>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700192 Whenever an interrupt triggers, the low-level architecture code calls
193 into the generic interrupt code by calling desc->handle_irq().
194 This high-level IRQ handling function only uses desc->irq_data.chip
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200195 primitives referenced by the assigned chip descriptor structure.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700196 </para>
197 </sect1>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800198 <sect1 id="Highlevel_Driver_API">
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700199 <title>High-level Driver API</title>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700200 <para>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700201 The high-level Driver API consists of following functions:
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700202 <itemizedlist>
203 <listitem><para>request_irq()</para></listitem>
204 <listitem><para>free_irq()</para></listitem>
205 <listitem><para>disable_irq()</para></listitem>
206 <listitem><para>enable_irq()</para></listitem>
207 <listitem><para>disable_irq_nosync() (SMP only)</para></listitem>
208 <listitem><para>synchronize_irq() (SMP only)</para></listitem>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200209 <listitem><para>irq_set_irq_type()</para></listitem>
210 <listitem><para>irq_set_irq_wake()</para></listitem>
211 <listitem><para>irq_set_handler_data()</para></listitem>
212 <listitem><para>irq_set_chip()</para></listitem>
213 <listitem><para>irq_set_chip_data()</para></listitem>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700214 </itemizedlist>
215 See the autogenerated function documentation for details.
216 </para>
217 </sect1>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800218 <sect1 id="Highlevel_IRQ_flow_handlers">
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700219 <title>High-level IRQ flow handlers</title>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700220 <para>
221 The generic layer provides a set of pre-defined irq-flow methods:
222 <itemizedlist>
223 <listitem><para>handle_level_irq</para></listitem>
224 <listitem><para>handle_edge_irq</para></listitem>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200225 <listitem><para>handle_fasteoi_irq</para></listitem>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700226 <listitem><para>handle_simple_irq</para></listitem>
227 <listitem><para>handle_percpu_irq</para></listitem>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200228 <listitem><para>handle_edge_eoi_irq</para></listitem>
229 <listitem><para>handle_bad_irq</para></listitem>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700230 </itemizedlist>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700231 The interrupt flow handlers (either pre-defined or architecture
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700232 specific) are assigned to specific interrupts by the architecture
233 either during bootup or during device initialization.
234 </para>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800235 <sect2 id="Default_flow_implementations">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700236 <title>Default flow implementations</title>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800237 <sect3 id="Helper_functions">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700238 <title>Helper functions</title>
239 <para>
240 The helper functions call the chip primitives and
241 are used by the default flow implementations.
242 The following helper functions are implemented (simplified excerpt):
243 <programlisting>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200244default_enable(struct irq_data *data)
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700245{
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200246 desc->irq_data.chip->irq_unmask(data);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700247}
248
Thomas Gleixner25ade602010-09-30 20:33:11 +0200249default_disable(struct irq_data *data)
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700250{
Thomas Gleixner25ade602010-09-30 20:33:11 +0200251 if (!delay_disable(data))
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200252 desc->irq_data.chip->irq_mask(data);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700253}
254
Thomas Gleixner25ade602010-09-30 20:33:11 +0200255default_ack(struct irq_data *data)
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700256{
Thomas Gleixner25ade602010-09-30 20:33:11 +0200257 chip->irq_ack(data);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700258}
259
Thomas Gleixner25ade602010-09-30 20:33:11 +0200260default_mask_ack(struct irq_data *data)
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700261{
Thomas Gleixner25ade602010-09-30 20:33:11 +0200262 if (chip->irq_mask_ack) {
263 chip->irq_mask_ack(data);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700264 } else {
Thomas Gleixner25ade602010-09-30 20:33:11 +0200265 chip->irq_mask(data);
266 chip->irq_ack(data);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700267 }
268}
269
Thomas Gleixner25ade602010-09-30 20:33:11 +0200270noop(struct irq_data *data))
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700271{
272}
273
274 </programlisting>
275 </para>
276 </sect3>
277 </sect2>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800278 <sect2 id="Default_flow_handler_implementations">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700279 <title>Default flow handler implementations</title>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800280 <sect3 id="Default_Level_IRQ_flow_handler">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700281 <title>Default Level IRQ flow handler</title>
282 <para>
283 handle_level_irq provides a generic implementation
284 for level-triggered interrupts.
285 </para>
286 <para>
287 The following control flow is implemented (simplified excerpt):
288 <programlisting>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200289desc->irq_data.chip->irq_mask_ack();
290handle_irq_event(desc->action);
291desc->irq_data.chip->irq_unmask();
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700292 </programlisting>
293 </para>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200294 </sect3>
295 <sect3 id="Default_FASTEOI_IRQ_flow_handler">
296 <title>Default Fast EOI IRQ flow handler</title>
297 <para>
298 handle_fasteoi_irq provides a generic implementation
299 for interrupts, which only need an EOI at the end of
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700300 the handler.
Thomas Gleixner25ade602010-09-30 20:33:11 +0200301 </para>
302 <para>
303 The following control flow is implemented (simplified excerpt):
304 <programlisting>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200305handle_irq_event(desc->action);
306desc->irq_data.chip->irq_eoi();
Thomas Gleixner25ade602010-09-30 20:33:11 +0200307 </programlisting>
308 </para>
309 </sect3>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800310 <sect3 id="Default_Edge_IRQ_flow_handler">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700311 <title>Default Edge IRQ flow handler</title>
312 <para>
313 handle_edge_irq provides a generic implementation
314 for edge-triggered interrupts.
315 </para>
316 <para>
317 The following control flow is implemented (simplified excerpt):
318 <programlisting>
319if (desc->status &amp; running) {
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200320 desc->irq_data.chip->irq_mask_ack();
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700321 desc->status |= pending | masked;
322 return;
323}
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200324desc->irq_data.chip->irq_ack();
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700325desc->status |= running;
326do {
327 if (desc->status &amp; masked)
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200328 desc->irq_data.chip->irq_unmask();
David S. Millerb06824c2006-12-12 01:00:06 -0800329 desc->status &amp;= ~pending;
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200330 handle_irq_event(desc->action);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700331} while (status &amp; pending);
David S. Millerb06824c2006-12-12 01:00:06 -0800332desc->status &amp;= ~running;
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700333 </programlisting>
334 </para>
335 </sect3>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800336 <sect3 id="Default_simple_IRQ_flow_handler">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700337 <title>Default simple IRQ flow handler</title>
338 <para>
339 handle_simple_irq provides a generic implementation
340 for simple interrupts.
341 </para>
342 <para>
343 Note: The simple flow handler does not call any
344 handler/chip primitives.
345 </para>
346 <para>
347 The following control flow is implemented (simplified excerpt):
348 <programlisting>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200349handle_irq_event(desc->action);
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700350 </programlisting>
351 </para>
352 </sect3>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800353 <sect3 id="Default_per_CPU_flow_handler">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700354 <title>Default per CPU flow handler</title>
355 <para>
356 handle_percpu_irq provides a generic implementation
357 for per CPU interrupts.
358 </para>
359 <para>
360 Per CPU interrupts are only available on SMP and
361 the handler provides a simplified version without
362 locking.
363 </para>
364 <para>
365 The following control flow is implemented (simplified excerpt):
366 <programlisting>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200367if (desc->irq_data.chip->irq_ack)
368 desc->irq_data.chip->irq_ack();
369handle_irq_event(desc->action);
370if (desc->irq_data.chip->irq_eoi)
371 desc->irq_data.chip->irq_eoi();
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700372 </programlisting>
373 </para>
374 </sect3>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200375 <sect3 id="EOI_Edge_IRQ_flow_handler">
376 <title>EOI Edge IRQ flow handler</title>
377 <para>
378 handle_edge_eoi_irq provides an abnomination of the edge
379 handler which is solely used to tame a badly wreckaged
380 irq controller on powerpc/cell.
381 </para>
382 </sect3>
383 <sect3 id="BAD_IRQ_flow_handler">
384 <title>Bad IRQ flow handler</title>
385 <para>
386 handle_bad_irq is used for spurious interrupts which
387 have no real handler assigned..
388 </para>
389 </sect3>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700390 </sect2>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800391 <sect2 id="Quirks_and_optimizations">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700392 <title>Quirks and optimizations</title>
393 <para>
394 The generic functions are intended for 'clean' architectures and chips,
395 which have no platform-specific IRQ handling quirks. If an architecture
396 needs to implement quirks on the 'flow' level then it can do so by
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700397 overriding the high-level irq-flow handler.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700398 </para>
399 </sect2>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800400 <sect2 id="Delayed_interrupt_disable">
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700401 <title>Delayed interrupt disable</title>
402 <para>
403 This per interrupt selectable feature, which was introduced by Russell
404 King in the ARM interrupt implementation, does not mask an interrupt
405 at the hardware level when disable_irq() is called. The interrupt is
406 kept enabled and is masked in the flow handler when an interrupt event
407 happens. This prevents losing edge interrupts on hardware which does
408 not store an edge interrupt event while the interrupt is disabled at
409 the hardware level. When an interrupt arrives while the IRQ_DISABLED
410 flag is set, then the interrupt is masked at the hardware level and
411 the IRQ_PENDING bit is set. When the interrupt is re-enabled by
412 enable_irq() the pending bit is checked and if it is set, the
413 interrupt is resent either via hardware or by a software resend
414 mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when
415 you want to use the delayed interrupt disable feature and your
416 hardware is not capable of retriggering an interrupt.)
Thomas Gleixner25ade602010-09-30 20:33:11 +0200417 The delayed interrupt disable is not configurable.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700418 </para>
419 </sect2>
420 </sect1>
Rob Landleyaa9128f2008-02-07 00:13:28 -0800421 <sect1 id="Chiplevel_hardware_encapsulation">
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700422 <title>Chip-level hardware encapsulation</title>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700423 <para>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700424 The chip-level hardware descriptor structure irq_chip
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700425 contains all the direct chip relevant functions, which
426 can be utilized by the irq flow implementations.
427 <itemizedlist>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200428 <listitem><para>irq_ack()</para></listitem>
429 <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem>
430 <listitem><para>irq_mask()</para></listitem>
431 <listitem><para>irq_unmask()</para></listitem>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700432 <listitem><para>irq_eoi() - Optional, required for EOI flow handlers</para></listitem>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200433 <listitem><para>irq_retrigger() - Optional</para></listitem>
434 <listitem><para>irq_set_type() - Optional</para></listitem>
435 <listitem><para>irq_set_wake() - Optional</para></listitem>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700436 </itemizedlist>
437 These primitives are strictly intended to mean what they say: ack means
438 ACK, masking means masking of an IRQ line, etc. It is up to the flow
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700439 handler(s) to use these basic units of low-level functionality.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700440 </para>
441 </sect1>
442 </chapter>
443
444 <chapter id="doirq">
445 <title>__do_IRQ entry point</title>
446 <para>
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200447 The original implementation __do_IRQ() was an alternative entry
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700448 point for all types of interrupts. It no longer exists.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700449 </para>
450 <para>
451 This handler turned out to be not suitable for all
452 interrupt hardware and was therefore reimplemented with split
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200453 functionality for edge/level/simple/percpu interrupts. This is not
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700454 only a functional optimization. It also shortens code paths for
455 interrupts.
456 </para>
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700457 </chapter>
458
459 <chapter id="locking">
460 <title>Locking on SMP</title>
461 <para>
462 The locking of chip registers is up to the architecture that
Geert Uytterhoevenee430592011-04-10 11:01:53 +0200463 defines the chip primitives. The per-irq structure is
464 protected via desc->lock, by the generic layer.
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700465 </para>
466 </chapter>
Thomas Gleixnerccc414f2013-06-28 11:45:15 +0200467
468 <chapter id="genericchip">
469 <title>Generic interrupt chip</title>
470 <para>
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700471 To avoid copies of identical implementations of IRQ chips the
Thomas Gleixnerccc414f2013-06-28 11:45:15 +0200472 core provides a configurable generic interrupt chip
Masanari Iida0ba4f6e2014-07-12 09:55:28 -0700473 implementation. Developers should check carefully whether the
Thomas Gleixnerccc414f2013-06-28 11:45:15 +0200474 generic chip fits their needs before implementing the same
Randy Dunlapfd2f3b72013-10-18 17:36:16 -0700475 functionality slightly differently themselves.
Thomas Gleixnerccc414f2013-06-28 11:45:15 +0200476 </para>
477!Ekernel/irq/generic-chip.c
478 </chapter>
479
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700480 <chapter id="structs">
481 <title>Structures</title>
482 <para>
483 This chapter contains the autogenerated documentation of the structures which are
484 used in the generic IRQ layer.
485 </para>
486!Iinclude/linux/irq.h
Thomas Gleixnera9d0a1a2009-03-03 16:58:16 +0100487!Iinclude/linux/interrupt.h
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700488 </chapter>
489
490 <chapter id="pubfunctions">
491 <title>Public Functions Provided</title>
492 <para>
493 This chapter contains the autogenerated documentation of the kernel API functions
494 which are exported.
495 </para>
496!Ekernel/irq/manage.c
497!Ekernel/irq/chip.c
498 </chapter>
499
500 <chapter id="intfunctions">
501 <title>Internal Functions Provided</title>
502 <para>
503 This chapter contains the autogenerated documentation of the internal functions.
504 </para>
Thomas Gleixner25ade602010-09-30 20:33:11 +0200505!Ikernel/irq/irqdesc.c
Thomas Gleixner11c869e2006-06-29 02:24:47 -0700506!Ikernel/irq/handle.c
507!Ikernel/irq/chip.c
508 </chapter>
509
510 <chapter id="credits">
511 <title>Credits</title>
512 <para>
513 The following people have contributed to this document:
514 <orderedlist>
515 <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
516 <listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem>
517 </orderedlist>
518 </para>
519 </chapter>
520</book>