[PATCH v5 04/11] of: irq: document properties for wakeup interrupt parent

[PATCH v5 04/11] of: irq: document properties for wakeup interrupt parent

[Lina Iyer]

Some interrupt controllers in a SoC, are always powered on and have a
select interrupts routed to them, so that they can wakeup the SoC from
suspend. Add wakeup-parent DT property to refer to these interrupt
controllers.

If the interrupts routed to the wakeup parent are not sequential, than a
map needs to exist to associate the same interrupt line on multiple
interrupt controllers. Providing this map in every driver is cumbersome.
Let's add this in the device tree and document the properties to map the
interrupt specifiers

Cc: devicetree@vger.kernel.org
Signed-off-by: Lina Iyer <ilina@codeaurora.org>
---
Changes in v5:
	- Update documentation to describe masks in the example
Changes in v4:
	- Added this documentation
---
 .../interrupt-controller/interrupts.txt       | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
index 8a3c40829899..e3e43f5d5566 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
+++ b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
@@ -108,3 +108,57 @@ commonly used:
 			sensitivity = <7>;
 		};
 	};
+
+3) Interrupt wakeup parent
+--------------------------
+
+Some interrupt controllers in a SoC, are always powered on and have a select
+interrupts routed to them, so that they can wakeup the SoC from suspend. These
+interrupt controllers do not fall into the category of a parent interrupt
+controller and can be specified by the "wakeup-parent" property and contain a
+single phandle referring to the wakeup capable interrupt controller.
+
+   Example:
+	wakeup-parent = <&pdc_intc>;
+
+
+4) Interrupt mapping
+--------------------
+
+Sometimes interrupts may be detected by more than one interrupt controller
+(depending on which controller is active). The interrupt controllers may not
+be in hierarchy and therefore the interrupt controller driver is required to
+establish the relationship between the same interrupt at different interrupt
+controllers. If these interrupts are not sequential then a map needs to be
+specified to help identify these interrupts.
+
+Mapping the interrupt specifiers in the device tree can be done using the
+"irqdomain-map" property. The property contains interrupt specifier at the
+current interrupt controller followed by the interrupt specifier at the mapped
+interrupt controller.
+
+   irqdomain-map = <incoming-interrupt-specifier mapped-interrupt-specifier>
+
+The optional properties "irqdomain-map-mask" and "irqdomain-map-pass-thru" may
+be provided to help interpret the valid bits of the incoming and mapped
+interrupt specifiers respectively.
+
+   Example:
+	intc: interrupt-controller@17a00000 {
+		#interrupt-cells = <3>;
+	};
+
+	pinctrl@3400000 {
+		#interrupt-cells = <2>;
+		irqdomain-map = <22 0 &intc 36 0>, <24 0 &intc 37 0>;
+		irqdomain-map-mask = <0xff 0>;
+		irqdomain-map-pass-thru = <0 0xff>;
+	};
+
+In the above example, the input interrupt specifier map-mask <0xff 0> applied
+on the incoming interrupt specifier of the map <22 0>, <24 0>, returns the
+input interrupt 22, 24 etc. The second argument being irq type is immaterial
+from the map and is used from the incoming request instead. The pass-thru
+specifier parses the output interrupt specifier from the rest of the unparsed
+argments from the map <&intc 36 0>, <&intc 37 0> etc to return the output
+interrupt 36, 37 etc.
-- 
The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
a Linux Foundation Collaborative Project

[PATCH v5 07/11] dt-bindings: sdm845-pinctrl: add wakeup interrupt parent for GPIO

[Lina Iyer]

SDM845 SoC has an always-on interrupt controller (PDC) with select GPIO
routed to the PDC as interrupts that can be used to wake the system up
from deep low power modes and suspend.

Update the sdm845 pinctrl device bindings to reference the PDC wakeup
interrupt controller and the GPIO PDC interrupt map.

Cc: devicetree@vger.kernel.org
Signed-off-by: Lina Iyer <ilina@codeaurora.org>
---
 .../bindings/pinctrl/qcom,sdm845-pinctrl.txt  | 79 ++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt
index 665aadb5ea28..895832127193 100644
--- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt
@@ -53,7 +53,6 @@ pin, a group, or a list of pins or groups. This configuration can include the
 mux function to select on those pin(s)/group(s), and various pin configuration
 parameters, such as pull-up, drive strength, etc.
 
-
 PIN CONFIGURATION NODES:
 
 The name of each subnode is not important; all subnodes should be enumerated
