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 irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of |
11 | irq numbers, but they don't provide any support for reverse mapping of |
12 | the controller-local IRQ (hwirq) number into the Linux IRQ number |
13 | space. |
14 | |
15 | The irq_domain library adds mapping between hwirq and IRQ numbers on |
16 | top of the irq_alloc_desc*() API. An irq_domain to manage mapping is |
17 | preferred over interrupt controller drivers open coding their own |
18 | reverse mapping scheme. |
19 | |
20 | irq_domain also implements translation from Device Tree interrupt |
21 | specifiers to hwirq numbers, and can be easily extended to support |
22 | other IRQ topology data sources. |
23 | |
24 | === irq_domain usage === |
25 | An interrupt controller driver creates and registers an irq_domain by |
26 | calling one of the irq_domain_add_*() functions (each mapping method |
27 | has a different allocator function, more on that later). The function |
28 | will return a pointer to the irq_domain on success. The caller must |
29 | provide the allocator function with an irq_domain_ops structure with |
30 | the .map callback populated as a minimum. |
31 | |
32 | In most cases, the irq_domain will begin empty without any mappings |
33 | between hwirq and IRQ numbers. Mappings are added to the irq_domain |
34 | by calling irq_create_mapping() which accepts the irq_domain and a |
35 | hwirq number as arguments. If a mapping for the hwirq doesn't already |
36 | exist then it will allocate a new Linux irq_desc, associate it with |
37 | the hwirq, and call the .map() callback so the driver can perform any |
38 | required hardware setup. |
39 | |
40 | When an interrupt is received, irq_find_mapping() function should |
41 | be used to find the Linux IRQ number from the hwirq number. |
42 | |
43 | If the driver has the Linux IRQ number or the irq_data pointer, and |
44 | needs to know the associated hwirq number (such as in the irq_chip |
45 | callbacks) then it can be directly obtained from irq_data->hwirq. |
46 | |
47 | === Types of irq_domain mappings === |
48 | There are several mechanisms available for reverse mapping from hwirq |
49 | to Linux irq, and each mechanism uses a different allocation function. |
50 | Which reverse map type should be used depends on the use case. Each |
51 | of the reverse map types are described below: |
52 | |
53 | ==== Linear ==== |
54 | irq_domain_add_linear() |
55 | |
56 | The linear reverse map maintains a fixed size table indexed by the |
57 | hwirq number. When a hwirq is mapped, an irq_desc is allocated for |
58 | the hwirq, and the IRQ number is stored in the table. |
59 | |
60 | The Linear map is a good choice when the maximum number of hwirqs is |
61 | fixed and a relatively small number (~ < 256). The advantages of this |
62 | map are fixed time lookup for IRQ numbers, and irq_descs are only |
63 | allocated for in-use IRQs. The disadvantage is that the table must be |
64 | as large as the largest possible hwirq number. |
65 | |
66 | The majority of drivers should use the linear map. |
67 | |
68 | ==== Tree ==== |
69 | irq_domain_add_tree() |
70 | |
71 | The irq_domain maintains a radix tree map from hwirq numbers to Linux |
72 | IRQs. When an hwirq is mapped, an irq_desc is allocated and the |
73 | hwirq is used as the lookup key for the radix tree. |
74 | |
75 | The tree map is a good choice if the hwirq number can be very large |
76 | since it doesn't need to allocate a table as large as the largest |
77 | hwirq number. The disadvantage is that hwirq to IRQ number lookup is |
78 | dependent on how many entries are in the table. |
79 | |
80 | Very few drivers should need this mapping. At the moment, powerpc |
81 | iseries is the only user. |
82 | |
83 | ==== No Map ===- |
84 | irq_domain_add_nomap() |
85 | |
86 | The No Map mapping is to be used when the hwirq number is |
87 | programmable in the hardware. In this case it is best to program the |
88 | Linux IRQ number into the hardware itself so that no mapping is |
89 | required. Calling irq_create_direct_mapping() will allocate a Linux |
90 | IRQ number and call the .map() callback so that driver can program the |
91 | Linux IRQ number into the hardware. |
92 | |
93 | Most drivers cannot use this mapping. |
94 | |
95 | ==== Legacy ==== |
96 | irq_domain_add_legacy() |
97 | irq_domain_add_legacy_isa() |
98 | |
99 | The Legacy mapping is a special case for drivers that already have a |
100 | range of irq_descs allocated for the hwirqs. It is used when the |
101 | driver cannot be immediately converted to use the linear mapping. For |
102 | example, many embedded system board support files use a set of #defines |
103 | for IRQ numbers that are passed to struct device registrations. In that |
104 | case the Linux IRQ numbers cannot be dynamically assigned and the legacy |
105 | mapping should be used. |
106 | |
107 | The legacy map assumes a contiguous range of IRQ numbers has already |
108 | been allocated for the controller and that the IRQ number can be |
109 | calculated by adding a fixed offset to the hwirq number, and |
110 | visa-versa. The disadvantage is that it requires the interrupt |
111 | controller to manage IRQ allocations and it requires an irq_desc to be |
112 | allocated for every hwirq, even if it is unused. |
113 | |
114 | The legacy map should only be used if fixed IRQ mappings must be |
115 | supported. For example, ISA controllers would use the legacy map for |
116 | mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ |
117 | numbers. |
118 |
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