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 | |
44 | provide the allocator function with an irq_domain_ops structure with | |
45 | the .map callback populated as a minimum. | |
46 | ||
47 | In most cases, the irq_domain will begin empty without any mappings | |
48 | between hwirq and IRQ numbers. Mappings are added to the irq_domain | |
49 | by calling irq_create_mapping() which accepts the irq_domain and a | |
50 | hwirq number as arguments. If a mapping for the hwirq doesn't already | |
51 | exist then it will allocate a new Linux irq_desc, associate it with | |
52 | the hwirq, and call the .map() callback so the driver can perform any | |
53 | required hardware setup. | |
54 | ||
55 | When an interrupt is received, irq_find_mapping() function should | |
56 | be used to find the Linux IRQ number from the hwirq number. | |
57 | ||
023bba36 LW |
58 | The irq_create_mapping() function must be called *atleast once* |
59 | before any call to irq_find_mapping(), lest the descriptor will not | |
60 | be allocated. | |
61 | ||
7ab3a837 GL |
62 | If the driver has the Linux IRQ number or the irq_data pointer, and |
63 | needs to know the associated hwirq number (such as in the irq_chip | |
64 | callbacks) then it can be directly obtained from irq_data->hwirq. | |
65 | ||
66 | === Types of irq_domain mappings === | |
67 | There are several mechanisms available for reverse mapping from hwirq | |
68 | to Linux irq, and each mechanism uses a different allocation function. | |
69 | Which reverse map type should be used depends on the use case. Each | |
70 | of the reverse map types are described below: | |
71 | ||
72 | ==== Linear ==== | |
73 | irq_domain_add_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 | The majority of drivers should use the linear map. | |
86 | ||
87 | ==== Tree ==== | |
88 | irq_domain_add_tree() | |
89 | ||
90 | The irq_domain maintains a radix tree map from hwirq numbers to Linux | |
91 | IRQs. When an hwirq is mapped, an irq_desc is allocated and the | |
92 | hwirq is used as the lookup key for the radix tree. | |
93 | ||
94 | The tree map is a good choice if the hwirq number can be very large | |
95 | since it doesn't need to allocate a table as large as the largest | |
96 | hwirq number. The disadvantage is that hwirq to IRQ number lookup is | |
97 | dependent on how many entries are in the table. | |
98 | ||
99 | Very few drivers should need this mapping. At the moment, powerpc | |
100 | iseries is the only user. | |
101 | ||
102 | ==== No Map ===- | |
103 | irq_domain_add_nomap() | |
104 | ||
105 | The No Map mapping is to be used when the hwirq number is | |
106 | programmable in the hardware. In this case it is best to program the | |
107 | Linux IRQ number into the hardware itself so that no mapping is | |
108 | required. Calling irq_create_direct_mapping() will allocate a Linux | |
109 | IRQ number and call the .map() callback so that driver can program the | |
110 | Linux IRQ number into the hardware. | |
111 | ||
112 | Most drivers cannot use this mapping. | |
113 | ||
114 | ==== Legacy ==== | |
781d0f46 | 115 | irq_domain_add_simple() |
7ab3a837 GL |
116 | irq_domain_add_legacy() |
117 | irq_domain_add_legacy_isa() | |
118 | ||
119 | The Legacy mapping is a special case for drivers that already have a | |
120 | range of irq_descs allocated for the hwirqs. It is used when the | |
121 | driver cannot be immediately converted to use the linear mapping. For | |
122 | example, many embedded system board support files use a set of #defines | |
123 | for IRQ numbers that are passed to struct device registrations. In that | |
124 | case the Linux IRQ numbers cannot be dynamically assigned and the legacy | |
125 | mapping should be used. | |
126 | ||
127 | The legacy map assumes a contiguous range of IRQ numbers has already | |
128 | been allocated for the controller and that the IRQ number can be | |
129 | calculated by adding a fixed offset to the hwirq number, and | |
130 | visa-versa. The disadvantage is that it requires the interrupt | |
131 | controller to manage IRQ allocations and it requires an irq_desc to be | |
132 | allocated for every hwirq, even if it is unused. | |
133 | ||
134 | The legacy map should only be used if fixed IRQ mappings must be | |
135 | supported. For example, ISA controllers would use the legacy map for | |
136 | mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ | |
137 | numbers. | |
781d0f46 MB |
138 | |
139 | Most users of legacy mappings should use irq_domain_add_simple() which | |
140 | will use a legacy domain only if an IRQ range is supplied by the | |
023bba36 LW |
141 | system and will otherwise use a linear domain mapping. The semantics |
142 | of this call are such that if an IRQ range is specified then | |
143 | descriptors will be allocated on-the-fly for it, and if no range is | |
144 | specified it will fall through to irq_domain_add_linear() which meand | |
145 | *no* irq descriptors will be allocated. | |
146 | ||
147 | A typical use case for simple domains is where an irqchip provider | |
148 | is supporting both dynamic and static IRQ assignments. | |
149 | ||
150 | In order to avoid ending up in a situation where a linear domain is | |
151 | used and no descriptor gets allocated it is very important to make sure | |
152 | that the driver using the simple domain call irq_create_mapping() | |
153 | before any irq_find_mapping() since the latter will actually work | |
154 | for the static IRQ assignment case. |