Describe interrupts-extended property

The interrupts-extended property is a common property used when
interrupt generating devices having interrupt lines in several interrupt
controllers with possibly distinct interrupt specifiers.

Signed-off-by: Florian Fainelli <[email protected]>
[grant.likely: editorial changes]
Signed-off-by: Grant Likely <[email protected]>

Author: ffainelli

source/devicetree-basics.rst

@@ -930,6 +930,9 @@ Description:
    specifiers. The format of an interrupt specifier is defined by the
    binding of the interrupt domain root.
 
+   *interrupts* is overridden by the *interrupts-extended*
+   property and normally only one or the other should be used.
+
 Example:
 
    A common definition of an interrupt specifier in an open PIC–compatible
@@ -955,6 +958,40 @@ Description:
    to the interrupt parent. If this property is missing from a device, its
    interrupt parent is assumed to be its devicetree parent.
 
+interrupts-extended
+^^^^^^^^^^^^^^^^^^^
+
+Property: ``interrupts-extended``
+
+Value type: ``<phandle> <prop-encoded-array>``
+
+Description:
+
+   The *interrupts-extended* property lists the interrupt(s) generated by a
+   device.
+   *interrupts-extended* should be used instead of *interrupts* when a device
+   is connected to multiple interrupt controllers as it encodes a parent phandle
+   with each interrupt specifier.
+
+Example:
+
+   This example shows how a device with two interrupt outputs connected to two
+   separate interrupt controllers would describe the connection using an
+   *interrupts-extended* property.
+   ``pic`` is an interrupt controller with an *#interrupt-cells* specifier
+   of 2, while ``gic`` is an interrupt controller with an *#interrupts-cells*
+   specifier of 1.
+
+      ``interrupts-extended = <&pic 0xA 8>, <&gic 0xda>;``
+
+
+The *interrupts* and *interrupts-extended* properties are mutually exclusive.
+A device node should use one or the other, but not both.
+Using both is only permissible when required for compatibility with software
+that does not understand *interrupts-extended*.
+If both *interrupts-extended* and *interrupts* are present then
+*interrupts-extended* takes precedence.
+
 Properties for Interrupt Controllers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~