| Message ID | 1327352870-14687-2-git-send-email-grant.likely@secretlab.ca (mailing list archive) |
|---|---|
| State | Not Applicable |
| Headers | show |
On 01/23/2012 01:07 PM, Grant Likely wrote: > Documentation for irq_domain library which will be created in subsequent > patches. > > Signed-off-by: Grant Likely <grant.likely@secretlab.ca> > Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org> > Cc: Thomas Gleixner <tglx@linutronix.de> > --- > Documentation/IRQ-domain.txt | 113 ++++++++++++++++++++++++++++++++++++++++++ > MAINTAINERS | 9 +++ > 2 files changed, 122 insertions(+), 0 deletions(-) > create mode 100644 Documentation/IRQ-domain.txt > > diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt > new file mode 100644 > index 0000000..247f32a > --- /dev/null > +++ b/Documentation/IRQ-domain.txt > @@ -0,0 +1,113 @@ > +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 controllers the kernel must ensure that each one does not with multiple interrupt controllers, > +get assigned overlapping allocations of Linux irq numbers. IRQ > + > +The irq_alloc_desc*() and irq_free_desc*() API provides allocation of I would say: APIs provide > +irq numbers, but it doesn't provide any support for reverse mapping of IRQ numbers, but they don't provide > +the controller-local irq (hwirq) number into the Linux irq number IRQ IRQ > +space. > + > +The irq_domain library adds mapping between hwirq and irq numbers on IRQ > +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 > + > +=== 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. It must provide "It" ? The caller ? > +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 IRQ > +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 Linux > +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. IRQ > + > +If the driver has the Linux irq number or the irq_data pointer, and IRQ > +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 IRQ, . > +Which reverse map type should be used depends on the use case. Each > +of the reverse map types are described below: > + > +==== Linear ==== > +irq_domain_add_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. IRQ > + > +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 IRQ > +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 ==== > +irq_domain_add_tree() > + > +The irq_domain maintains a radix tree map from hwirq numbers to linux Linux > +irqs. When an hwirq is mapped, and irq_desc is allocated and the IRQs. When a hwirq an > +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 IRQ > +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 ===- > +irq_domain_add_nomap() > + > +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 IRQ > +required. Calling irq_create_direct_mapping() will allocate a linux Linux > +irq number and call the .map() callback so that driver can program the IRQ > +Linux irq number into the hardware. IRQ > + > +Most drivers cannot use this mapping. > + > +==== Legacy ==== > +irq_domain_add_legacy() > +irq_domain_add_legacy_isa() > + > +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, such > +as when the driver is used in a system with fixed irq number IRQ > +assignments, as is typical in many embedded system board files. > + > +The legacy map assumes a contiguous range of irq numbers has already IRQ > +been allocated for the controller and that the irq number can be IRQ > +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 IRQ > +allocated for every hwirq, even if it is unused. > + > +Drivers should only use the legacy map if they have fixed irq mappings IRQ > +(#define IRQ_* in embedded board files). For example, ISA controllers > +mapped to Linux irqs 0-15 would use the legacy map. IRQs
On Tue, Jan 24, 2012 at 11:13:41AM -0800, Randy Dunlap wrote: > On 01/23/2012 01:07 PM, Grant Likely wrote: > > Documentation for irq_domain library which will be created in subsequent > > patches. > > > > Signed-off-by: Grant Likely <grant.likely@secretlab.ca> > > Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org> > > Cc: Thomas Gleixner <tglx@linutronix.de> > > --- > > Documentation/IRQ-domain.txt | 113 ++++++++++++++++++++++++++++++++++++++++++ > > MAINTAINERS | 9 +++ > > 2 files changed, 122 insertions(+), 0 deletions(-) > > create mode 100644 Documentation/IRQ-domain.txt > > > > diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt > > new file mode 100644 > > index 0000000..247f32a > > --- /dev/null > > +++ b/Documentation/IRQ-domain.txt > > @@ -0,0 +1,113 @@ > > +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 controllers the kernel must ensure that each one does not > > with multiple interrupt controllers, Hi Randy. Thanks for the comments. I've made the changes and they'll appear in v4 of the series. g.
diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt new file mode 100644 index 0000000..247f32a --- /dev/null +++ b/Documentation/IRQ-domain.txt @@ -0,0 +1,113 @@ +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 controllers the kernel must ensure that each one does not +get assigned overlapping allocations of Linux irq numbers. + +The irq_alloc_desc*() and irq_free_desc*() API provides allocation of +irq numbers, but it doesn't provide any support for reverse mapping of +the controller-local irq (hwirq) number into the Linux irq number +space. + +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. It 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. + +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 ==== +irq_domain_add_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 ==== +irq_domain_add_tree() + +The irq_domain maintains a radix tree map from hwirq numbers to linux +irqs. When an hwirq is mapped, and 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 ===- +irq_domain_add_nomap() + +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 ==== +irq_domain_add_legacy() +irq_domain_add_legacy_isa() + +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, such +as when the driver is used in a system with fixed irq number +assignments, as is typical in many embedded system board files. + +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. + +Drivers should only use the legacy map if they have fixed irq mappings +(#define IRQ_* in embedded board files). For example, ISA controllers +mapped to Linux irqs 0-15 would use the legacy map. diff --git a/MAINTAINERS b/MAINTAINERS index 89b70df..d308f0f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3626,6 +3626,15 @@ S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core F: kernel/irq/ +IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY) +M: Benjamin Herrenschmidt <benh@kernel.crashing.org> +M: Grant Likely <grant.likely@secretlab.ca> +T: git git://git.secretlab.ca/git/linux-2.6.git irqdomain/next +S: Maintained +F: Documentation/IRQ-domain.txt +F: include/linux/irqdomain.h +F: kernel/irq/irqdomain.c + ISAPNP M: Jaroslav Kysela <perex@perex.cz> S: Maintained
Documentation for irq_domain library which will be created in subsequent patches. Signed-off-by: Grant Likely <grant.likely@secretlab.ca> Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org> Cc: Thomas Gleixner <tglx@linutronix.de> --- Documentation/IRQ-domain.txt | 113 ++++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 9 +++ 2 files changed, 122 insertions(+), 0 deletions(-) create mode 100644 Documentation/IRQ-domain.txt