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