]>
Commit | Line | Data |
---|---|---|
7ab3a837 GL |
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 | ||
023bba36 LW |
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 | ||
7ab3a837 GL |
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 Device Tree interrupt | |
36 | specifiers to hwirq numbers, and can be easily extended to support | |
37 | 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 | |
a257954b | 44 | provide the allocator function with an irq_domain_ops structure. |
7ab3a837 GL |
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 | ||
023bba36 LW |
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 | ||
7ab3a837 GL |
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 | ||
74 | The linear reverse map maintains a fixed size table indexed by the | |
75 | hwirq number. When a hwirq is mapped, an irq_desc is allocated for | |
76 | the hwirq, and the IRQ number is stored in the table. | |
77 | ||
78 | The Linear map is a good choice when the maximum number of hwirqs is | |
79 | fixed and a relatively small number (~ < 256). The advantages of this | |
80 | map are fixed time lookup for IRQ numbers, and irq_descs are only | |
81 | allocated for in-use IRQs. The disadvantage is that the table must be | |
82 | as large as the largest possible hwirq number. | |
83 | ||
84 | The majority of drivers should use the linear map. | |
85 | ||
86 | ==== Tree ==== | |
87 | irq_domain_add_tree() | |
88 | ||
89 | The irq_domain maintains a radix tree map from hwirq numbers to Linux | |
90 | IRQs. When an hwirq is mapped, an irq_desc is allocated and the | |
91 | hwirq is used as the lookup key for the radix tree. | |
92 | ||
93 | The tree map is a good choice if the hwirq number can be very large | |
94 | since it doesn't need to allocate a table as large as the largest | |
95 | hwirq number. The disadvantage is that hwirq to IRQ number lookup is | |
96 | dependent on how many entries are in the table. | |
97 | ||
98 | Very few drivers should need this mapping. At the moment, powerpc | |
99 | iseries is the only user. | |
100 | ||
101 | ==== No Map ===- | |
102 | irq_domain_add_nomap() | |
103 | ||
104 | The No Map mapping is to be used when the hwirq number is | |
105 | programmable in the hardware. In this case it is best to program the | |
106 | Linux IRQ number into the hardware itself so that no mapping is | |
107 | required. Calling irq_create_direct_mapping() will allocate a Linux | |
108 | IRQ number and call the .map() callback so that driver can program the | |
109 | Linux IRQ number into the hardware. | |
110 | ||
111 | Most drivers cannot use this mapping. | |
112 | ||
113 | ==== Legacy ==== | |
781d0f46 | 114 | irq_domain_add_simple() |
7ab3a837 GL |
115 | irq_domain_add_legacy() |
116 | irq_domain_add_legacy_isa() | |
117 | ||
118 | The Legacy mapping is a special case for drivers that already have a | |
119 | range of irq_descs allocated for the hwirqs. It is used when the | |
120 | driver cannot be immediately converted to use the linear mapping. For | |
121 | example, many embedded system board support files use a set of #defines | |
122 | for IRQ numbers that are passed to struct device registrations. In that | |
123 | case the Linux IRQ numbers cannot be dynamically assigned and the legacy | |
124 | mapping should be used. | |
125 | ||
126 | The legacy map assumes a contiguous range of IRQ numbers has already | |
127 | been allocated for the controller and that the IRQ number can be | |
128 | calculated by adding a fixed offset to the hwirq number, and | |
129 | visa-versa. The disadvantage is that it requires the interrupt | |
130 | controller to manage IRQ allocations and it requires an irq_desc to be | |
131 | allocated for every hwirq, even if it is unused. | |
132 | ||
133 | The legacy map should only be used if fixed IRQ mappings must be | |
134 | supported. For example, ISA controllers would use the legacy map for | |
135 | mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ | |
136 | numbers. | |
781d0f46 MB |
137 | |
138 | Most users of legacy mappings should use irq_domain_add_simple() which | |
139 | will use a legacy domain only if an IRQ range is supplied by the | |
023bba36 LW |
140 | system and will otherwise use a linear domain mapping. The semantics |
141 | of this call are such that if an IRQ range is specified then | |
142 | descriptors will be allocated on-the-fly for it, and if no range is | |
d9a6ed1f | 143 | specified it will fall through to irq_domain_add_linear() which means |
023bba36 LW |
144 | *no* irq descriptors will be allocated. |
145 | ||
146 | A typical use case for simple domains is where an irqchip provider | |
147 | is supporting both dynamic and static IRQ assignments. | |
148 | ||
149 | In order to avoid ending up in a situation where a linear domain is | |
150 | used and no descriptor gets allocated it is very important to make sure | |
151 | that the driver using the simple domain call irq_create_mapping() | |
152 | before any irq_find_mapping() since the latter will actually work | |
153 | for the static IRQ assignment case. | |
f8264e34 JL |
154 | |
155 | ==== Hierarchy IRQ domain ==== | |
156 | On some architectures, there may be multiple interrupt controllers | |
157 | involved in delivering an interrupt from the device to the target CPU. | |
158 | Let's look at a typical interrupt delivering path on x86 platforms: | |
159 | ||
160 | Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU | |
161 | ||
162 | There are three interrupt controllers involved: | |
163 | 1) IOAPIC controller | |
164 | 2) Interrupt remapping controller | |
165 | 3) Local APIC controller | |
166 | ||
167 | To support such a hardware topology and make software architecture match | |
168 | hardware architecture, an irq_domain data structure is built for each | |
169 | interrupt controller and those irq_domains are organized into hierarchy. | |
170 | When building irq_domain hierarchy, the irq_domain near to the device is | |
171 | child and the irq_domain near to CPU is parent. So a hierarchy structure | |
172 | as below will be built for the example above. | |
173 | CPU Vector irq_domain (root irq_domain to manage CPU vectors) | |
174 | ^ | |
175 | | | |
176 | Interrupt Remapping irq_domain (manage irq_remapping entries) | |
177 | ^ | |
178 | | | |
179 | IOAPIC irq_domain (manage IOAPIC delivery entries/pins) | |
180 | ||
181 | There are four major interfaces to use hierarchy irq_domain: | |
182 | 1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt | |
183 | controller related resources to deliver these interrupts. | |
184 | 2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller | |
185 | related resources associated with these interrupts. | |
186 | 3) irq_domain_activate_irq(): activate interrupt controller hardware to | |
187 | deliver the interrupt. | |
188 | 3) irq_domain_deactivate_irq(): deactivate interrupt controller hardware | |
189 | to stop delivering the interrupt. | |
190 | ||
191 | Following changes are needed to support hierarchy irq_domain. | |
192 | 1) a new field 'parent' is added to struct irq_domain; it's used to | |
193 | maintain irq_domain hierarchy information. | |
194 | 2) a new field 'parent_data' is added to struct irq_data; it's used to | |
195 | build hierarchy irq_data to match hierarchy irq_domains. The irq_data | |
196 | is used to store irq_domain pointer and hardware irq number. | |
197 | 3) new callbacks are added to struct irq_domain_ops to support hierarchy | |
198 | irq_domain operations. | |
199 | ||
200 | With support of hierarchy irq_domain and hierarchy irq_data ready, an | |
201 | irq_domain structure is built for each interrupt controller, and an | |
202 | irq_data structure is allocated for each irq_domain associated with an | |
203 | IRQ. Now we could go one step further to support stacked(hierarchy) | |
204 | irq_chip. That is, an irq_chip is associated with each irq_data along | |
205 | the hierarchy. A child irq_chip may implement a required action by | |
206 | itself or by cooperating with its parent irq_chip. | |
207 | ||
208 | With stacked irq_chip, interrupt controller driver only needs to deal | |
209 | with the hardware managed by itself and may ask for services from its | |
210 | parent irq_chip when needed. So we could achieve a much cleaner | |
211 | software architecture. | |
212 | ||
213 | For an interrupt controller driver to support hierarchy irq_domain, it | |
214 | needs to: | |
215 | 1) Implement irq_domain_ops.alloc and irq_domain_ops.free | |
216 | 2) Optionally implement irq_domain_ops.activate and | |
217 | irq_domain_ops.deactivate. | |
218 | 3) Optionally implement an irq_chip to manage the interrupt controller | |
219 | hardware. | |
220 | 4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap, | |
221 | they are unused with hierarchy irq_domain. | |
222 | ||
223 | Hierarchy irq_domain may also be used to support other architectures, | |
224 | such as ARM, ARM64 etc. |