On Sat, 2012-12-01 at 19:05 +0100, Linus Walleij wrote: > This updates the IRQdomain documentation a bit, by adding a more > verbose explanation to why we need this, and by adding some > extended documentation of the irq_domain_simple() usecase. > > Signed-off-by: Linus Walleij <linus.wall...@linaro.org> Thanks for doing this as the other day I was complaining about it and wanted to do this as you have already done. > --- > Documentation/IRQ-domain.txt | 34 +++++++++++++++++++++++++++++++++- > 1 file changed, 33 insertions(+), 1 deletion(-) > > diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt > index 1401cec..9bc9594 100644 > --- a/Documentation/IRQ-domain.txt > +++ b/Documentation/IRQ-domain.txt > @@ -7,6 +7,21 @@ systems with multiple interrupt controllers the kernel must > ensure > that each one gets assigned non-overlapping allocations of Linux > IRQ numbers. > > +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 > @@ -40,6 +55,10 @@ 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 > +be allocated. > + > 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. > @@ -119,4 +138,17 @@ numbers. > > 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. > +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.
-- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
