blob: 82001a25a14bd7478c8aace88bc063ab3d0b87bf
1 | irq_domain interrupt number mapping library |
2 | |
3 | The current design of the Linux kernel uses a single large number |
4 | space where each separate IRQ source is assigned a different number. |
5 | This is simple when there is only one interrupt controller, but in |
6 | systems with multiple interrupt controllers the kernel must ensure |
7 | that each one gets assigned non-overlapping allocations of Linux |
8 | IRQ numbers. |
9 | |
10 | The number of interrupt controllers registered as unique irqchips |
11 | show a rising tendency: for example subdrivers of different kinds |
12 | such as GPIO controllers avoid reimplementing identical callback |
13 | mechanisms as the IRQ core system by modelling their interrupt |
14 | handlers as irqchips, i.e. in effect cascading interrupt controllers. |
15 | |
16 | Here the interrupt number loose all kind of correspondence to |
17 | hardware interrupt numbers: whereas in the past, IRQ numbers could |
18 | be chosen so they matched the hardware IRQ line into the root |
19 | interrupt controller (i.e. the component actually fireing the |
20 | interrupt line to the CPU) nowadays this number is just a number. |
21 | |
22 | For this reason we need a mechanism to separate controller-local |
23 | interrupt numbers, called hardware irq's, from Linux IRQ numbers. |
24 | |
25 | The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of |
26 | irq numbers, but they don't provide any support for reverse mapping of |
27 | the controller-local IRQ (hwirq) number into the Linux IRQ number |
28 | space. |
29 | |
30 | The irq_domain library adds mapping between hwirq and IRQ numbers on |
31 | top of the irq_alloc_desc*() API. An irq_domain to manage mapping is |
32 | preferred over interrupt controller drivers open coding their own |
33 | reverse mapping scheme. |
34 | |
35 | irq_domain also implements translation from an abstract irq_fwspec |
36 | structure to hwirq numbers (Device Tree and ACPI GSI so far), and can |
37 | be easily extended to support other IRQ topology data sources. |
38 | |
39 | === irq_domain usage === |
40 | An interrupt controller driver creates and registers an irq_domain by |
41 | calling one of the irq_domain_add_*() functions (each mapping method |
42 | has a different allocator function, more on that later). The function |
43 | will return a pointer to the irq_domain on success. The caller must |
44 | provide the allocator function with an irq_domain_ops structure. |
45 | |
46 | In most cases, the irq_domain will begin empty without any mappings |
47 | between hwirq and IRQ numbers. Mappings are added to the irq_domain |
48 | by calling irq_create_mapping() which accepts the irq_domain and a |
49 | hwirq number as arguments. If a mapping for the hwirq doesn't already |
50 | exist then it will allocate a new Linux irq_desc, associate it with |
51 | the hwirq, and call the .map() callback so the driver can perform any |
52 | required hardware setup. |
53 | |
54 | When an interrupt is received, irq_find_mapping() function should |
55 | be used to find the Linux IRQ number from the hwirq number. |
56 | |
57 | The irq_create_mapping() function must be called *atleast once* |
58 | before any call to irq_find_mapping(), lest the descriptor will not |
59 | be allocated. |
60 | |
61 | If the driver has the Linux IRQ number or the irq_data pointer, and |
62 | needs to know the associated hwirq number (such as in the irq_chip |
63 | callbacks) then it can be directly obtained from irq_data->hwirq. |
64 | |
65 | === Types of irq_domain mappings === |
66 | There are several mechanisms available for reverse mapping from hwirq |
67 | to Linux irq, and each mechanism uses a different allocation function. |
68 | Which reverse map type should be used depends on the use case. Each |
69 | of the reverse map types are described below: |
70 | |
71 | ==== Linear ==== |
72 | irq_domain_add_linear() |
73 | irq_domain_create_linear() |
74 | |
75 | The linear reverse map maintains a fixed size table indexed by the |
76 | hwirq number. When a hwirq is mapped, an irq_desc is allocated for |
77 | the hwirq, and the IRQ number is stored in the table. |
78 | |
79 | The Linear map is a good choice when the maximum number of hwirqs is |
80 | fixed and a relatively small number (~ < 256). The advantages of this |
81 | map are fixed time lookup for IRQ numbers, and irq_descs are only |
82 | allocated for in-use IRQs. The disadvantage is that the table must be |
83 | as large as the largest possible hwirq number. |
84 | |
85 | irq_domain_add_linear() and irq_domain_create_linear() are functionally |
86 | equivalent, except for the first argument is different - the former |
87 | accepts an Open Firmware specific 'struct device_node', while the latter |
88 | accepts a more general abstraction 'struct fwnode_handle'. |
89 | |
90 | The majority of drivers should use the linear map. |
91 | |
92 | ==== Tree ==== |
93 | irq_domain_add_tree() |
94 | irq_domain_create_tree() |
95 | |
96 | The irq_domain maintains a radix tree map from hwirq numbers to Linux |
97 | IRQs. When an hwirq is mapped, an irq_desc is allocated and the |
98 | hwirq is used as the lookup key for the radix tree. |
99 | |
100 | The tree map is a good choice if the hwirq number can be very large |
101 | since it doesn't need to allocate a table as large as the largest |
102 | hwirq number. The disadvantage is that hwirq to IRQ number lookup is |
103 | dependent on how many entries are in the table. |
104 | |
105 | irq_domain_add_tree() and irq_domain_create_tree() are functionally |
106 | equivalent, except for the first argument is different - the former |
107 | accepts an Open Firmware specific 'struct device_node', while the latter |
108 | accepts a more general abstraction 'struct fwnode_handle'. |
109 | |
110 | Very few drivers should need this mapping. |
111 | |
112 | ==== No Map ===- |
113 | irq_domain_add_nomap() |
114 | |
115 | The No Map mapping is to be used when the hwirq number is |
116 | programmable in the hardware. In this case it is best to program the |
117 | Linux IRQ number into the hardware itself so that no mapping is |
118 | required. Calling irq_create_direct_mapping() will allocate a Linux |
119 | IRQ number and call the .map() callback so that driver can program the |
120 | Linux IRQ number into the hardware. |
121 | |
122 | Most drivers cannot use this mapping. |
123 | |
124 | ==== Legacy ==== |
125 | irq_domain_add_simple() |
126 | irq_domain_add_legacy() |
127 | irq_domain_add_legacy_isa() |
128 | |
129 | The Legacy mapping is a special case for drivers that already have a |
130 | range of irq_descs allocated for the hwirqs. It is used when the |
131 | driver cannot be immediately converted to use the linear mapping. For |
132 | example, many embedded system board support files use a set of #defines |
133 | for IRQ numbers that are passed to struct device registrations. In that |
134 | case the Linux IRQ numbers cannot be dynamically assigned and the legacy |
135 | mapping should be used. |
136 | |
137 | The legacy map assumes a contiguous range of IRQ numbers has already |
138 | been allocated for the controller and that the IRQ number can be |
139 | calculated by adding a fixed offset to the hwirq number, and |
140 | visa-versa. The disadvantage is that it requires the interrupt |
141 | controller to manage IRQ allocations and it requires an irq_desc to be |
142 | allocated for every hwirq, even if it is unused. |
143 | |
144 | The legacy map should only be used if fixed IRQ mappings must be |
145 | supported. For example, ISA controllers would use the legacy map for |
146 | mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ |
147 | numbers. |
148 | |
149 | Most users of legacy mappings should use irq_domain_add_simple() which |
150 | will use a legacy domain only if an IRQ range is supplied by the |
151 | system and will otherwise use a linear domain mapping. The semantics |
152 | of this call are such that if an IRQ range is specified then |
153 | descriptors will be allocated on-the-fly for it, and if no range is |
154 | specified it will fall through to irq_domain_add_linear() which means |
155 | *no* irq descriptors will be allocated. |
156 | |
157 | A typical use case for simple domains is where an irqchip provider |
158 | is supporting both dynamic and static IRQ assignments. |
159 | |
160 | In order to avoid ending up in a situation where a linear domain is |
161 | used and no descriptor gets allocated it is very important to make sure |
162 | that the driver using the simple domain call irq_create_mapping() |
163 | before any irq_find_mapping() since the latter will actually work |
164 | for the static IRQ assignment case. |
165 | |
166 | ==== Hierarchy IRQ domain ==== |
167 | On some architectures, there may be multiple interrupt controllers |
168 | involved in delivering an interrupt from the device to the target CPU. |
169 | Let's look at a typical interrupt delivering path on x86 platforms: |
170 | |
171 | Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU |
172 | |
173 | There are three interrupt controllers involved: |
174 | 1) IOAPIC controller |
175 | 2) Interrupt remapping controller |
176 | 3) Local APIC controller |
177 | |
178 | To support such a hardware topology and make software architecture match |
179 | hardware architecture, an irq_domain data structure is built for each |
180 | interrupt controller and those irq_domains are organized into hierarchy. |
181 | When building irq_domain hierarchy, the irq_domain near to the device is |
182 | child and the irq_domain near to CPU is parent. So a hierarchy structure |
183 | as below will be built for the example above. |
184 | CPU Vector irq_domain (root irq_domain to manage CPU vectors) |
185 | ^ |
186 | | |
187 | Interrupt Remapping irq_domain (manage irq_remapping entries) |
188 | ^ |
189 | | |
190 | IOAPIC irq_domain (manage IOAPIC delivery entries/pins) |
191 | |
192 | There are four major interfaces to use hierarchy irq_domain: |
193 | 1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt |
194 | controller related resources to deliver these interrupts. |
195 | 2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller |
196 | related resources associated with these interrupts. |
197 | 3) irq_domain_activate_irq(): activate interrupt controller hardware to |
198 | deliver the interrupt. |
199 | 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware |
200 | to stop delivering the interrupt. |
201 | |
202 | Following changes are needed to support hierarchy irq_domain. |
203 | 1) a new field 'parent' is added to struct irq_domain; it's used to |
204 | maintain irq_domain hierarchy information. |
205 | 2) a new field 'parent_data' is added to struct irq_data; it's used to |
206 | build hierarchy irq_data to match hierarchy irq_domains. The irq_data |
207 | is used to store irq_domain pointer and hardware irq number. |
208 | 3) new callbacks are added to struct irq_domain_ops to support hierarchy |
209 | irq_domain operations. |
210 | |
211 | With support of hierarchy irq_domain and hierarchy irq_data ready, an |
212 | irq_domain structure is built for each interrupt controller, and an |
213 | irq_data structure is allocated for each irq_domain associated with an |
214 | IRQ. Now we could go one step further to support stacked(hierarchy) |
215 | irq_chip. That is, an irq_chip is associated with each irq_data along |
216 | the hierarchy. A child irq_chip may implement a required action by |
217 | itself or by cooperating with its parent irq_chip. |
218 | |
219 | With stacked irq_chip, interrupt controller driver only needs to deal |
220 | with the hardware managed by itself and may ask for services from its |
221 | parent irq_chip when needed. So we could achieve a much cleaner |
222 | software architecture. |
223 | |
224 | For an interrupt controller driver to support hierarchy irq_domain, it |
225 | needs to: |
226 | 1) Implement irq_domain_ops.alloc and irq_domain_ops.free |
227 | 2) Optionally implement irq_domain_ops.activate and |
228 | irq_domain_ops.deactivate. |
229 | 3) Optionally implement an irq_chip to manage the interrupt controller |
230 | hardware. |
231 | 4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap, |
232 | they are unused with hierarchy irq_domain. |
233 | |
234 | Hierarchy irq_domain may also be used to support other architectures, |
235 | such as ARM, ARM64 etc. |
236 |