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 | |
85c2a0ed | 29 | __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 | ||
85c2a0ed | 46 | In the SMP world of the __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 | |
85c2a0ed | 86 | of existing implementations, the __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 | |
85c2a0ed | 119 | into the generic interrupt code by calling 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 | ||
85c2a0ed | 128 | - request_irq() |
3bd3b99a | 129 | |
5ca470a0 JC |
130 | - request_threaded_irq() |
131 | ||
85c2a0ed | 132 | - free_irq() |
3bd3b99a | 133 | |
85c2a0ed | 134 | - disable_irq() |
3bd3b99a | 135 | |
85c2a0ed | 136 | - enable_irq() |
3bd3b99a | 137 | |
85c2a0ed | 138 | - disable_irq_nosync() (SMP only) |
3bd3b99a | 139 | |
85c2a0ed | 140 | - synchronize_irq() (SMP only) |
3bd3b99a | 141 | |
85c2a0ed | 142 | - irq_set_irq_type() |
3bd3b99a | 143 | |
85c2a0ed | 144 | - irq_set_irq_wake() |
3bd3b99a | 145 | |
85c2a0ed | 146 | - irq_set_handler_data() |
3bd3b99a | 147 | |
85c2a0ed | 148 | - irq_set_chip() |
3bd3b99a | 149 | |
85c2a0ed | 150 | - irq_set_chip_data() |
3bd3b99a MCC |
151 | |
152 | See the autogenerated function documentation for details. | |
153 | ||
154 | High-level IRQ flow handlers | |
155 | ---------------------------- | |
156 | ||
157 | The generic layer provides a set of pre-defined irq-flow methods: | |
158 | ||
85c2a0ed | 159 | - handle_level_irq() |
3bd3b99a | 160 | |
85c2a0ed | 161 | - handle_edge_irq() |
3bd3b99a | 162 | |
85c2a0ed | 163 | - handle_fasteoi_irq() |
3bd3b99a | 164 | |
85c2a0ed | 165 | - handle_simple_irq() |
3bd3b99a | 166 | |
85c2a0ed | 167 | - handle_percpu_irq() |
3bd3b99a | 168 | |
85c2a0ed | 169 | - handle_edge_eoi_irq() |
3bd3b99a | 170 | |
85c2a0ed | 171 | - handle_bad_irq() |
3bd3b99a MCC |
172 | |
173 | The interrupt flow handlers (either pre-defined or architecture | |
174 | specific) are assigned to specific interrupts by the architecture either | |
175 | during bootup or during device initialization. | |
176 | ||
177 | Default flow implementations | |
178 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
179 | ||
180 | Helper functions | |
181 | ^^^^^^^^^^^^^^^^ | |
182 | ||
183 | The helper functions call the chip primitives and are used by the | |
184 | default flow implementations. The following helper functions are | |
185 | implemented (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 | ||
219 | Default flow handler implementations | |
220 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
221 | ||
222 | Default Level IRQ flow handler | |
223 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
224 | ||
225 | handle_level_irq provides a generic implementation for level-triggered | |
226 | interrupts. | |
227 | ||
228 | The following control flow is implemented (simplified excerpt):: | |
229 | ||
0f83aaa3 | 230 | desc->irq_data.chip->irq_mask_ack(); |
3bd3b99a | 231 | handle_irq_event(desc->action); |
0f83aaa3 | 232 | desc->irq_data.chip->irq_unmask(); |
3bd3b99a MCC |
233 | |
234 | ||
235 | Default Fast EOI IRQ flow handler | |
236 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
237 | ||
238 | handle_fasteoi_irq provides a generic implementation for interrupts, | |
239 | which only need an EOI at the end of the handler. | |
240 | ||
241 | The following control flow is implemented (simplified excerpt):: | |
242 | ||
243 | handle_irq_event(desc->action); | |
0f83aaa3 | 244 | desc->irq_data.chip->irq_eoi(); |
3bd3b99a MCC |
245 | |
246 | ||
247 | Default Edge IRQ flow handler | |
248 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
249 | ||
250 | handle_edge_irq provides a generic implementation for edge-triggered | |
251 | interrupts. | |
252 | ||
253 | The following control flow is implemented (simplified excerpt):: | |
254 | ||
255 | if (desc->status & running) { | |
0f83aaa3 | 256 | desc->irq_data.chip->irq_mask_ack(); |
3bd3b99a MCC |
257 | desc->status |= pending | masked; |
258 | return; | |
259 | } | |
0f83aaa3 | 260 | desc->irq_data.chip->irq_ack(); |
3bd3b99a MCC |
261 | desc->status |= running; |
262 | do { | |
263 | if (desc->status & masked) | |
0f83aaa3 | 264 | desc->irq_data.chip->irq_unmask(); |
3bd3b99a MCC |
265 | desc->status &= ~pending; |
266 | handle_irq_event(desc->action); | |
c63594f2 | 267 | } while (desc->status & pending); |
3bd3b99a MCC |
268 | desc->status &= ~running; |
269 | ||
270 | ||
271 | Default simple IRQ flow handler | |
272 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
273 | ||
274 | handle_simple_irq provides a generic implementation for simple | |
275 | interrupts. | |
276 | ||
277 | .. note:: | |
278 | ||
279 | The simple flow handler does not call any handler/chip primitives. | |
280 | ||
281 | The following control flow is implemented (simplified excerpt):: | |
282 | ||
283 | handle_irq_event(desc->action); | |
284 | ||
285 | ||
286 | Default per CPU flow handler | |
287 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
288 | ||
289 | handle_percpu_irq provides a generic implementation for per CPU | |
290 | interrupts. | |
291 | ||
292 | Per CPU interrupts are only available on SMP and the handler provides a | |
293 | simplified version without locking. | |
294 | ||
295 | The following control flow is implemented (simplified excerpt):: | |
296 | ||
297 | if (desc->irq_data.chip->irq_ack) | |
0f83aaa3 | 298 | desc->irq_data.chip->irq_ack(); |
3bd3b99a MCC |
299 | handle_irq_event(desc->action); |
300 | if (desc->irq_data.chip->irq_eoi) | |
0f83aaa3 | 301 | desc->irq_data.chip->irq_eoi(); |
3bd3b99a MCC |
302 | |
303 | ||
304 | EOI Edge IRQ flow handler | |
305 | ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
306 | ||
307 | handle_edge_eoi_irq provides an abnomination of the edge handler | |
308 | which is solely used to tame a badly wreckaged irq controller on | |
309 | powerpc/cell. | |
310 | ||
311 | Bad IRQ flow handler | |
312 | ^^^^^^^^^^^^^^^^^^^^ | |
313 | ||
314 | handle_bad_irq is used for spurious interrupts which have no real | |
315 | handler assigned.. | |
316 | ||
317 | Quirks and optimizations | |
318 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
319 | ||
320 | The generic functions are intended for 'clean' architectures and chips, | |
321 | which have no platform-specific IRQ handling quirks. If an architecture | |
322 | needs to implement quirks on the 'flow' level then it can do so by | |
323 | overriding the high-level irq-flow handler. | |
324 | ||
325 | Delayed interrupt disable | |
326 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
327 | ||
328 | This per interrupt selectable feature, which was introduced by Russell | |
329 | King in the ARM interrupt implementation, does not mask an interrupt at | |
85c2a0ed | 330 | the hardware level when disable_irq() is called. The interrupt is kept |
3bd3b99a MCC |
331 | enabled and is masked in the flow handler when an interrupt event |
332 | happens. This prevents losing edge interrupts on hardware which does not | |
333 | store an edge interrupt event while the interrupt is disabled at the | |
334 | hardware level. When an interrupt arrives while the IRQ_DISABLED flag | |
335 | is set, then the interrupt is masked at the hardware level and the | |
336 | IRQ_PENDING bit is set. When the interrupt is re-enabled by | |
85c2a0ed | 337 | enable_irq() the pending bit is checked and if it is set, the interrupt |
3bd3b99a MCC |
338 | is resent either via hardware or by a software resend mechanism. (It's |
339 | necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use | |
340 | the delayed interrupt disable feature and your hardware is not capable | |
341 | of retriggering an interrupt.) The delayed interrupt disable is not | |
342 | configurable. | |
343 | ||
344 | Chip-level hardware encapsulation | |
345 | --------------------------------- | |
346 | ||
76d40fae MCC |
347 | The chip-level hardware descriptor structure :c:type:`irq_chip` contains all |
348 | the direct chip relevant functions, which can be utilized by the irq flow | |
3bd3b99a MCC |
349 | implementations. |
350 | ||
76d40fae | 351 | - ``irq_ack`` |
3bd3b99a | 352 | |
76d40fae | 353 | - ``irq_mask_ack`` - Optional, recommended for performance |
3bd3b99a | 354 | |
76d40fae | 355 | - ``irq_mask`` |
3bd3b99a | 356 | |
76d40fae | 357 | - ``irq_unmask`` |
3bd3b99a | 358 | |
76d40fae | 359 | - ``irq_eoi`` - Optional, required for EOI flow handlers |
3bd3b99a | 360 | |
76d40fae | 361 | - ``irq_retrigger`` - Optional |
3bd3b99a | 362 | |
76d40fae | 363 | - ``irq_set_type`` - Optional |
3bd3b99a | 364 | |
76d40fae | 365 | - ``irq_set_wake`` - Optional |
3bd3b99a MCC |
366 | |
367 | These primitives are strictly intended to mean what they say: ack means | |
368 | ACK, masking means masking of an IRQ line, etc. It is up to the flow | |
369 | handler(s) to use these basic units of low-level functionality. | |
370 | ||
371 | __do_IRQ entry point | |
372 | ==================== | |
373 | ||
85c2a0ed | 374 | The original implementation __do_IRQ() was an alternative entry point |
3bd3b99a MCC |
375 | for all types of interrupts. It no longer exists. |
376 | ||
377 | This handler turned out to be not suitable for all interrupt hardware | |
378 | and was therefore reimplemented with split functionality for | |
379 | edge/level/simple/percpu interrupts. This is not only a functional | |
380 | optimization. It also shortens code paths for interrupts. | |
381 | ||
382 | Locking on SMP | |
383 | ============== | |
384 | ||
385 | The locking of chip registers is up to the architecture that defines the | |
386 | chip primitives. The per-irq structure is protected via desc->lock, by | |
387 | the generic layer. | |
388 | ||
389 | Generic interrupt chip | |
390 | ====================== | |
391 | ||
392 | To avoid copies of identical implementations of IRQ chips the core | |
393 | provides a configurable generic interrupt chip implementation. | |
394 | Developers should check carefully whether the generic chip fits their | |
395 | needs before implementing the same functionality slightly differently | |
396 | themselves. | |
397 | ||
398 | .. kernel-doc:: kernel/irq/generic-chip.c | |
399 | :export: | |
400 | ||
401 | Structures | |
402 | ========== | |
403 | ||
404 | This chapter contains the autogenerated documentation of the structures | |
405 | which 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 | ||
413 | Public Functions Provided | |
414 | ========================= | |
415 | ||
416 | This chapter contains the autogenerated documentation of the kernel API | |
417 | functions which are exported. | |
418 | ||
419 | .. kernel-doc:: kernel/irq/manage.c | |
3bd3b99a MCC |
420 | |
421 | .. kernel-doc:: kernel/irq/chip.c | |
9b9b0bda | 422 | :export: |
3bd3b99a MCC |
423 | |
424 | Internal Functions Provided | |
425 | =========================== | |
426 | ||
427 | This chapter contains the autogenerated documentation of the internal | |
428 | functions. | |
429 | ||
430 | .. kernel-doc:: kernel/irq/irqdesc.c | |
3bd3b99a MCC |
431 | |
432 | .. kernel-doc:: kernel/irq/handle.c | |
3bd3b99a MCC |
433 | |
434 | .. kernel-doc:: kernel/irq/chip.c | |
9b9b0bda | 435 | :internal: |
3bd3b99a MCC |
436 | |
437 | Credits | |
438 | ======= | |
439 | ||
440 | The following people have contributed to this document: | |
441 | ||
442 | 1. Thomas Gleixner tglx@linutronix.de | |
443 | ||
444 | 2. Ingo Molnar mingo@elte.hu |