Debian Codegraph @

Documentation/core-api/irq/irq-domain.rst

raw
1 ===============================================
2 The irq_domain Interrupt Number Mapping Library
3 ===============================================
4
5 The current design of the Linux kernel uses a single large number
6 space where each separate IRQ source is assigned a unique number.
7 This is simple when there is only one interrupt controller. But in
8 systems with multiple interrupt controllers, the kernel must ensure
9 that each one gets assigned non-overlapping allocations of Linux
10 IRQ numbers.
11
12 The number of interrupt controllers registered as unique irqchips
13 shows a rising tendency. For example, subdrivers of different kinds
14 such as GPIO controllers avoid reimplementing identical callback
15 mechanisms as the IRQ core system by modelling their interrupt
16 handlers as irqchips. I.e. in effect cascading interrupt controllers.
17
18 So in the past, IRQ numbers could be chosen so that they match the
19 hardware IRQ line into the root interrupt controller (i.e. the
20 component actually firing the interrupt line to the CPU). Nowadays,
21 this number is just a number and the number has no
22 relationship to hardware interrupt numbers.
23
24 For this reason, we need a mechanism to separate controller-local
25 interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
26
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
30 space.
31
32 The irq_domain library adds a mapping between hwirq and IRQ numbers on
33 top of the irq_alloc_desc*() API. An irq_domain to manage the mapping
34 is preferred over interrupt controller drivers open coding their own
35 reverse mapping scheme.
36
37 irq_domain also implements a translation from an abstract struct
38 irq_fwspec to hwirq numbers (Device Tree, non-DT firmware node, ACPI
39 GSI, and software node so far), and can be easily extended to support
40 other IRQ topology data sources. The implementation is performed
41 without any extra platform support code.
42
43 irq_domain Usage
44 ================
45 struct irq_domain could be defined as an irq domain controller. That
46 is, it handles the mapping between hardware and virtual interrupt
47 numbers for a given interrupt domain. The domain structure is
48 generally created by the PIC code for a given PIC instance (though a
49 domain can cover more than one PIC if they have a flat number model).
50 It is the domain callbacks that are responsible for setting the
51 irq_chip on a given irq_desc after it has been mapped.
52
53 The host code and data structures use a fwnode_handle pointer to
54 identify the domain. In some cases, and in order to preserve source
55 code compatibility, this fwnode pointer is "upgraded" to a DT
56 device_node. For those firmware infrastructures that do not provide a
57 unique identifier for an interrupt controller, the irq_domain code
58 offers a fwnode allocator.
59
60 An interrupt controller driver creates and registers a struct irq_domain
61 by calling one of the irq_domain_create_*() functions (each mapping
62 method has a different allocator function, more on that later). The
63 function will return a pointer to the struct irq_domain on success. The
64 caller must provide the allocator function with a struct irq_domain_ops
65 pointer.
66
67 In most cases, the irq_domain will begin empty without any mappings
68 between hwirq and IRQ numbers. Mappings are added to the irq_domain
69 by calling irq_create_mapping() which accepts the irq_domain and a
70 hwirq number as arguments. If a mapping for the hwirq doesn't already
71 exist, irq_create_mapping() allocates a new Linux irq_desc, associates
72 it with the hwirq, and calls the :c:member:`irq_domain_ops.map()`
73 callback. In there, the driver can perform any required hardware
74 setup.
75
76 Once a mapping has been established, it can be retrieved or used via a
77 variety of methods:
78
79 - irq_resolve_mapping() returns a pointer to the irq_desc structure
80 for a given domain and hwirq number, or NULL if there was no
81 mapping.
82 - irq_find_mapping() returns a Linux IRQ number for a given domain and
83 hwirq number, or 0 if there was no mapping
84 - generic_handle_domain_irq() handles an interrupt described by a
85 domain and a hwirq number
86
87 Note that irq_domain lookups must happen in contexts that are
88 compatible with an RCU read-side critical section.
89
90 The irq_create_mapping() function must be called *at least once*
91 before any call to irq_find_mapping(), lest the descriptor will not
92 be allocated.
93
94 If the driver has the Linux IRQ number or the irq_data pointer, and
95 needs to know the associated hwirq number (such as in the irq_chip
96 callbacks) then it can be directly obtained from
97 :c:member:`irq_data.hwirq`.
98
99 Types of irq_domain Mappings
100 ============================
101
102 There are several mechanisms available for reverse mapping from hwirq
103 to Linux IRQ, and each mechanism uses a different allocation function.
104 Which reverse map type should be used depends on the use case. Each
105 of the reverse map types are described below:
106
107 Linear
108 ------
109
110 ::
111
112 irq_domain_create_linear()
113
114 The linear reverse map maintains a fixed-size table indexed by the
115 hwirq number. When a hwirq is mapped, an irq_desc is allocated for
116 the hwirq, and the IRQ number is stored in the table.
117
118 The Linear map is a good choice when the maximum number of hwirqs is
119 fixed and a relatively small number (~ < 256). The advantages of this
120 map are fixed-time lookup for IRQ numbers, and irq_descs are only
121 allocated for in-use IRQs. The disadvantage is that the table must be
122 as large as the largest possible hwirq number.
123
124 The majority of drivers should use the Linear map.
125
126 Tree
127 ----
128
129 ::
130
131 irq_domain_create_tree()
132
133 The irq_domain maintains a radix tree map from hwirq numbers to Linux
134 IRQs. When an hwirq is mapped, an irq_desc is allocated and the
135 hwirq is used as the lookup key for the radix tree.
136
137 The Tree map is a good choice if the hwirq number can be very large
138 since it doesn't need to allocate a table as large as the largest
139 hwirq number. The disadvantage is that hwirq to IRQ number lookup is
140 dependent on how many entries are in the table.
141
142 Very few drivers should need this mapping.
143
144 No Map
145 ------
146
147 ::
148
149 irq_domain_create_nomap()
150
151 The No Map mapping is to be used when the hwirq number is
152 programmable in the hardware. In this case it is best to program the
153 Linux IRQ number into the hardware itself so that no mapping is
154 required. Calling irq_create_direct_mapping() will allocate a Linux
155 IRQ number and call the .map() callback so that driver can program the
156 Linux IRQ number into the hardware.
157
158 Most drivers cannot use this mapping, and it is now gated on the
159 CONFIG_IRQ_DOMAIN_NOMAP option. Please refrain from introducing new
160 users of this API.
161
162 Legacy
163 ------
164
165 ::
166
167 irq_domain_create_simple()
168 irq_domain_create_legacy()
169
170 The Legacy mapping is a special case for drivers that already have a
171 range of irq_descs allocated for the hwirqs. It is used when the
172 driver cannot be immediately converted to use the Linear mapping. For
173 example, many embedded system board support files use a set of #defines
174 for IRQ numbers that are passed to struct device registrations. In that
175 case the Linux IRQ numbers cannot be dynamically assigned and the Legacy
176 mapping should be used.
177
178 As the name implies, the \*_legacy() functions are deprecated and only
179 exist to ease the support of ancient platforms. No new users should be
180 added. Same goes for the \*_simple() functions when their use results
181 in the legacy behaviour.
182
183 The Legacy map assumes a contiguous range of IRQ numbers has already
184 been allocated for the controller and that the IRQ number can be
185 calculated by adding a fixed offset to the hwirq number, and
186 visa-versa. The disadvantage is that it requires the interrupt
187 controller to manage IRQ allocations and it requires an irq_desc to be
188 allocated for every hwirq, even if it is unused.
189
190 The Legacy map should only be used if fixed IRQ mappings must be
191 supported. For example, ISA controllers would use the Legacy map for
192 mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ
193 numbers.
194
195 Most users of legacy mappings should use irq_domain_create_simple()
196 which will use a legacy domain only if an IRQ range is supplied by the
197 system and will otherwise use a linear domain mapping. The semantics of
198 this call are such that if an IRQ range is specified then descriptors
199 will be allocated on-the-fly for it, and if no range is specified it
200 will fall through to irq_domain_create_linear() which means *no* IRQ
201 descriptors will be allocated.
202
203 A typical use case for simple domains is where an irqchip provider
204 is supporting both dynamic and static IRQ assignments.
205
206 In order to avoid ending up in a situation where a linear domain is
207 used and no descriptor gets allocated it is very important to make sure
208 that the driver using the simple domain call irq_create_mapping()
209 before any irq_find_mapping() since the latter will actually work
210 for the static IRQ assignment case.
211
212 Hierarchy IRQ Domain
213 --------------------
214
215 On some architectures, there may be multiple interrupt controllers
216 involved in delivering an interrupt from the device to the target CPU.
217 Let's look at a typical interrupt delivery path on x86 platforms::
218
219 Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
220
221 There are three interrupt controllers involved:
222
223 1) IOAPIC controller
224 2) Interrupt remapping controller
225 3) Local APIC controller
226
227 To support such a hardware topology and make software architecture match
228 hardware architecture, an irq_domain data structure is built for each
229 interrupt controller and those irq_domains are organized into hierarchy.
230 When building irq_domain hierarchy, the irq_domain nearest the device is
231 child and the irq_domain nearest the CPU is parent. So a hierarchy structure
232 as below will be built for the example above::
233
234 CPU Vector irq_domain (root irq_domain to manage CPU vectors)
235 ^
236 |
237 Interrupt Remapping irq_domain (manage irq_remapping entries)
238 ^
239 |
240 IOAPIC irq_domain (manage IOAPIC delivery entries/pins)
241
242 There are four major interfaces to use hierarchy irq_domain:
243
244 1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt
245 controller related resources to deliver these interrupts.
246 2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller
247 related resources associated with these interrupts.
248 3) irq_domain_activate_irq(): activate interrupt controller hardware to
249 deliver the interrupt.
250 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
251 to stop delivering the interrupt.
252
253 The following is needed to support hierarchy irq_domain:
254
255 1) The :c:member:`parent` field in struct irq_domain is used to
256 maintain irq_domain hierarchy information.
257 2) The :c:member:`parent_data` field in struct irq_data is used to
258 build hierarchy irq_data to match hierarchy irq_domains. The
259 irq_data is used to store irq_domain pointer and hardware irq
260 number.
261 3) The :c:member:`alloc()`, :c:member:`free()`, and other callbacks in
262 struct irq_domain_ops to support hierarchy irq_domain operations.
263
264 With the support of hierarchy irq_domain and hierarchy irq_data ready,
265 an irq_domain structure is built for each interrupt controller, and an
266 irq_data structure is allocated for each irq_domain associated with an
267 IRQ.
268
269 For an interrupt controller driver to support hierarchy irq_domain, it
270 needs to:
271
272 1) Implement irq_domain_ops.alloc() and irq_domain_ops.free()
273 2) Optionally, implement irq_domain_ops.activate() and
274 irq_domain_ops.deactivate().
275 3) Optionally, implement an irq_chip to manage the interrupt controller
276 hardware.
277 4) There is no need to implement irq_domain_ops.map() and
278 irq_domain_ops.unmap(). They are unused with hierarchy irq_domain.
279
280 Note the hierarchy irq_domain is in no way x86-specific, and is
281 heavily used to support other architectures, such as ARM, ARM64 etc.
282
283 Stacked irq_chip
284 ~~~~~~~~~~~~~~~~
285
286 Now, we could go one step further to support stacked (hierarchy)
287 irq_chip. That is, an irq_chip is associated with each irq_data along
288 the hierarchy. A child irq_chip may implement a required action by
289 itself or by cooperating with its parent irq_chip.
290
291 With stacked irq_chip, interrupt controller driver only needs to deal
292 with the hardware managed by itself and may ask for services from its
293 parent irq_chip when needed. So we could achieve a much cleaner
294 software architecture.
295
296 Debugging
297 =========
298
299 Most of the internals of the IRQ subsystem are exposed in debugfs by
300 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
301
302 Structures and Public Functions Provided
303 ========================================
304
305 This chapter contains the autogenerated documentation of the structures
306 and exported kernel API functions which are used for IRQ domains.
307
308 .. kernel-doc:: include/linux/irqdomain.h
309
310 .. kernel-doc:: kernel/irq/irqdomain.c
311 :export:
312
313 Internal Functions Provided
314 ===========================
315
316 This chapter contains the autogenerated documentation of the internal
317 functions.
318
319 .. kernel-doc:: kernel/irq/irqdomain.c
320 :internal: