core-api/irq/irq-domain.rst

9 that each one gets assigned non-overlapping allocations of Linux
24 For this reason we need a mechanism to separate controller-local
29 the controller-local IRQ (hwirq) number into the Linux IRQ number
55 the hwirq, and call the .map() callback so the driver can perform any
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.
87 Which reverse map type should be used depends on the use case.  Each
88 of the reverse map types are described below:
91 ------
98 The linear reverse map maintains a fixed size table indexed by the
102 The Linear map is a good choice when the maximum number of hwirqs is
104 map are fixed time lookup for IRQ numbers, and irq_descs are only
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
113 The majority of drivers should use the linear map.
116 ----
123 The irq_domain maintains a radix tree map from hwirq numbers to Linux
124 IRQs.  When an hwirq is mapped, an irq_desc is allocated and the
127 The tree map is a good choice if the hwirq number can be very large
133 equivalent, except for the first argument is different - the former
139 No Map
140 ------
146 The No Map mapping is to be used when the hwirq number is
150 IRQ number and call the .map() callback so that driver can program the
158 ------
168 range of irq_descs allocated for the hwirqs.  It is used when the
180 The legacy map assumes a contiguous range of IRQ numbers has already
183 visa-versa.  The disadvantage is that it requires the interrupt
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
193 irq_domain_create_simple() which will use a legacy domain only if an IRQ range
195 The semantics of this call are such that if an IRQ range is specified then
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
287 4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,