genericirq.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  1. .. include:: <isonum.txt>
  2. ==========================
  3. Linux generic IRQ handling
  4. ==========================
  5. :Copyright: |copy| 2005-2010: Thomas Gleixner
  6. :Copyright: |copy| 2005-2006: Ingo Molnar
  7. Introduction
  8. ============
  9. The generic interrupt handling layer is designed to provide a complete
  10. abstraction of interrupt handling for device drivers. It is able to
  11. handle all the different types of interrupt controller hardware. Device
  12. drivers use generic API functions to request, enable, disable and free
  13. interrupts. The drivers do not have to know anything about interrupt
  14. hardware details, so they can be used on different platforms without
  15. code changes.
  16. This documentation is provided to developers who want to implement an
  17. interrupt subsystem based for their architecture, with the help of the
  18. generic IRQ handling layer.
  19. Rationale
  20. =========
  21. The original implementation of interrupt handling in Linux uses the
  22. __do_IRQ() super-handler, which is able to deal with every type of
  23. interrupt logic.
  24. Originally, Russell King identified different types of handlers to build
  25. a quite universal set for the ARM interrupt handler implementation in
  26. Linux 2.5/2.6. He distinguished between:
  27. - Level type
  28. - Edge type
  29. - Simple type
  30. During the implementation we identified another type:
  31. - Fast EOI type
  32. In the SMP world of the __do_IRQ() super-handler another type was
  33. identified:
  34. - Per CPU type
  35. This split implementation of high-level IRQ handlers allows us to
  36. optimize the flow of the interrupt handling for each specific interrupt
  37. type. This reduces complexity in that particular code path and allows
  38. the optimized handling of a given type.
  39. The original general IRQ implementation used hw_interrupt_type
  40. structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate
  41. the flow control in the super-handler. This leads to a mix of flow logic
  42. and low-level hardware logic, and it also leads to unnecessary code
  43. duplication: for example in i386, there is an ``ioapic_level_irq`` and an
  44. ``ioapic_edge_irq`` IRQ-type which share many of the low-level details but
  45. have different flow handling.
  46. A more natural abstraction is the clean separation of the 'irq flow' and
  47. the 'chip details'.
  48. Analysing a couple of architecture's IRQ subsystem implementations
  49. reveals that most of them can use a generic set of 'irq flow' methods
  50. and only need to add the chip-level specific code. The separation is
  51. also valuable for (sub)architectures which need specific quirks in the
  52. IRQ flow itself but not in the chip details - and thus provides a more
  53. transparent IRQ subsystem design.
  54. Each interrupt descriptor is assigned its own high-level flow handler,
  55. which is normally one of the generic implementations. (This high-level
  56. flow handler implementation also makes it simple to provide
  57. demultiplexing handlers which can be found in embedded platforms on
  58. various architectures.)
  59. The separation makes the generic interrupt handling layer more flexible
  60. and extensible. For example, an (sub)architecture can use a generic
  61. IRQ-flow implementation for 'level type' interrupts and add a
  62. (sub)architecture specific 'edge type' implementation.
  63. To make the transition to the new model easier and prevent the breakage
  64. of existing implementations, the __do_IRQ() super-handler is still
  65. available. This leads to a kind of duality for the time being. Over time
  66. the new model should be used in more and more architectures, as it
  67. enables smaller and cleaner IRQ subsystems. It's deprecated for three
  68. years now and about to be removed.
  69. Known Bugs And Assumptions
  70. ==========================
  71. None (knock on wood).
  72. Abstraction layers
  73. ==================
  74. There are three main levels of abstraction in the interrupt code:
  75. 1. High-level driver API
  76. 2. High-level IRQ flow handlers
  77. 3. Chip-level hardware encapsulation
  78. Interrupt control flow
  79. ----------------------
  80. Each interrupt is described by an interrupt descriptor structure
  81. irq_desc. The interrupt is referenced by an 'unsigned int' numeric
  82. value which selects the corresponding interrupt description structure in
  83. the descriptor structures array. The descriptor structure contains
  84. status information and pointers to the interrupt flow method and the
  85. interrupt chip structure which are assigned to this interrupt.
  86. Whenever an interrupt triggers, the low-level architecture code calls
  87. into the generic interrupt code by calling desc->handle_irq(). This
  88. high-level IRQ handling function only uses desc->irq_data.chip
  89. primitives referenced by the assigned chip descriptor structure.
  90. High-level Driver API
  91. ---------------------
  92. The high-level Driver API consists of following functions:
  93. - request_irq()
  94. - request_threaded_irq()
  95. - free_irq()
  96. - disable_irq()
  97. - enable_irq()
  98. - disable_irq_nosync() (SMP only)
  99. - synchronize_irq() (SMP only)
  100. - irq_set_irq_type()
  101. - irq_set_irq_wake()
  102. - irq_set_handler_data()
  103. - irq_set_chip()
  104. - irq_set_chip_data()
  105. See the autogenerated function documentation for details.
  106. High-level IRQ flow handlers
  107. ----------------------------
  108. The generic layer provides a set of pre-defined irq-flow methods:
  109. - handle_level_irq()
  110. - handle_edge_irq()
  111. - handle_fasteoi_irq()
  112. - handle_simple_irq()
  113. - handle_percpu_irq()
  114. - handle_edge_eoi_irq()
  115. - handle_bad_irq()
  116. The interrupt flow handlers (either pre-defined or architecture
  117. specific) are assigned to specific interrupts by the architecture either
  118. during bootup or during device initialization.
  119. Default flow implementations
  120. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  121. Helper functions
  122. ^^^^^^^^^^^^^^^^
  123. The helper functions call the chip primitives and are used by the
  124. default flow implementations. The following helper functions are
  125. implemented (simplified excerpt)::
  126. default_enable(struct irq_data *data)
  127. {
  128. desc->irq_data.chip->irq_unmask(data);
  129. }
  130. default_disable(struct irq_data *data)
  131. {
  132. if (!delay_disable(data))
  133. desc->irq_data.chip->irq_mask(data);
  134. }
  135. default_ack(struct irq_data *data)
  136. {
  137. chip->irq_ack(data);
  138. }
  139. default_mask_ack(struct irq_data *data)
  140. {
  141. if (chip->irq_mask_ack) {
  142. chip->irq_mask_ack(data);
  143. } else {
  144. chip->irq_mask(data);
  145. chip->irq_ack(data);
  146. }
  147. }
  148. noop(struct irq_data *data))
  149. {
  150. }
  151. Default flow handler implementations
  152. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  153. Default Level IRQ flow handler
  154. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  155. handle_level_irq provides a generic implementation for level-triggered
  156. interrupts.
  157. The following control flow is implemented (simplified excerpt)::
  158. desc->irq_data.chip->irq_mask_ack();
  159. handle_irq_event(desc->action);
  160. desc->irq_data.chip->irq_unmask();
  161. Default Fast EOI IRQ flow handler
  162. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  163. handle_fasteoi_irq provides a generic implementation for interrupts,
  164. which only need an EOI at the end of the handler.
  165. The following control flow is implemented (simplified excerpt)::
  166. handle_irq_event(desc->action);
  167. desc->irq_data.chip->irq_eoi();
  168. Default Edge IRQ flow handler
  169. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  170. handle_edge_irq provides a generic implementation for edge-triggered
  171. interrupts.
  172. The following control flow is implemented (simplified excerpt)::
  173. if (desc->status & running) {
  174. desc->irq_data.chip->irq_mask_ack();
  175. desc->status |= pending | masked;
  176. return;
  177. }
  178. desc->irq_data.chip->irq_ack();
  179. desc->status |= running;
  180. do {
  181. if (desc->status & masked)
  182. desc->irq_data.chip->irq_unmask();
  183. desc->status &= ~pending;
  184. handle_irq_event(desc->action);
  185. } while (status & pending);
  186. desc->status &= ~running;
  187. Default simple IRQ flow handler
  188. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  189. handle_simple_irq provides a generic implementation for simple
  190. interrupts.
  191. .. note::
  192. The simple flow handler does not call any handler/chip primitives.
  193. The following control flow is implemented (simplified excerpt)::
  194. handle_irq_event(desc->action);
  195. Default per CPU flow handler
  196. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  197. handle_percpu_irq provides a generic implementation for per CPU
  198. interrupts.
  199. Per CPU interrupts are only available on SMP and the handler provides a
  200. simplified version without locking.
  201. The following control flow is implemented (simplified excerpt)::
  202. if (desc->irq_data.chip->irq_ack)
  203. desc->irq_data.chip->irq_ack();
  204. handle_irq_event(desc->action);
  205. if (desc->irq_data.chip->irq_eoi)
  206. desc->irq_data.chip->irq_eoi();
  207. EOI Edge IRQ flow handler
  208. ^^^^^^^^^^^^^^^^^^^^^^^^^
  209. handle_edge_eoi_irq provides an abnomination of the edge handler
  210. which is solely used to tame a badly wreckaged irq controller on
  211. powerpc/cell.
  212. Bad IRQ flow handler
  213. ^^^^^^^^^^^^^^^^^^^^
  214. handle_bad_irq is used for spurious interrupts which have no real
  215. handler assigned..
  216. Quirks and optimizations
  217. ~~~~~~~~~~~~~~~~~~~~~~~~
  218. The generic functions are intended for 'clean' architectures and chips,
  219. which have no platform-specific IRQ handling quirks. If an architecture
  220. needs to implement quirks on the 'flow' level then it can do so by
  221. overriding the high-level irq-flow handler.
  222. Delayed interrupt disable
  223. ~~~~~~~~~~~~~~~~~~~~~~~~~
  224. This per interrupt selectable feature, which was introduced by Russell
  225. King in the ARM interrupt implementation, does not mask an interrupt at
  226. the hardware level when disable_irq() is called. The interrupt is kept
  227. enabled and is masked in the flow handler when an interrupt event
  228. happens. This prevents losing edge interrupts on hardware which does not
  229. store an edge interrupt event while the interrupt is disabled at the
  230. hardware level. When an interrupt arrives while the IRQ_DISABLED flag
  231. is set, then the interrupt is masked at the hardware level and the
  232. IRQ_PENDING bit is set. When the interrupt is re-enabled by
  233. enable_irq() the pending bit is checked and if it is set, the interrupt
  234. is resent either via hardware or by a software resend mechanism. (It's
  235. necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use
  236. the delayed interrupt disable feature and your hardware is not capable
  237. of retriggering an interrupt.) The delayed interrupt disable is not
  238. configurable.
  239. Chip-level hardware encapsulation
  240. ---------------------------------
  241. The chip-level hardware descriptor structure :c:type:`irq_chip` contains all
  242. the direct chip relevant functions, which can be utilized by the irq flow
  243. implementations.
  244. - ``irq_ack``
  245. - ``irq_mask_ack`` - Optional, recommended for performance
  246. - ``irq_mask``
  247. - ``irq_unmask``
  248. - ``irq_eoi`` - Optional, required for EOI flow handlers
  249. - ``irq_retrigger`` - Optional
  250. - ``irq_set_type`` - Optional
  251. - ``irq_set_wake`` - Optional
  252. These primitives are strictly intended to mean what they say: ack means
  253. ACK, masking means masking of an IRQ line, etc. It is up to the flow
  254. handler(s) to use these basic units of low-level functionality.
  255. __do_IRQ entry point
  256. ====================
  257. The original implementation __do_IRQ() was an alternative entry point
  258. for all types of interrupts. It no longer exists.
  259. This handler turned out to be not suitable for all interrupt hardware
  260. and was therefore reimplemented with split functionality for
  261. edge/level/simple/percpu interrupts. This is not only a functional
  262. optimization. It also shortens code paths for interrupts.
  263. Locking on SMP
  264. ==============
  265. The locking of chip registers is up to the architecture that defines the
  266. chip primitives. The per-irq structure is protected via desc->lock, by
  267. the generic layer.
  268. Generic interrupt chip
  269. ======================
  270. To avoid copies of identical implementations of IRQ chips the core
  271. provides a configurable generic interrupt chip implementation.
  272. Developers should check carefully whether the generic chip fits their
  273. needs before implementing the same functionality slightly differently
  274. themselves.
  275. .. kernel-doc:: kernel/irq/generic-chip.c
  276. :export:
  277. Structures
  278. ==========
  279. This chapter contains the autogenerated documentation of the structures
  280. which are used in the generic IRQ layer.
  281. .. kernel-doc:: include/linux/irq.h
  282. :internal:
  283. .. kernel-doc:: include/linux/interrupt.h
  284. :internal:
  285. Public Functions Provided
  286. =========================
  287. This chapter contains the autogenerated documentation of the kernel API
  288. functions which are exported.
  289. .. kernel-doc:: kernel/irq/manage.c
  290. .. kernel-doc:: kernel/irq/chip.c
  291. :export:
  292. Internal Functions Provided
  293. ===========================
  294. This chapter contains the autogenerated documentation of the internal
  295. functions.
  296. .. kernel-doc:: kernel/irq/irqdesc.c
  297. .. kernel-doc:: kernel/irq/handle.c
  298. .. kernel-doc:: kernel/irq/chip.c
  299. :internal:
  300. Credits
  301. =======
  302. The following people have contributed to this document:
  303. 1. Thomas Gleixner tglx@linutronix.de
  304. 2. Ingo Molnar mingo@elte.hu