1.. include:: <isonum.txt>
2
3==========================
4Linux generic IRQ handling
5==========================
6
7:Copyright: |copy| 2005-2010: Thomas Gleixner
8:Copyright: |copy| 2005-2006:  Ingo Molnar
9
10Introduction
11============
12
13The generic interrupt handling layer is designed to provide a complete
14abstraction of interrupt handling for device drivers. It is able to
15handle all the different types of interrupt controller hardware. Device
16drivers use generic API functions to request, enable, disable and free
17interrupts. The drivers do not have to know anything about interrupt
18hardware details, so they can be used on different platforms without
19code changes.
20
21This documentation is provided to developers who want to implement an
22interrupt subsystem based for their architecture, with the help of the
23generic IRQ handling layer.
24
25Rationale
26=========
27
28The original implementation of interrupt handling in Linux uses the
29__do_IRQ() super-handler, which is able to deal with every type of
30interrupt logic.
31
32Originally, Russell King identified different types of handlers to build
33a quite universal set for the ARM interrupt handler implementation in
34Linux 2.5/2.6. He distinguished between:
35
36-  Level type
37
38-  Edge type
39
40-  Simple type
41
42During the implementation we identified another type:
43
44-  Fast EOI type
45
46In the SMP world of the __do_IRQ() super-handler another type was
47identified:
48
49-  Per CPU type
50
51This split implementation of high-level IRQ handlers allows us to
52optimize the flow of the interrupt handling for each specific interrupt
53type. This reduces complexity in that particular code path and allows
54the optimized handling of a given type.
55
56The original general IRQ implementation used hw_interrupt_type
57structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate
58the flow control in the super-handler. This leads to a mix of flow logic
59and low-level hardware logic, and it also leads to unnecessary code
60duplication: for example in i386, there is an ``ioapic_level_irq`` and an
61``ioapic_edge_irq`` IRQ-type which share many of the low-level details but
62have different flow handling.
63
64A more natural abstraction is the clean separation of the 'irq flow' and
65the 'chip details'.
66
67Analysing a couple of architecture's IRQ subsystem implementations
68reveals that most of them can use a generic set of 'irq flow' methods
69and only need to add the chip-level specific code. The separation is
70also valuable for (sub)architectures which need specific quirks in the
71IRQ flow itself but not in the chip details - and thus provides a more
72transparent IRQ subsystem design.
73
74Each interrupt descriptor is assigned its own high-level flow handler,
75which is normally one of the generic implementations. (This high-level
76flow handler implementation also makes it simple to provide
77demultiplexing handlers which can be found in embedded platforms on
78various architectures.)
79
80The separation makes the generic interrupt handling layer more flexible
81and extensible. For example, an (sub)architecture can use a generic
82IRQ-flow implementation for 'level type' interrupts and add a
83(sub)architecture specific 'edge type' implementation.
84
85To make the transition to the new model easier and prevent the breakage
86of existing implementations, the __do_IRQ() super-handler is still
87available. This leads to a kind of duality for the time being. Over time
88the new model should be used in more and more architectures, as it
89enables smaller and cleaner IRQ subsystems. It's deprecated for three
90years now and about to be removed.
91
92Known Bugs And Assumptions
93==========================
94
95None (knock on wood).
96
97Abstraction layers
98==================
99
100There are three main levels of abstraction in the interrupt code:
101
1021. High-level driver API
103
1042. High-level IRQ flow handlers
105
1063. Chip-level hardware encapsulation
107
108Interrupt control flow
109----------------------
110
111Each interrupt is described by an interrupt descriptor structure
112irq_desc. The interrupt is referenced by an 'unsigned int' numeric
113value which selects the corresponding interrupt description structure in
114the descriptor structures array. The descriptor structure contains
115status information and pointers to the interrupt flow method and the
116interrupt chip structure which are assigned to this interrupt.
117
118Whenever an interrupt triggers, the low-level architecture code calls
119into the generic interrupt code by calling desc->handle_irq(). This
120high-level IRQ handling function only uses desc->irq_data.chip
121primitives referenced by the assigned chip descriptor structure.
122
123High-level Driver API
124---------------------
125
126The high-level Driver API consists of following functions:
127
128-  request_irq()
129
130-  request_threaded_irq()
131
132-  free_irq()
133
134-  disable_irq()
135
136-  enable_irq()
137
138-  disable_irq_nosync() (SMP only)
139
140-  synchronize_irq() (SMP only)
141
142-  irq_set_irq_type()
143
144-  irq_set_irq_wake()
145
146-  irq_set_handler_data()
147
148-  irq_set_chip()
149
150-  irq_set_chip_data()
151
152See the autogenerated function documentation for details.
153
154High-level IRQ flow handlers
155----------------------------
156
157The generic layer provides a set of pre-defined irq-flow methods:
158
159-  handle_level_irq()
160
161-  handle_edge_irq()
162
163-  handle_fasteoi_irq()
164
165-  handle_simple_irq()
166
167-  handle_percpu_irq()
168
169-  handle_edge_eoi_irq()
170
171-  handle_bad_irq()
172
173The interrupt flow handlers (either pre-defined or architecture
174specific) are assigned to specific interrupts by the architecture either
175during bootup or during device initialization.
176
177Default flow implementations
178~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179
180Helper functions
181^^^^^^^^^^^^^^^^
182
183The helper functions call the chip primitives and are used by the
184default flow implementations. The following helper functions are
185implemented (simplified excerpt)::
186
187    default_enable(struct irq_data *data)
188    {
189        desc->irq_data.chip->irq_unmask(data);
190    }
191
192    default_disable(struct irq_data *data)
193    {
194        if (!delay_disable(data))
195            desc->irq_data.chip->irq_mask(data);
196    }
197
198    default_ack(struct irq_data *data)
199    {
200        chip->irq_ack(data);
201    }
202
203    default_mask_ack(struct irq_data *data)
204    {
205        if (chip->irq_mask_ack) {
206            chip->irq_mask_ack(data);
207        } else {
208            chip->irq_mask(data);
209            chip->irq_ack(data);
210        }
211    }
212
213    noop(struct irq_data *data))
214    {
215    }
216
217
218
219Default flow handler implementations
220~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221
222Default Level IRQ flow handler
223^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224
225handle_level_irq provides a generic implementation for level-triggered
226interrupts.
227
228The following control flow is implemented (simplified excerpt)::
229
230    desc->irq_data.chip->irq_mask_ack();
231    handle_irq_event(desc->action);
232    desc->irq_data.chip->irq_unmask();
233
234
235Default Fast EOI IRQ flow handler
236^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
237
238handle_fasteoi_irq provides a generic implementation for interrupts,
239which only need an EOI at the end of the handler.
240
241The following control flow is implemented (simplified excerpt)::
242
243    handle_irq_event(desc->action);
244    desc->irq_data.chip->irq_eoi();
245
246
247Default Edge IRQ flow handler
248^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
249
250handle_edge_irq provides a generic implementation for edge-triggered
251interrupts.
252
253The following control flow is implemented (simplified excerpt)::
254
255    if (desc->status & running) {
256        desc->irq_data.chip->irq_mask_ack();
257        desc->status |= pending | masked;
258        return;
259    }
260    desc->irq_data.chip->irq_ack();
261    desc->status |= running;
262    do {
263        if (desc->status & masked)
264            desc->irq_data.chip->irq_unmask();
265        desc->status &= ~pending;
266        handle_irq_event(desc->action);
267    } while (status & pending);
268    desc->status &= ~running;
269
270
271Default simple IRQ flow handler
272^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
273
274handle_simple_irq provides a generic implementation for simple
275interrupts.
276
277.. note::
278
279   The simple flow handler does not call any handler/chip primitives.
280
281The following control flow is implemented (simplified excerpt)::
282
283    handle_irq_event(desc->action);
284
285
286Default per CPU flow handler
287^^^^^^^^^^^^^^^^^^^^^^^^^^^^
288
289handle_percpu_irq provides a generic implementation for per CPU
290interrupts.
291
292Per CPU interrupts are only available on SMP and the handler provides a
293simplified version without locking.
294
295The following control flow is implemented (simplified excerpt)::
296
297    if (desc->irq_data.chip->irq_ack)
298        desc->irq_data.chip->irq_ack();
299    handle_irq_event(desc->action);
300    if (desc->irq_data.chip->irq_eoi)
301        desc->irq_data.chip->irq_eoi();
302
303
304EOI Edge IRQ flow handler
305^^^^^^^^^^^^^^^^^^^^^^^^^
306
307handle_edge_eoi_irq provides an abnomination of the edge handler
308which is solely used to tame a badly wreckaged irq controller on
309powerpc/cell.
310
311Bad IRQ flow handler
312^^^^^^^^^^^^^^^^^^^^
313
314handle_bad_irq is used for spurious interrupts which have no real
315handler assigned..
316
317Quirks and optimizations
318~~~~~~~~~~~~~~~~~~~~~~~~
319
320The generic functions are intended for 'clean' architectures and chips,
321which have no platform-specific IRQ handling quirks. If an architecture
322needs to implement quirks on the 'flow' level then it can do so by
323overriding the high-level irq-flow handler.
324
325Delayed interrupt disable
326~~~~~~~~~~~~~~~~~~~~~~~~~
327
328This per interrupt selectable feature, which was introduced by Russell
329King in the ARM interrupt implementation, does not mask an interrupt at
330the hardware level when disable_irq() is called. The interrupt is kept
331enabled and is masked in the flow handler when an interrupt event
332happens. This prevents losing edge interrupts on hardware which does not
333store an edge interrupt event while the interrupt is disabled at the
334hardware level. When an interrupt arrives while the IRQ_DISABLED flag
335is set, then the interrupt is masked at the hardware level and the
336IRQ_PENDING bit is set. When the interrupt is re-enabled by
337enable_irq() the pending bit is checked and if it is set, the interrupt
338is resent either via hardware or by a software resend mechanism. (It's
339necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use
340the delayed interrupt disable feature and your hardware is not capable
341of retriggering an interrupt.) The delayed interrupt disable is not
342configurable.
343
344Chip-level hardware encapsulation
345---------------------------------
346
347The chip-level hardware descriptor structure :c:type:`irq_chip` contains all
348the direct chip relevant functions, which can be utilized by the irq flow
349implementations.
350
351-  ``irq_ack``
352
353-  ``irq_mask_ack`` - Optional, recommended for performance
354
355-  ``irq_mask``
356
357-  ``irq_unmask``
358
359-  ``irq_eoi`` - Optional, required for EOI flow handlers
360
361-  ``irq_retrigger`` - Optional
362
363-  ``irq_set_type`` - Optional
364
365-  ``irq_set_wake`` - Optional
366
367These primitives are strictly intended to mean what they say: ack means
368ACK, masking means masking of an IRQ line, etc. It is up to the flow
369handler(s) to use these basic units of low-level functionality.
370
371__do_IRQ entry point
372====================
373
374The original implementation __do_IRQ() was an alternative entry point
375for all types of interrupts. It no longer exists.
376
377This handler turned out to be not suitable for all interrupt hardware
378and was therefore reimplemented with split functionality for
379edge/level/simple/percpu interrupts. This is not only a functional
380optimization. It also shortens code paths for interrupts.
381
382Locking on SMP
383==============
384
385The locking of chip registers is up to the architecture that defines the
386chip primitives. The per-irq structure is protected via desc->lock, by
387the generic layer.
388
389Generic interrupt chip
390======================
391
392To avoid copies of identical implementations of IRQ chips the core
393provides a configurable generic interrupt chip implementation.
394Developers should check carefully whether the generic chip fits their
395needs before implementing the same functionality slightly differently
396themselves.
397
398.. kernel-doc:: kernel/irq/generic-chip.c
399   :export:
400
401Structures
402==========
403
404This chapter contains the autogenerated documentation of the structures
405which are used in the generic IRQ layer.
406
407.. kernel-doc:: include/linux/irq.h
408   :internal:
409
410.. kernel-doc:: include/linux/interrupt.h
411   :internal:
412
413Public Functions Provided
414=========================
415
416This chapter contains the autogenerated documentation of the kernel API
417functions which are exported.
418
419.. kernel-doc:: kernel/irq/manage.c
420
421.. kernel-doc:: kernel/irq/chip.c
422   :export:
423
424Internal Functions Provided
425===========================
426
427This chapter contains the autogenerated documentation of the internal
428functions.
429
430.. kernel-doc:: kernel/irq/irqdesc.c
431
432.. kernel-doc:: kernel/irq/handle.c
433
434.. kernel-doc:: kernel/irq/chip.c
435   :internal:
436
437Credits
438=======
439
440The following people have contributed to this document:
441
4421. Thomas Gleixner tglx@linutronix.de
443
4442. Ingo Molnar mingo@elte.hu
445