core-api/irq/irq-domain.rst

2 The irq_domain interrupt number mapping library
5 The current design of the Linux kernel uses a single large number
6 space where each separate IRQ source is assigned a different number.
7 This is simple when there is only one interrupt controller, but in
9 that each one gets assigned non-overlapping allocations of Linux
12 The number of interrupt controllers registered as unique irqchips
18 Here the interrupt number loose all kind of correspondence to
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
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
53 hwirq number as arguments.  If a mapping for the hwirq doesn't already
61 - irq_resolve_mapping() returns a pointer to the irq_desc structure
62   for a given domain and hwirq number, and NULL if there was no
64 - irq_find_mapping() returns a Linux IRQ number for a given domain and
65   hwirq number, and 0 if there was no mapping
66 - irq_linear_revmap() is now identical to irq_find_mapping(), and is
68 - generic_handle_domain_irq() handles an interrupt described by a
69   domain and a hwirq number
72 compatible with a RCU read-side critical section.
78 If the driver has the Linux IRQ number or the irq_data pointer, and
79 needs to know the associated hwirq number (such as in the irq_chip
80 callbacks) then it can be directly obtained from irq_data->hwirq.
91 ------
99 hwirq number.  When a hwirq is mapped, an irq_desc is allocated for
100 the hwirq, and the IRQ number is stored in the table.
102 The Linear map is a good choice when the maximum number of hwirqs is
103 fixed and a relatively small number (~ < 256).  The advantages of this
105 allocated for in-use IRQs.  The disadvantage is that the table must be
106 as large as the largest possible hwirq number.
109 equivalent, except for the first argument is different - the former
116 ----
127 The tree map is a good choice if the hwirq number can be very large
129 hwirq number.  The disadvantage is that hwirq to IRQ number lookup is
133 equivalent, except for the first argument is different - the former
140 ------
146 The No Map mapping is to be used when the hwirq number is
148 Linux IRQ number into the hardware itself so that no mapping is
150 IRQ number and call the .map() callback so that driver can program the
151 Linux IRQ number into the hardware.
158 ------
181 been allocated for the controller and that the IRQ number can be
182 calculated by adding a fixed offset to the hwirq number, and
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
189 mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ
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 --------------------
222   Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
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.
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
253 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
262    is used to store irq_domain pointer and hardware irq number.
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