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