0001 .. include:: <isonum.txt>
0002
0003 ==========================
0004 Linux generic IRQ handling
0005 ==========================
0006
0007 :Copyright: |copy| 2005-2010: Thomas Gleixner
0008 :Copyright: |copy| 2005-2006: Ingo Molnar
0009
0010 Introduction
0011 ============
0012
0013 The generic interrupt handling layer is designed to provide a complete
0014 abstraction of interrupt handling for device drivers. It is able to
0015 handle all the different types of interrupt controller hardware. Device
0016 drivers use generic API functions to request, enable, disable and free
0017 interrupts. The drivers do not have to know anything about interrupt
0018 hardware details, so they can be used on different platforms without
0019 code changes.
0020
0021 This documentation is provided to developers who want to implement an
0022 interrupt subsystem based for their architecture, with the help of the
0023 generic IRQ handling layer.
0024
0025 Rationale
0026 =========
0027
0028 The original implementation of interrupt handling in Linux uses the
0029 __do_IRQ() super-handler, which is able to deal with every type of
0030 interrupt logic.
0031
0032 Originally, Russell King identified different types of handlers to build
0033 a quite universal set for the ARM interrupt handler implementation in
0034 Linux 2.5/2.6. He distinguished between:
0035
0036 - Level type
0037
0038 - Edge type
0039
0040 - Simple type
0041
0042 During the implementation we identified another type:
0043
0044 - Fast EOI type
0045
0046 In the SMP world of the __do_IRQ() super-handler another type was
0047 identified:
0048
0049 - Per CPU type
0050
0051 This split implementation of high-level IRQ handlers allows us to
0052 optimize the flow of the interrupt handling for each specific interrupt
0053 type. This reduces complexity in that particular code path and allows
0054 the optimized handling of a given type.
0055
0056 The original general IRQ implementation used hw_interrupt_type
0057 structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate
0058 the flow control in the super-handler. This leads to a mix of flow logic
0059 and low-level hardware logic, and it also leads to unnecessary code
0060 duplication: for example in i386, there is an ``ioapic_level_irq`` and an
0061 ``ioapic_edge_irq`` IRQ-type which share many of the low-level details but
0062 have different flow handling.
0063
0064 A more natural abstraction is the clean separation of the 'irq flow' and
0065 the 'chip details'.
0066
0067 Analysing a couple of architecture's IRQ subsystem implementations
0068 reveals that most of them can use a generic set of 'irq flow' methods
0069 and only need to add the chip-level specific code. The separation is
0070 also valuable for (sub)architectures which need specific quirks in the
0071 IRQ flow itself but not in the chip details - and thus provides a more
0072 transparent IRQ subsystem design.
0073
0074 Each interrupt descriptor is assigned its own high-level flow handler,
0075 which is normally one of the generic implementations. (This high-level
0076 flow handler implementation also makes it simple to provide
0077 demultiplexing handlers which can be found in embedded platforms on
0078 various architectures.)
0079
0080 The separation makes the generic interrupt handling layer more flexible
0081 and extensible. For example, an (sub)architecture can use a generic
0082 IRQ-flow implementation for 'level type' interrupts and add a
0083 (sub)architecture specific 'edge type' implementation.
0084
0085 To make the transition to the new model easier and prevent the breakage
0086 of existing implementations, the __do_IRQ() super-handler is still
0087 available. This leads to a kind of duality for the time being. Over time
0088 the new model should be used in more and more architectures, as it
0089 enables smaller and cleaner IRQ subsystems. It's deprecated for three
0090 years now and about to be removed.
0091
0092 Known Bugs And Assumptions
0093 ==========================
0094
0095 None (knock on wood).
0096
0097 Abstraction layers
0098 ==================
0099
0100 There are three main levels of abstraction in the interrupt code:
0101
0102 1. High-level driver API
0103
0104 2. High-level IRQ flow handlers
0105
0106 3. Chip-level hardware encapsulation
0107
0108 Interrupt control flow
0109 ----------------------
0110
0111 Each interrupt is described by an interrupt descriptor structure
0112 irq_desc. The interrupt is referenced by an 'unsigned int' numeric
0113 value which selects the corresponding interrupt description structure in
0114 the descriptor structures array. The descriptor structure contains
0115 status information and pointers to the interrupt flow method and the
0116 interrupt chip structure which are assigned to this interrupt.
0117
0118 Whenever an interrupt triggers, the low-level architecture code calls
0119 into the generic interrupt code by calling desc->handle_irq(). This
0120 high-level IRQ handling function only uses desc->irq_data.chip
0121 primitives referenced by the assigned chip descriptor structure.
0122
0123 High-level Driver API
0124 ---------------------
0125
0126 The high-level Driver API consists of following functions:
0127
0128 - request_irq()
0129
0130 - request_threaded_irq()
0131
0132 - free_irq()
0133
0134 - disable_irq()
0135
0136 - enable_irq()
0137
0138 - disable_irq_nosync() (SMP only)
0139
0140 - synchronize_irq() (SMP only)
0141
0142 - irq_set_irq_type()
0143
0144 - irq_set_irq_wake()
0145
0146 - irq_set_handler_data()
0147
0148 - irq_set_chip()
0149
0150 - irq_set_chip_data()
0151
0152 See the autogenerated function documentation for details.
0153
0154 High-level IRQ flow handlers
0155 ----------------------------
0156
0157 The generic layer provides a set of pre-defined irq-flow methods:
0158
0159 - handle_level_irq()
0160
0161 - handle_edge_irq()
0162
0163 - handle_fasteoi_irq()
0164
0165 - handle_simple_irq()
0166
0167 - handle_percpu_irq()
0168
0169 - handle_edge_eoi_irq()
0170
0171 - handle_bad_irq()
0172
0173 The interrupt flow handlers (either pre-defined or architecture
0174 specific) are assigned to specific interrupts by the architecture either
0175 during bootup or during device initialization.
0176
0177 Default flow implementations
0178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0179
0180 Helper functions
0181 ^^^^^^^^^^^^^^^^
0182
0183 The helper functions call the chip primitives and are used by the
0184 default flow implementations. The following helper functions are
0185 implemented (simplified excerpt)::
0186
0187 default_enable(struct irq_data *data)
0188 {
0189 desc->irq_data.chip->irq_unmask(data);
0190 }
0191
0192 default_disable(struct irq_data *data)
0193 {
0194 if (!delay_disable(data))
0195 desc->irq_data.chip->irq_mask(data);
0196 }
0197
0198 default_ack(struct irq_data *data)
0199 {
0200 chip->irq_ack(data);
0201 }
0202
0203 default_mask_ack(struct irq_data *data)
0204 {
0205 if (chip->irq_mask_ack) {
0206 chip->irq_mask_ack(data);
0207 } else {
0208 chip->irq_mask(data);
0209 chip->irq_ack(data);
0210 }
0211 }
0212
0213 noop(struct irq_data *data))
0214 {
0215 }
0216
0217
0218
0219 Default flow handler implementations
0220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0221
0222 Default Level IRQ flow handler
0223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0224
0225 handle_level_irq provides a generic implementation for level-triggered
0226 interrupts.
0227
0228 The following control flow is implemented (simplified excerpt)::
0229
0230 desc->irq_data.chip->irq_mask_ack();
0231 handle_irq_event(desc->action);
0232 desc->irq_data.chip->irq_unmask();
0233
0234
0235 Default Fast EOI IRQ flow handler
0236 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0237
0238 handle_fasteoi_irq provides a generic implementation for interrupts,
0239 which only need an EOI at the end of the handler.
0240
0241 The following control flow is implemented (simplified excerpt)::
0242
0243 handle_irq_event(desc->action);
0244 desc->irq_data.chip->irq_eoi();
0245
0246
0247 Default Edge IRQ flow handler
0248 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0249
0250 handle_edge_irq provides a generic implementation for edge-triggered
0251 interrupts.
0252
0253 The following control flow is implemented (simplified excerpt)::
0254
0255 if (desc->status & running) {
0256 desc->irq_data.chip->irq_mask_ack();
0257 desc->status |= pending | masked;
0258 return;
0259 }
0260 desc->irq_data.chip->irq_ack();
0261 desc->status |= running;
0262 do {
0263 if (desc->status & masked)
0264 desc->irq_data.chip->irq_unmask();
0265 desc->status &= ~pending;
0266 handle_irq_event(desc->action);
0267 } while (status & pending);
0268 desc->status &= ~running;
0269
0270
0271 Default simple IRQ flow handler
0272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0273
0274 handle_simple_irq provides a generic implementation for simple
0275 interrupts.
0276
0277 .. note::
0278
0279 The simple flow handler does not call any handler/chip primitives.
0280
0281 The following control flow is implemented (simplified excerpt)::
0282
0283 handle_irq_event(desc->action);
0284
0285
0286 Default per CPU flow handler
0287 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0288
0289 handle_percpu_irq provides a generic implementation for per CPU
0290 interrupts.
0291
0292 Per CPU interrupts are only available on SMP and the handler provides a
0293 simplified version without locking.
0294
0295 The following control flow is implemented (simplified excerpt)::
0296
0297 if (desc->irq_data.chip->irq_ack)
0298 desc->irq_data.chip->irq_ack();
0299 handle_irq_event(desc->action);
0300 if (desc->irq_data.chip->irq_eoi)
0301 desc->irq_data.chip->irq_eoi();
0302
0303
0304 EOI Edge IRQ flow handler
0305 ^^^^^^^^^^^^^^^^^^^^^^^^^
0306
0307 handle_edge_eoi_irq provides an abnomination of the edge handler
0308 which is solely used to tame a badly wreckaged irq controller on
0309 powerpc/cell.
0310
0311 Bad IRQ flow handler
0312 ^^^^^^^^^^^^^^^^^^^^
0313
0314 handle_bad_irq is used for spurious interrupts which have no real
0315 handler assigned..
0316
0317 Quirks and optimizations
0318 ~~~~~~~~~~~~~~~~~~~~~~~~
0319
0320 The generic functions are intended for 'clean' architectures and chips,
0321 which have no platform-specific IRQ handling quirks. If an architecture
0322 needs to implement quirks on the 'flow' level then it can do so by
0323 overriding the high-level irq-flow handler.
0324
0325 Delayed interrupt disable
0326 ~~~~~~~~~~~~~~~~~~~~~~~~~
0327
0328 This per interrupt selectable feature, which was introduced by Russell
0329 King in the ARM interrupt implementation, does not mask an interrupt at
0330 the hardware level when disable_irq() is called. The interrupt is kept
0331 enabled and is masked in the flow handler when an interrupt event
0332 happens. This prevents losing edge interrupts on hardware which does not
0333 store an edge interrupt event while the interrupt is disabled at the
0334 hardware level. When an interrupt arrives while the IRQ_DISABLED flag
0335 is set, then the interrupt is masked at the hardware level and the
0336 IRQ_PENDING bit is set. When the interrupt is re-enabled by
0337 enable_irq() the pending bit is checked and if it is set, the interrupt
0338 is resent either via hardware or by a software resend mechanism. (It's
0339 necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use
0340 the delayed interrupt disable feature and your hardware is not capable
0341 of retriggering an interrupt.) The delayed interrupt disable is not
0342 configurable.
0343
0344 Chip-level hardware encapsulation
0345 ---------------------------------
0346
0347 The chip-level hardware descriptor structure :c:type:`irq_chip` contains all
0348 the direct chip relevant functions, which can be utilized by the irq flow
0349 implementations.
0350
0351 - ``irq_ack``
0352
0353 - ``irq_mask_ack`` - Optional, recommended for performance
0354
0355 - ``irq_mask``
0356
0357 - ``irq_unmask``
0358
0359 - ``irq_eoi`` - Optional, required for EOI flow handlers
0360
0361 - ``irq_retrigger`` - Optional
0362
0363 - ``irq_set_type`` - Optional
0364
0365 - ``irq_set_wake`` - Optional
0366
0367 These primitives are strictly intended to mean what they say: ack means
0368 ACK, masking means masking of an IRQ line, etc. It is up to the flow
0369 handler(s) to use these basic units of low-level functionality.
0370
0371 __do_IRQ entry point
0372 ====================
0373
0374 The original implementation __do_IRQ() was an alternative entry point
0375 for all types of interrupts. It no longer exists.
0376
0377 This handler turned out to be not suitable for all interrupt hardware
0378 and was therefore reimplemented with split functionality for
0379 edge/level/simple/percpu interrupts. This is not only a functional
0380 optimization. It also shortens code paths for interrupts.
0381
0382 Locking on SMP
0383 ==============
0384
0385 The locking of chip registers is up to the architecture that defines the
0386 chip primitives. The per-irq structure is protected via desc->lock, by
0387 the generic layer.
0388
0389 Generic interrupt chip
0390 ======================
0391
0392 To avoid copies of identical implementations of IRQ chips the core
0393 provides a configurable generic interrupt chip implementation.
0394 Developers should check carefully whether the generic chip fits their
0395 needs before implementing the same functionality slightly differently
0396 themselves.
0397
0398 .. kernel-doc:: kernel/irq/generic-chip.c
0399 :export:
0400
0401 Structures
0402 ==========
0403
0404 This chapter contains the autogenerated documentation of the structures
0405 which are used in the generic IRQ layer.
0406
0407 .. kernel-doc:: include/linux/irq.h
0408 :internal:
0409
0410 .. kernel-doc:: include/linux/interrupt.h
0411 :internal:
0412
0413 Public Functions Provided
0414 =========================
0415
0416 This chapter contains the autogenerated documentation of the kernel API
0417 functions which are exported.
0418
0419 .. kernel-doc:: kernel/irq/manage.c
0420
0421 .. kernel-doc:: kernel/irq/chip.c
0422 :export:
0423
0424 Internal Functions Provided
0425 ===========================
0426
0427 This chapter contains the autogenerated documentation of the internal
0428 functions.
0429
0430 .. kernel-doc:: kernel/irq/irqdesc.c
0431
0432 .. kernel-doc:: kernel/irq/handle.c
0433
0434 .. kernel-doc:: kernel/irq/chip.c
0435 :internal:
0436
0437 Credits
0438 =======
0439
0440 The following people have contributed to this document:
0441
0442 1. Thomas Gleixner tglx@linutronix.de
0443
0444 2. Ingo Molnar mingo@elte.hu
