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