1.. include:: <isonum.txt> 2 3========================== 4Linux generic IRQ handling 5========================== 6 7:Copyright: |copy| 2005-2010: Thomas Gleixner 8:Copyright: |copy| 2005-2006: Ingo Molnar 9 10Introduction 11============ 12 13The generic interrupt handling layer is designed to provide a complete 14abstraction of interrupt handling for device drivers. It is able to 15handle all the different types of interrupt controller hardware. Device 16drivers use generic API functions to request, enable, disable and free 17interrupts. The drivers do not have to know anything about interrupt 18hardware details, so they can be used on different platforms without 19code changes. 20 21This documentation is provided to developers who want to implement an 22interrupt subsystem based for their architecture, with the help of the 23generic IRQ handling layer. 24 25Rationale 26========= 27 28The 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 30interrupt logic. 31 32Originally, Russell King identified different types of handlers to build 33a quite universal set for the ARM interrupt handler implementation in 34Linux 2.5/2.6. He distinguished between: 35 36- Level type 37 38- Edge type 39 40- Simple type 41 42During the implementation we identified another type: 43 44- Fast EOI type 45 46In the SMP world of the :c:func:`__do_IRQ` super-handler another type was 47identified: 48 49- Per CPU type 50 51This split implementation of high-level IRQ handlers allows us to 52optimize the flow of the interrupt handling for each specific interrupt 53type. This reduces complexity in that particular code path and allows 54the optimized handling of a given type. 55 56The original general IRQ implementation used hw_interrupt_type 57structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate 58the flow control in the super-handler. This leads to a mix of flow logic 59and low-level hardware logic, and it also leads to unnecessary code 60duplication: 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 62have different flow handling. 63 64A more natural abstraction is the clean separation of the 'irq flow' and 65the 'chip details'. 66 67Analysing a couple of architecture's IRQ subsystem implementations 68reveals that most of them can use a generic set of 'irq flow' methods 69and only need to add the chip-level specific code. The separation is 70also valuable for (sub)architectures which need specific quirks in the 71IRQ flow itself but not in the chip details - and thus provides a more 72transparent IRQ subsystem design. 73 74Each interrupt descriptor is assigned its own high-level flow handler, 75which is normally one of the generic implementations. (This high-level 76flow handler implementation also makes it simple to provide 77demultiplexing handlers which can be found in embedded platforms on 78various architectures.) 79 80The separation makes the generic interrupt handling layer more flexible 81and extensible. For example, an (sub)architecture can use a generic 82IRQ-flow implementation for 'level type' interrupts and add a 83(sub)architecture specific 'edge type' implementation. 84 85To make the transition to the new model easier and prevent the breakage 86of existing implementations, the :c:func:`__do_IRQ` super-handler is still 87available. This leads to a kind of duality for the time being. Over time 88the new model should be used in more and more architectures, as it 89enables smaller and cleaner IRQ subsystems. It's deprecated for three 90years now and about to be removed. 91 92Known Bugs And Assumptions 93========================== 94 95None (knock on wood). 96 97Abstraction layers 98================== 99 100There are three main levels of abstraction in the interrupt code: 101 1021. High-level driver API 103 1042. High-level IRQ flow handlers 105 1063. Chip-level hardware encapsulation 107 108Interrupt control flow 109---------------------- 110 111Each interrupt is described by an interrupt descriptor structure 112irq_desc. The interrupt is referenced by an 'unsigned int' numeric 113value which selects the corresponding interrupt description structure in 114the descriptor structures array. The descriptor structure contains 115status information and pointers to the interrupt flow method and the 116interrupt chip structure which are assigned to this interrupt. 117 118Whenever an interrupt triggers, the low-level architecture code calls 119into the generic interrupt code by calling :c:func:`desc->handle_irq`. This 120high-level IRQ handling function only uses desc->irq_data.chip 121primitives referenced by the assigned chip descriptor structure. 122 123High-level Driver API 124--------------------- 125 126The 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 150See the autogenerated function documentation for details. 151 152High-level IRQ flow handlers 153---------------------------- 154 155The 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 171The interrupt flow handlers (either pre-defined or architecture 172specific) are assigned to specific interrupts by the architecture either 173during bootup or during device initialization. 174 175Default flow implementations 176~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 177 178Helper functions 179^^^^^^^^^^^^^^^^ 180 181The helper functions call the chip primitives and are used by the 182default flow implementations. The following helper functions are 183implemented (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 217Default flow handler implementations 218~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 219 220Default Level IRQ flow handler 221^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 222 223handle_level_irq provides a generic implementation for level-triggered 224interrupts. 225 226The 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 233Default Fast EOI IRQ flow handler 234^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 235 236handle_fasteoi_irq provides a generic implementation for interrupts, 237which only need an EOI at the end of the handler. 238 239The following control flow is implemented (simplified excerpt):: 240 241 handle_irq_event(desc->action); 242 desc->irq_data.chip->irq_eoi(); 243 244 245Default Edge IRQ flow handler 246^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 247 248handle_edge_irq provides a generic implementation for edge-triggered 249interrupts. 250 251The 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 269Default simple IRQ flow handler 270^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 271 272handle_simple_irq provides a generic implementation for simple 273interrupts. 274 275.. note:: 276 277 The simple flow handler does not call any handler/chip primitives. 278 279The following control flow is implemented (simplified excerpt):: 280 281 handle_irq_event(desc->action); 282 283 284Default per CPU flow handler 285^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 286 287handle_percpu_irq provides a generic implementation for per CPU 288interrupts. 289 290Per CPU interrupts are only available on SMP and the handler provides a 291simplified version without locking. 292 293The 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 302EOI Edge IRQ flow handler 303^^^^^^^^^^^^^^^^^^^^^^^^^ 304 305handle_edge_eoi_irq provides an abnomination of the edge handler 306which is solely used to tame a badly wreckaged irq controller on 307powerpc/cell. 308 309Bad IRQ flow handler 310^^^^^^^^^^^^^^^^^^^^ 311 312handle_bad_irq is used for spurious interrupts which have no real 313handler assigned.. 314 315Quirks and optimizations 316~~~~~~~~~~~~~~~~~~~~~~~~ 317 318The generic functions are intended for 'clean' architectures and chips, 319which have no platform-specific IRQ handling quirks. If an architecture 320needs to implement quirks on the 'flow' level then it can do so by 321overriding the high-level irq-flow handler. 322 323Delayed interrupt disable 324~~~~~~~~~~~~~~~~~~~~~~~~~ 325 326This per interrupt selectable feature, which was introduced by Russell 327King in the ARM interrupt implementation, does not mask an interrupt at 328the hardware level when :c:func:`disable_irq` is called. The interrupt is kept 329enabled and is masked in the flow handler when an interrupt event 330happens. This prevents losing edge interrupts on hardware which does not 331store an edge interrupt event while the interrupt is disabled at the 332hardware level. When an interrupt arrives while the IRQ_DISABLED flag 333is set, then the interrupt is masked at the hardware level and the 334IRQ_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 336is resent either via hardware or by a software resend mechanism. (It's 337necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use 338the delayed interrupt disable feature and your hardware is not capable 339of retriggering an interrupt.) The delayed interrupt disable is not 340configurable. 341 342Chip-level hardware encapsulation 343--------------------------------- 344 345The chip-level hardware descriptor structure :c:type:`irq_chip` contains all 346the direct chip relevant functions, which can be utilized by the irq flow 347implementations. 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 365These primitives are strictly intended to mean what they say: ack means 366ACK, masking means masking of an IRQ line, etc. It is up to the flow 367handler(s) to use these basic units of low-level functionality. 368 369__do_IRQ entry point 370==================== 371 372The original implementation :c:func:`__do_IRQ` was an alternative entry point 373for all types of interrupts. It no longer exists. 374 375This handler turned out to be not suitable for all interrupt hardware 376and was therefore reimplemented with split functionality for 377edge/level/simple/percpu interrupts. This is not only a functional 378optimization. It also shortens code paths for interrupts. 379 380Locking on SMP 381============== 382 383The locking of chip registers is up to the architecture that defines the 384chip primitives. The per-irq structure is protected via desc->lock, by 385the generic layer. 386 387Generic interrupt chip 388====================== 389 390To avoid copies of identical implementations of IRQ chips the core 391provides a configurable generic interrupt chip implementation. 392Developers should check carefully whether the generic chip fits their 393needs before implementing the same functionality slightly differently 394themselves. 395 396.. kernel-doc:: kernel/irq/generic-chip.c 397 :export: 398 399Structures 400========== 401 402This chapter contains the autogenerated documentation of the structures 403which 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 411Public Functions Provided 412========================= 413 414This chapter contains the autogenerated documentation of the kernel API 415functions which are exported. 416 417.. kernel-doc:: kernel/irq/manage.c 418 419.. kernel-doc:: kernel/irq/chip.c 420 421Internal Functions Provided 422=========================== 423 424This chapter contains the autogenerated documentation of the internal 425functions. 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 433Credits 434======= 435 436The following people have contributed to this document: 437 4381. Thomas Gleixner tglx@linutronix.de 439 4402. Ingo Molnar mingo@elte.hu 441