Commit | Line | Data |
---|---|---|
3bd3b99a MCC |
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 | |
76d40fae | 29 | :c:func:`__do_IRQ` super-handler, which is able to deal with every type of |
3bd3b99a MCC |
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 | ||
76d40fae | 46 | In the SMP world of the :c:func:`__do_IRQ` super-handler another type was |
3bd3b99a MCC |
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 | |
76d40fae | 57 | structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate |
3bd3b99a MCC |
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 | |
76d40fae MCC |
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 | |
3bd3b99a MCC |
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 | |
76d40fae | 86 | of existing implementations, the :c:func:`__do_IRQ` super-handler is still |
3bd3b99a MCC |
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 | |
76d40fae | 119 | into the generic interrupt code by calling :c:func:`desc->handle_irq`. This |
3bd3b99a MCC |
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 | ||
76d40fae | 128 | - :c:func:`request_irq` |
3bd3b99a | 129 | |
76d40fae | 130 | - :c:func:`free_irq` |
3bd3b99a | 131 | |
76d40fae | 132 | - :c:func:`disable_irq` |
3bd3b99a | 133 | |
76d40fae | 134 | - :c:func:`enable_irq` |
3bd3b99a | 135 | |
76d40fae | 136 | - :c:func:`disable_irq_nosync` (SMP only) |
3bd3b99a | 137 | |
76d40fae | 138 | - :c:func:`synchronize_irq` (SMP only) |
3bd3b99a | 139 | |
76d40fae | 140 | - :c:func:`irq_set_irq_type` |
3bd3b99a | 141 | |
76d40fae | 142 | - :c:func:`irq_set_irq_wake` |
3bd3b99a | 143 | |
76d40fae | 144 | - :c:func:`irq_set_handler_data` |
3bd3b99a | 145 | |
76d40fae | 146 | - :c:func:`irq_set_chip` |
3bd3b99a | 147 | |
76d40fae | 148 | - :c:func:`irq_set_chip_data` |
3bd3b99a MCC |
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 | ||
76d40fae | 157 | - :c:func:`handle_level_irq` |
3bd3b99a | 158 | |
76d40fae | 159 | - :c:func:`handle_edge_irq` |
3bd3b99a | 160 | |
76d40fae | 161 | - :c:func:`handle_fasteoi_irq` |
3bd3b99a | 162 | |
76d40fae | 163 | - :c:func:`handle_simple_irq` |
3bd3b99a | 164 | |
76d40fae | 165 | - :c:func:`handle_percpu_irq` |
3bd3b99a | 166 | |
76d40fae | 167 | - :c:func:`handle_edge_eoi_irq` |
3bd3b99a | 168 | |
76d40fae | 169 | - :c:func:`handle_bad_irq` |
3bd3b99a MCC |
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 | ||
76d40fae | 228 | :c:func:`desc->irq_data.chip->irq_mask_ack`; |
3bd3b99a | 229 | handle_irq_event(desc->action); |
76d40fae | 230 | :c:func:`desc->irq_data.chip->irq_unmask`; |
3bd3b99a MCC |
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); | |
76d40fae | 242 | :c:func:`desc->irq_data.chip->irq_eoi`; |
3bd3b99a MCC |
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) { | |
76d40fae | 254 | :c:func:`desc->irq_data.chip->irq_mask_ack`; |
3bd3b99a MCC |
255 | desc->status |= pending | masked; |
256 | return; | |
257 | } | |
76d40fae | 258 | :c:func:`desc->irq_data.chip->irq_ack`; |
3bd3b99a MCC |
259 | desc->status |= running; |
260 | do { | |
261 | if (desc->status & masked) | |
76d40fae | 262 | :c:func:`desc->irq_data.chip->irq_unmask`; |
3bd3b99a MCC |
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) | |
76d40fae | 296 | :c:func:`desc->irq_data.chip->irq_ack`; |
3bd3b99a MCC |
297 | handle_irq_event(desc->action); |
298 | if (desc->irq_data.chip->irq_eoi) | |
76d40fae | 299 | :c:func:`desc->irq_data.chip->irq_eoi`; |
3bd3b99a MCC |
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 | |
76d40fae | 328 | the hardware level when :c:func:`disable_irq` is called. The interrupt is kept |
3bd3b99a MCC |
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 | |
76d40fae | 335 | :c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt |
3bd3b99a MCC |
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 | ||
76d40fae MCC |
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 | |
3bd3b99a MCC |
347 | implementations. |
348 | ||
76d40fae | 349 | - ``irq_ack`` |
3bd3b99a | 350 | |
76d40fae | 351 | - ``irq_mask_ack`` - Optional, recommended for performance |
3bd3b99a | 352 | |
76d40fae | 353 | - ``irq_mask`` |
3bd3b99a | 354 | |
76d40fae | 355 | - ``irq_unmask`` |
3bd3b99a | 356 | |
76d40fae | 357 | - ``irq_eoi`` - Optional, required for EOI flow handlers |
3bd3b99a | 358 | |
76d40fae | 359 | - ``irq_retrigger`` - Optional |
3bd3b99a | 360 | |
76d40fae | 361 | - ``irq_set_type`` - Optional |
3bd3b99a | 362 | |
76d40fae | 363 | - ``irq_set_wake`` - Optional |
3bd3b99a MCC |
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 | ||
76d40fae | 372 | The original implementation :c:func:`__do_IRQ` was an alternative entry point |
3bd3b99a MCC |
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 | |
3bd3b99a MCC |
418 | |
419 | .. kernel-doc:: kernel/irq/chip.c | |
3bd3b99a MCC |
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 | |
3bd3b99a MCC |
428 | |
429 | .. kernel-doc:: kernel/irq/handle.c | |
3bd3b99a MCC |
430 | |
431 | .. kernel-doc:: kernel/irq/chip.c | |
3bd3b99a MCC |
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 |