Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
DMARC-Filter: OpenDMARC Filter v1.3.2 smtp.codeaurora.org 8931560A50
Date:   Mon, 15 Apr 2019 15:11:47 -0600
From:   Lina Iyer <ilina@codeaurora.org>
To:     Marc Zyngier <marc.zyngier@arm.com>
Cc:     swboyd@chromium.org, evgreen@chromium.org,
        linux-kernel@vger.kernel.org, rplsssn@codeaurora.org,
        linux-arm-msm@vger.kernel.org, thierry.reding@gmail.com,
        bjorn.andersson@linaro.org, dianders@chromium.org,
        linus.walleij@linaro.org, Rob Herring <robh@kernel.org>
Subject: Re: [PATCH v4 03/10] of/irq: document properties for wakeup
 interrupt parent
Message-ID: <20190415211147.GB16124@codeaurora.org>
References: <20190313211844.29416-1-ilina@codeaurora.org>
 <20190313211844.29416-4-ilina@codeaurora.org>
 <20190318174236.072f0a95@why.wild-wind.fr.eu.org>
 <20190404155838.GD10883@codeaurora.org>
 <acd726c2-23fa-841a-a5c2-e00d39980021@arm.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Disposition: inline
In-Reply-To: <acd726c2-23fa-841a-a5c2-e00d39980021@arm.com>
User-Agent: Mutt/1.11.3 (2019-02-01)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Mon, Apr 15 2019 at 06:42 -0600, Marc Zyngier wrote:
>On 04/04/2019 16:58, Lina Iyer wrote:
>> On Mon, Mar 18 2019 at 11:54 -0600, Marc Zyngier wrote:
>>> On Wed, 13 Mar 2019 15:18:37 -0600
>>> Lina Iyer <ilina@codeaurora.org> wrote:
>>>
>>> Please do Cc Rob when posting DT related patches.
>>>
>>>> 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
>>>>
>>>> Signed-off-by: Lina Iyer <ilina@codeaurora.org>
>>>> ---
>>>> Changes in v4:
>>>> 	- Added this documentation
>>>> ---
>>>>  .../interrupt-controller/interrupts.txt       | 39 +++++++++++++++++++
>>>>  1 file changed, 39 insertions(+)
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
>>>> index 8a3c40829899..917b598317f5 100644
>>>> --- a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
>>>> +++ b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
>>>> @@ -108,3 +108,42 @@ 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:
>>>> +	irqdomain-map = <22 0 &intc 36 0>, <24 0 &intc 37 0>;
>>>> +	irqdomain-map-mask = <0xff 0>;
>>>> +	irqdomain-map-pass-thru = <0 0xff>;
>>>
>>>
>>> This doesn't quite explain how the mask and pass-thru properties are
>>> used. I guess that the mask is used to define the 'useful bits' on the
>>> incoming side, but pass-thru puzzles me. In your example, does it mean
>>> that incoming lines map to outgoing interrupt <0 0>?
>>>
>> Sorry about the late reply.
>>
>> How about this to go with the rest of the documentation -
>>
>> 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.
>
>I think you need to add #interrupt-cells in your example, which is
>otherwise hard to interpret.
>
Ok. Thanks, will add.

--Lina