Commit 1642a1e6 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

IRQ-domain.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- use proper markups for titles;
- mark literal blocks as such;
- add blank lines where needed.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent ae2f26aa
irq_domain interrupt number mapping library ===============================================
The irq_domain interrupt number mapping library
===============================================
The current design of the Linux kernel uses a single large number The current design of the Linux kernel uses a single large number
space where each separate IRQ source is assigned a different number. space where each separate IRQ source is assigned a different number.
...@@ -36,7 +38,9 @@ irq_domain also implements translation from an abstract irq_fwspec ...@@ -36,7 +38,9 @@ irq_domain also implements translation from an abstract irq_fwspec
structure to hwirq numbers (Device Tree and ACPI GSI so far), and can structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
be easily extended to support other IRQ topology data sources. be easily extended to support other IRQ topology data sources.
=== irq_domain usage === irq_domain usage
================
An interrupt controller driver creates and registers an irq_domain by An interrupt controller driver creates and registers an irq_domain by
calling one of the irq_domain_add_*() functions (each mapping method calling one of the irq_domain_add_*() functions (each mapping method
has a different allocator function, more on that later). The function has a different allocator function, more on that later). The function
...@@ -62,15 +66,21 @@ If the driver has the Linux IRQ number or the irq_data pointer, and ...@@ -62,15 +66,21 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
needs to know the associated hwirq number (such as in the irq_chip needs to know the associated hwirq number (such as in the irq_chip
callbacks) then it can be directly obtained from irq_data->hwirq. callbacks) then it can be directly obtained from irq_data->hwirq.
=== Types of irq_domain mappings === Types of irq_domain mappings
============================
There are several mechanisms available for reverse mapping from hwirq There are several mechanisms available for reverse mapping from hwirq
to Linux irq, and each mechanism uses a different allocation function. to Linux irq, and each mechanism uses a different allocation function.
Which reverse map type should be used depends on the use case. Each Which reverse map type should be used depends on the use case. Each
of the reverse map types are described below: of the reverse map types are described below:
==== Linear ==== Linear
irq_domain_add_linear() ------
irq_domain_create_linear()
::
irq_domain_add_linear()
irq_domain_create_linear()
The linear reverse map maintains a fixed size table indexed by the The linear reverse map maintains a fixed size table indexed by the
hwirq number. When a hwirq is mapped, an irq_desc is allocated for hwirq number. When a hwirq is mapped, an irq_desc is allocated for
...@@ -89,9 +99,13 @@ accepts a more general abstraction 'struct fwnode_handle'. ...@@ -89,9 +99,13 @@ accepts a more general abstraction 'struct fwnode_handle'.
The majority of drivers should use the linear map. The majority of drivers should use the linear map.
==== Tree ==== Tree
irq_domain_add_tree() ----
irq_domain_create_tree()
::
irq_domain_add_tree()
irq_domain_create_tree()
The irq_domain maintains a radix tree map from hwirq numbers to Linux The irq_domain maintains a radix tree map from hwirq numbers to Linux
IRQs. When an hwirq is mapped, an irq_desc is allocated and the IRQs. When an hwirq is mapped, an irq_desc is allocated and the
...@@ -109,8 +123,12 @@ accepts a more general abstraction 'struct fwnode_handle'. ...@@ -109,8 +123,12 @@ accepts a more general abstraction 'struct fwnode_handle'.
Very few drivers should need this mapping. Very few drivers should need this mapping.
==== No Map ===- No Map
irq_domain_add_nomap() ------
::
irq_domain_add_nomap()
The No Map mapping is to be used when the hwirq number is The No Map mapping is to be used when the hwirq number is
programmable in the hardware. In this case it is best to program the programmable in the hardware. In this case it is best to program the
...@@ -121,10 +139,14 @@ Linux IRQ number into the hardware. ...@@ -121,10 +139,14 @@ Linux IRQ number into the hardware.
Most drivers cannot use this mapping. Most drivers cannot use this mapping.
==== Legacy ==== Legacy
irq_domain_add_simple() ------
irq_domain_add_legacy()
irq_domain_add_legacy_isa() ::
irq_domain_add_simple()
irq_domain_add_legacy()
irq_domain_add_legacy_isa()
The Legacy mapping is a special case for drivers that already have a The Legacy mapping is a special case for drivers that already have a
range of irq_descs allocated for the hwirqs. It is used when the range of irq_descs allocated for the hwirqs. It is used when the
...@@ -163,14 +185,17 @@ that the driver using the simple domain call irq_create_mapping() ...@@ -163,14 +185,17 @@ that the driver using the simple domain call irq_create_mapping()
before any irq_find_mapping() since the latter will actually work before any irq_find_mapping() since the latter will actually work
for the static IRQ assignment case. for the static IRQ assignment case.
==== Hierarchy IRQ domain ==== Hierarchy IRQ domain
--------------------
On some architectures, there may be multiple interrupt controllers On some architectures, there may be multiple interrupt controllers
involved in delivering an interrupt from the device to the target CPU. involved in delivering an interrupt from the device to the target CPU.
Let's look at a typical interrupt delivering path on x86 platforms: Let's look at a typical interrupt delivering path on x86 platforms::
Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
There are three interrupt controllers involved: There are three interrupt controllers involved:
1) IOAPIC controller 1) IOAPIC controller
2) Interrupt remapping controller 2) Interrupt remapping controller
3) Local APIC controller 3) Local APIC controller
...@@ -180,7 +205,8 @@ hardware architecture, an irq_domain data structure is built for each ...@@ -180,7 +205,8 @@ hardware architecture, an irq_domain data structure is built for each
interrupt controller and those irq_domains are organized into hierarchy. interrupt controller and those irq_domains are organized into hierarchy.
When building irq_domain hierarchy, the irq_domain near to the device is When building irq_domain hierarchy, the irq_domain near to the device is
child and the irq_domain near to CPU is parent. So a hierarchy structure child and the irq_domain near to CPU is parent. So a hierarchy structure
as below will be built for the example above. as below will be built for the example above::
CPU Vector irq_domain (root irq_domain to manage CPU vectors) CPU Vector irq_domain (root irq_domain to manage CPU vectors)
^ ^
| |
...@@ -190,6 +216,7 @@ as below will be built for the example above. ...@@ -190,6 +216,7 @@ as below will be built for the example above.
IOAPIC irq_domain (manage IOAPIC delivery entries/pins) IOAPIC irq_domain (manage IOAPIC delivery entries/pins)
There are four major interfaces to use hierarchy irq_domain: There are four major interfaces to use hierarchy irq_domain:
1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt 1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt
controller related resources to deliver these interrupts. controller related resources to deliver these interrupts.
2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller 2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller
...@@ -199,7 +226,8 @@ There are four major interfaces to use hierarchy irq_domain: ...@@ -199,7 +226,8 @@ There are four major interfaces to use hierarchy irq_domain:
4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
to stop delivering the interrupt. to stop delivering the interrupt.
Following changes are needed to support hierarchy irq_domain. Following changes are needed to support hierarchy irq_domain:
1) a new field 'parent' is added to struct irq_domain; it's used to 1) a new field 'parent' is added to struct irq_domain; it's used to
maintain irq_domain hierarchy information. maintain irq_domain hierarchy information.
2) a new field 'parent_data' is added to struct irq_data; it's used to 2) a new field 'parent_data' is added to struct irq_data; it's used to
...@@ -223,6 +251,7 @@ software architecture. ...@@ -223,6 +251,7 @@ software architecture.
For an interrupt controller driver to support hierarchy irq_domain, it For an interrupt controller driver to support hierarchy irq_domain, it
needs to: needs to:
1) Implement irq_domain_ops.alloc and irq_domain_ops.free 1) Implement irq_domain_ops.alloc and irq_domain_ops.free
2) Optionally implement irq_domain_ops.activate and 2) Optionally implement irq_domain_ops.activate and
irq_domain_ops.deactivate. irq_domain_ops.deactivate.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment