tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
irqdomain: update documentation
This updates the IRQdomain documentation a bit, by adding a more
verbose explanation to why we need this, and by adding some
extended documentation of the irq_domain_simple() usecase.
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
Signed-off-by: Grant Likely <grant.likely@secretlab.ca>
authored by
Linus Walleij
and committed by
Grant Likely
023bba36
d202b7b9
+33
-1
+33
-1
Documentation/IRQ-domain.txt
+33
-1
Documentation/IRQ-domain.txt
···
7
7
that each one gets assigned non-overlapping allocations of Linux
8
8
IRQ numbers.
9
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
+
10
25
The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
11
26
irq numbers, but they don't provide any support for reverse mapping of
12
27
the controller-local IRQ (hwirq) number into the Linux IRQ number
···
54
39
55
40
When an interrupt is received, irq_find_mapping() function should
56
41
be used to find the Linux IRQ number from the hwirq number.
42
+
43
+
The irq_create_mapping() function must be called *atleast once*
44
+
before any call to irq_find_mapping(), lest the descriptor will not
45
+
be allocated.
57
46
58
47
If the driver has the Linux IRQ number or the irq_data pointer, and
59
48
needs to know the associated hwirq number (such as in the irq_chip
···
138
119
139
120
Most users of legacy mappings should use irq_domain_add_simple() which
140
121
will use a legacy domain only if an IRQ range is supplied by the
141
-
system and will otherwise use a linear domain mapping.
122
+
system and will otherwise use a linear domain mapping. The semantics
123
+
of this call are such that if an IRQ range is specified then
124
+
descriptors will be allocated on-the-fly for it, and if no range is
125
+
specified it will fall through to irq_domain_add_linear() which meand
126
+
*no* irq descriptors will be allocated.
127
+
128
+
A typical use case for simple domains is where an irqchip provider
129
+
is supporting both dynamic and static IRQ assignments.
130
+
131
+
In order to avoid ending up in a situation where a linear domain is
132
+
used and no descriptor gets allocated it is very important to make sure
133
+
that the driver using the simple domain call irq_create_mapping()
134
+
before any irq_find_mapping() since the latter will actually work
135
+
for the static IRQ assignment case.