@@ -160,6 +159,84 @@ Example:
 		#gpio-cells = <2>;
 		interrupt-controller;
 		#interrupt-cells = <2>;
+		wakeup-parent = <&pdc_intc>;
+		irqdomain-map = <1 0 &pdc_intc 30 0>,
+				<3 0 &pdc_intc 31 0>,
+				<5 0 &pdc_intc 32 0>,
+				<10 0 &pdc_intc 33 0>,
+				<11 0 &pdc_intc 34 0>,
+				<20 0 &pdc_intc 35 0>,
+				<22 0 &pdc_intc 36 0>,
+				<24 0 &pdc_intc 37 0>,
+				<26 0 &pdc_intc 38 0>,
+				<30 0 &pdc_intc 39 0>,
+				<31 0 &pdc_intc 117 0>,
+				<32 0 &pdc_intc 41 0>,
+				<34 0 &pdc_intc 42 0>,
+				<36 0 &pdc_intc 43 0>,
+				<37 0 &pdc_intc 44 0>,
+				<38 0 &pdc_intc 45 0>,
+				<39 0 &pdc_intc 46 0>,
+				<40 0 &pdc_intc 47 0>,
+				<41 0 &pdc_intc 115 0>,
+				<43 0 &pdc_intc 49 0>,
+				<44 0 &pdc_intc 50 0>,
+				<46 0 &pdc_intc 51 0>,
+				<48 0 &pdc_intc 52 0>,
+				<49 0 &pdc_intc 118 0>,
+				<52 0 &pdc_intc 54 0>,
+				<53 0 &pdc_intc 55 0>,
+				<54 0 &pdc_intc 56 0>,
+				<56 0 &pdc_intc 57 0>,
+				<57 0 &pdc_intc 58 0>,
+				<58 0 &pdc_intc 59 0>,
+				<59 0 &pdc_intc 60 0>,
+				<60 0 &pdc_intc 61 0>,
+				<61 0 &pdc_intc 62 0>,
+				<62 0 &pdc_intc 63 0>,
+				<63 0 &pdc_intc 64 0>,
+				<64 0 &pdc_intc 65 0>,
+				<66 0 &pdc_intc 66 0>,
+				<68 0 &pdc_intc 67 0>,
+				<71 0 &pdc_intc 68 0>,
+				<73 0 &pdc_intc 69 0>,
+				<77 0 &pdc_intc 70 0>,
+				<78 0 &pdc_intc 71 0>,
+				<79 0 &pdc_intc 72 0>,
+				<80 0 &pdc_intc 73 0>,
+				<84 0 &pdc_intc 74 0>,
+				<85 0 &pdc_intc 75 0>,
+				<86 0 &pdc_intc 76 0>,
+				<88 0 &pdc_intc 77 0>,
+				<89 0 &pdc_intc 116 0>,
+				<91 0 &pdc_intc 79 0>,
+				<92 0 &pdc_intc 80 0>,
+				<95 0 &pdc_intc 81 0>,
+				<96 0 &pdc_intc 82 0>,
+				<97 0 &pdc_intc 83 0>,
+				<101 0 &pdc_intc 84 0>,
+				<103 0 &pdc_intc 85 0>,
+				<104 0 &pdc_intc 86 0>,
+				<115 0 &pdc_intc 90 0>,
+				<116 0 &pdc_intc 91 0>,
+				<117 0 &pdc_intc 92 0>,
+				<118 0 &pdc_intc 93 0>,
+				<119 0 &pdc_intc 94 0>,
+				<120 0 &pdc_intc 95 0>,
+				<121 0 &pdc_intc 96 0>,
+				<122 0 &pdc_intc 97 0>,
+				<123 0 &pdc_intc 98 0>,
+				<124 0 &pdc_intc 99 0>,
+				<125 0 &pdc_intc 100 0>,
+				<127 0 &pdc_intc 102 0>,
+				<128 0 &pdc_intc 103 0>,
+				<129 0 &pdc_intc 104 0>,
+				<130 0 &pdc_intc 105 0>,
+				<132 0 &pdc_intc 106 0>,
+				<133 0 &pdc_intc 107 0>,
+				<145 0 &pdc_intc 108 0>;
+		irqdomain-map-mask = <0xff 0>;
+		irqdomain-map-pass-thru = <0 0xff>;
 
 		qup9_active: qup9-active {
 			mux {
-- 
The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
a Linux Foundation Collaborative Project

Re: [PATCH v5 04/11] of: irq: document properties for wakeup interrupt parent

[Rob Herring]

On Tue, May 7, 2019 at 3:41 PM Lina Iyer <ilina@codeaurora.org> wrote:
>
> Some interrupt controllers in a SoC, are always powered on and have a
> select interrupts routed to them, so that they can wakeup the SoC from
> suspend. Add wakeup-parent DT property to refer to these interrupt
> controllers.
>
> If the interrupts routed to the wakeup parent are not sequential, than a
> map needs to exist to associate the same interrupt line on multiple
> interrupt controllers. Providing this map in every driver is cumbersome.
> Let's add this in the device tree and document the properties to map the
> interrupt specifiers
>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Lina Iyer <ilina@codeaurora.org>
> ---
> Changes in v5:
>         - Update documentation to describe masks in the example
> Changes in v4:
>         - Added this documentation
> ---
>  .../interrupt-controller/interrupts.txt       | 54 +++++++++++++++++++
>  1 file changed, 54 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
> index 8a3c40829899..e3e43f5d5566 100644
> --- a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
> +++ b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
> @@ -108,3 +108,57 @@ commonly used:
>                         sensitivity = <7>;
>                 };
>         };
> +
> +3) Interrupt wakeup parent
> +--------------------------
> +
> +Some interrupt controllers in a SoC, are always powered on and have a select
> +interrupts routed to them, so that they can wakeup the SoC from suspend. These
> +interrupt controllers do not fall into the category of a parent interrupt
> +controller and can be specified by the "wakeup-parent" property and contain a
> +single phandle referring to the wakeup capable interrupt controller.
> +
> +   Example:
> +       wakeup-parent = <&pdc_intc>;
> +
> +
> +4) Interrupt mapping
> +--------------------
> +
> +Sometimes interrupts may be detected by more than one interrupt controller
> +(depending on which controller is active). The interrupt controllers may not
> +be in hierarchy and therefore the interrupt controller driver is required to
> +establish the relationship between the same interrupt at different interrupt
> +controllers. If these interrupts are not sequential then a map needs to be
> +specified to help identify these interrupts.
> +
> +Mapping the interrupt specifiers in the device tree can be done using the
> +"irqdomain-map" property. The property contains interrupt specifier at the
> +current interrupt controller followed by the interrupt specifier at the mapped
> +interrupt controller.
> +
> +   irqdomain-map = <incoming-interrupt-specifier mapped-interrupt-specifier>

