| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <1327700179-17454-2-git-send-email-grant.likely@secretlab.ca> Date: Fri, 27 Jan 2012 14:35:55 -0700 From: Grant Likely <grant.likely@...retlab.ca> To: linux-kernel@...r.kernel.org, Benjamin Herrenschmidt <benh@...nel.crashing.org>, Thomas Gleixner <tglx@...utronix.de>, Milton Miller <miltonm@....com>, Rob Herring <rob.herring@...xeda.com>, Stephen Rothwell <sfr@...b.auug.org.au> Cc: devicetree-discuss@...ts.ozlabs.org, linux-arm-kernel@...ts.infradead.org, linuxppc-dev@...ts.ozlabs.org, Grant Likely <grant.likely@...retlab.ca> Subject: [PATCH v3 01/25] irq_domain: add documentation and MAINTAINERS entry. Documentation for irq_domain library which will be created in subsequent patches. Signed-off-by: Grant Likely <grant.likely@...retlab.ca> Cc: Benjamin Herrenschmidt <benh@...nel.crashing.org> Cc: Thomas Gleixner <tglx@...utronix.de> Cc: Rob Herring <rob.herring@...xeda.com> Cc: Milton Miller <miltonm@....com> --- 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 +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@...nel.crashing.org> +M: Grant Likely <grant.likely@...retlab.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@...ex.cz> S: Maintained -- 1.7.5.4 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@...r.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists