core-api/irq/irq-domain.rst

2 The irq_domain interrupt number mapping library
7 This is simple when there is only one interrupt controller, but in
8 systems with multiple interrupt controllers the kernel must ensure
9 that each one gets assigned non-overlapping allocations of Linux
12 The number of interrupt controllers registered as unique irqchips
15 mechanisms as the IRQ core system by modelling their interrupt
16 handlers as irqchips, i.e. in effect cascading interrupt controllers.
18 Here the interrupt number loose all kind of correspondence to
19 hardware interrupt numbers: whereas in the past, IRQ numbers could
21 interrupt controller (i.e. the component actually fireing the
22 interrupt line to the CPU) nowadays this number is just a number.
24 For this reason we need a mechanism to separate controller-local
25 interrupt numbers, called hardware irq's, from Linux IRQ numbers.
29 the controller-local IRQ (hwirq) number into the Linux IRQ number
34 preferred over interrupt controller drivers open coding their own
44 An interrupt controller driver creates and registers an irq_domain by
61 - irq_resolve_mapping() returns a pointer to the irq_desc structure
64 - irq_find_mapping() returns a Linux IRQ number for a given domain and
66 - irq_linear_revmap() is now identical to irq_find_mapping(), and is
68 - generic_handle_domain_irq() handles an interrupt described by a
72 compatible with a RCU read-side critical section.
80 callbacks) then it can be directly obtained from irq_data->hwirq.
91 ------
105 allocated for in-use IRQs.  The disadvantage is that the table must be
109 equivalent, except for the first argument is different - the former
116 ----
133 equivalent, except for the first argument is different - the former
140 ------
157 Legacy  section in Types of irq_domain mappings
158 ------
167 The Legacy mapping is a special case for drivers that already have a
172 case the Linux IRQ numbers cannot be dynamically assigned and the legacy
178 in the legacy behaviour.
180 The legacy map assumes a contiguous range of IRQ numbers has already
181 been allocated for the controller and that the IRQ number can be
183 visa-versa.  The disadvantage is that it requires the interrupt
184 controller to manage IRQ allocations and it requires an irq_desc to be
187 The legacy map should only be used if fixed IRQ mappings must be
188 supported.  For example, ISA controllers would use the legacy map for
189 mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ
192 Most users of legacy mappings should use irq_domain_add_simple() or
193 irq_domain_create_simple() which will use a legacy domain only if an IRQ range
196 descriptors will be allocated on-the-fly for it, and if no range is
211 equivalent, except for the first argument is different - the former
216 --------------------
218 On some architectures, there may be multiple interrupt controllers
219 involved in delivering an interrupt from the device to the target CPU.
220 Let's look at a typical interrupt delivering path on x86 platforms::
222   Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
224 There are three interrupt controllers involved:
226 1) IOAPIC controller
227 2) Interrupt remapping controller
228 3) Local APIC controller
232 interrupt controller and those irq_domains are organized into hierarchy.
240 	Interrupt Remapping irq_domain (manage irq_remapping entries)
247 1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt
248    controller related resources to deliver these interrupts.
249 2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller
251 3) irq_domain_activate_irq(): activate interrupt controller hardware to
252    deliver the interrupt.
253 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
254    to stop delivering the interrupt.
267 irq_domain structure is built for each interrupt controller, and an
274 With stacked irq_chip, interrupt controller driver only needs to deal
279 For an interrupt controller driver to support hierarchy irq_domain, it
285 3) Optionally implement an irq_chip to manage the interrupt controller