I'm wondering why we need a new map property rather than just using
interrupt-map? Contrary to what Linus said, it is not PCI only.

It would be an extension of the current behavior. It's generally used
to map each interrupt to different parents or swizzle the routing (in
the PCI case). Generally, a node would be either an
'interrupt-controller' or an 'interrupt-map' node. The interrupt
parsing code (for the kernel at least) prioritizes
'interrupt-controller' path, so adding 'interrupt-map' could be done
without changing behavior.

Another concern I have with this is it only solves the problem of an
IRQ routed to multiple parents for the case of 2 parents. What happens
when we have an IRQ routed to 3 different parents? Maybe the solution
is the incoming-interrupt-specifier can be listed more than once. Marc
already expressed concerns with the scalability of interrupt-map
property, so that's maybe not an ideal solution.

> +
> +The optional properties "irqdomain-map-mask" and "irqdomain-map-pass-thru" may
> +be provided to help interpret the valid bits of the incoming and mapped
> +interrupt specifiers respectively.
> +
> +   Example:
> +       intc: interrupt-controller@17a00000 {
> +               #interrupt-cells = <3>;

The phandle doesn't count as a cell, so this should be 2.

> +       };
> +
> +       pinctrl@3400000 {
> +               #interrupt-cells = <2>;
> +               irqdomain-map = <22 0 &intc 36 0>, <24 0 &intc 37 0>;
> +               irqdomain-map-mask = <0xff 0>;
> +               irqdomain-map-pass-thru = <0 0xff>;
> +       };
> +
> +In the above example, the input interrupt specifier map-mask <0xff 0> applied
> +on the incoming interrupt specifier of the map <22 0>, <24 0>, returns the
> +input interrupt 22, 24 etc. The second argument being irq type is immaterial
> +from the map and is used from the incoming request instead. The pass-thru
> +specifier parses the output interrupt specifier from the rest of the unparsed
> +argments from the map <&intc 36 0>, <&intc 37 0> etc to return the output
> +interrupt 36, 37 etc.
> --
> The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
> a Linux Foundation Collaborative Project
>