core-api/irq/irq-domain.rst

5 The current design of the Linux kernel uses a single large number
9 that each one gets assigned non-overlapping allocations of Linux
12 The number of interrupt controllers registered as unique irqchips
13 show a rising tendency: for example subdrivers of different kinds
18 Here the interrupt number loose all kind of correspondence to
24 For this reason we need a mechanism to separate controller-local
27 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
28 irq numbers, but they don't provide any support for reverse mapping of
29 the controller-local IRQ (hwirq) number into the Linux IRQ number
33 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
45 calling one of the irq_domain_add_*() or irq_domain_create_*() functions
59 variety of methods:
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.
82 Types of irq_domain mappings
87 Which reverse map type should be used depends on the use case.  Each
88 of the reverse map types are described below:
91 ------
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
109 equivalent, except for the first argument is different - the former
113 The majority of drivers should use the linear map.
116 ----
133 equivalent, except for the first argument is different - the former
140 ------
153 Most drivers cannot use this mapping, and it is now gated on the
155 users of this API.
158 ------
168 range of irq_descs allocated for the hwirqs.  It is used when the
169 driver cannot be immediately converted to use the linear mapping.  For
170 example, many embedded system board support files use a set of #defines
176 exist to ease the support of ancient platforms. No new users should be
177 added. Same goes for the \*_simple() functions when their use results
180 The legacy map assumes a contiguous range of IRQ numbers has already
183 visa-versa.  The disadvantage is that it requires the interrupt
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
194 is supplied by the system and will otherwise use a linear domain mapping.
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
200 A typical use case for simple domains is where an irqchip provider
211 equivalent, except for the first argument is different - the former
216 --------------------
222   Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
245 There are four major interfaces to use hierarchy irq_domain:
266 With support of hierarchy irq_domain and hierarchy irq_data ready, an
296 Most of the internals of the IRQ subsystem are exposed in debugfs by