Root/
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 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 | |
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 | |
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 ==== |
115 | irq_domain_add_simple() |
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. |
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 |
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. |
155 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9