|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.
|This is simple when there is only one interrupt controller, but in
|systems with multiple interrupt controllers the kernel must ensure
|that each one gets assigned non-overlapping allocations of Linux
|The number of interrupt controllers registered as unique irqchips
|show a rising tendency: for example subdrivers of different kinds
|such as GPIO controllers avoid reimplementing identical callback
|mechanisms as the IRQ core system by modelling their interrupt
|handlers as irqchips, i.e. in effect cascading interrupt controllers.
|Here the interrupt number loose all kind of correspondence to
|hardware interrupt numbers: whereas in the past, IRQ numbers could
|be chosen so they matched the hardware IRQ line into the root
|interrupt controller (i.e. the component actually fireing the
|interrupt line to the CPU) nowadays this number is just a number.
|For this reason we need a mechanism to separate controller-local
|interrupt numbers, called hardware irq's, from Linux IRQ numbers.
|The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
|irq numbers, but they don't provide any support for reverse mapping of
|the controller-local IRQ (hwirq) number into the Linux IRQ number
|The irq_domain library adds mapping between hwirq and IRQ numbers on
|top of the irq_alloc_desc*() API. An irq_domain to manage mapping is
|preferred over interrupt controller drivers open coding their own
|reverse mapping scheme.
|irq_domain also implements translation from Device Tree interrupt
|specifiers to hwirq numbers, and can be easily extended to support
|other IRQ topology data sources.
|=== 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
|will return a pointer to the irq_domain on success. The caller must
|provide the allocator function with an irq_domain_ops structure with
|the .map callback populated as a minimum.
|In most cases, the irq_domain will begin empty without any mappings
|between hwirq and IRQ numbers. Mappings are added to the irq_domain
|by calling irq_create_mapping() which accepts the irq_domain and a
|hwirq number as arguments. If a mapping for the hwirq doesn't already
|exist then it will allocate a new Linux irq_desc, associate it with
|the hwirq, and call the .map() callback so the driver can perform any
|required hardware setup.
|When an interrupt is received, irq_find_mapping() function should
|be used to find the Linux IRQ number from the hwirq number.
|The irq_create_mapping() function must be called *atleast once*
|before any call to irq_find_mapping(), lest the descriptor will not
|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
|callbacks) then it can be directly obtained from irq_data->hwirq.
|=== 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 ====
|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
|the hwirq, and the IRQ number is stored in the table.
|The Linear map is a good choice when the maximum number of hwirqs is
|fixed and a relatively small number (~ < 256). The advantages of this
|map are fixed time lookup for IRQ numbers, and irq_descs are only
|allocated for in-use IRQs. The disadvantage is that the table must be
|as large as the largest possible hwirq number.
|The majority of drivers should use the linear map.
|==== Tree ====
|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
|hwirq is used as the lookup key for the radix tree.
|The tree map is a good choice if the hwirq number can be very large
|since it doesn't need to allocate a table as large as the largest
|hwirq number. The disadvantage is that hwirq to IRQ number lookup is
|dependent on how many entries are in the table.
|Very few drivers should need this mapping. At the moment, powerpc
|iseries is the only user.
|==== No Map ===-
|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
|Linux IRQ number into the hardware itself so that no mapping is
|required. Calling irq_create_direct_mapping() will allocate a Linux
|IRQ number and call the .map() callback so that driver can program the
|Linux IRQ number into the hardware.
|Most drivers cannot use this mapping.
|==== Legacy ====
|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
|driver cannot be immediately converted to use the linear mapping. For
|example, many embedded system board support files use a set of #defines
|for IRQ numbers that are passed to struct device registrations. In that
|case the Linux IRQ numbers cannot be dynamically assigned and the legacy
|mapping should be used.
|The legacy map assumes a contiguous range of IRQ numbers has already
|been allocated for the controller and that the IRQ number can be
|calculated by adding a fixed offset to the hwirq number, and
|visa-versa. The disadvantage is that it requires the interrupt
|controller to manage IRQ allocations and it requires an irq_desc to be
|allocated for every hwirq, even if it is unused.
|The legacy map should only be used if fixed IRQ mappings must be
|supported. For example, ISA controllers would use the legacy map for
|mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ
|Most users of legacy mappings should use irq_domain_add_simple() which
|will use a legacy domain only if an IRQ range is supplied by the
|system and will otherwise use a linear domain mapping. The semantics
|of this call are such that if an IRQ range is specified then
|descriptors will be allocated on-the-fly for it, and if no range is
|specified it will fall through to irq_domain_add_linear() which meand
|*no* irq descriptors will be allocated.
|A typical use case for simple domains is where an irqchip provider
|is supporting both dynamic and static IRQ assignments.
|In order to avoid ending up in a situation where a linear domain is
|used and no descriptor gets allocated it is very important to make sure
|that the driver using the simple domain call irq_create_mapping()
|before any irq_find_mapping() since the latter will actually work
|for the static IRQ assignment case.