IRQ-domain.txt: standardize document format

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

space where each separate IRQ source is assigned a different number.

structure to hwirq numbers (Device Tree and ACPI GSI so far), and can

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

calling one of the irq_domain_add_*() functions (each mapping method

has a different allocator function, more on that later).  The function

needs to know the associated hwirq number (such as in the irq_chip

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

to Linux irq, and each mechanism uses a different allocation function.

Which reverse map type should be used depends on the use case.  Each

of the reverse map types are described below:

==== Linear ====

Linear

------

::

	irq_domain_add_linear()

	irq_domain_create_linear()

The majority of drivers should use the linear map.

==== Tree ====

Tree

----

::

	irq_domain_add_tree()

	irq_domain_create_tree()

Very few drivers should need this mapping.

==== No Map ===-

No Map

------

::

	irq_domain_add_nomap()

The No Map mapping is to be used when the hwirq number is

Most drivers cannot use this mapping.

==== Legacy ====

Legacy

------

::

	irq_domain_add_simple()

	irq_domain_add_legacy()

	irq_domain_add_legacy_isa()

before any irq_find_mapping() since the latter will actually work

for the static IRQ assignment case.

==== Hierarchy IRQ domain ====

Hierarchy IRQ domain

--------------------

On some architectures, there may be multiple interrupt controllers

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

There are three interrupt controllers involved:

1) IOAPIC controller

2) Interrupt remapping controller

3) Local APIC controller

interrupt controller and those irq_domains are organized into hierarchy.

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

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)

		^

		|

	IOAPIC irq_domain (manage IOAPIC delivery entries/pins)

There are four major interfaces to use hierarchy irq_domain:

1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt

   controller related resources to deliver these interrupts.

2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller

4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware

   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

   maintain irq_domain hierarchy information.

2) a new field 'parent_data' is added to struct irq_data; it's used to

For an interrupt controller driver to support hierarchy irq_domain, it

needs to:

1) Implement irq_domain_ops.alloc and irq_domain_ops.free

2) Optionally implement irq_domain_ops.activate and

   irq_domain_ops.deactivate.