| 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: |