[PATCH v4] Documentation: dt: binding: fsl: add devicetree binding for describing RCPM

[PATCH v4] Documentation: dt: binding: fsl: add devicetree binding for describing RCPM

[Dongsheng Wang]

From: Wang Dongsheng <dongsheng.wang@freescale.com>

RCPM is the Run Control and Power Management module performs all
device-level tasks associated with device run control and power
management.

Add this for freescale powerpc platform and layerscape platform.

Signed-off-by: Chenhui Zhao <chenhui.zhao@freescale.com>
Signed-off-by: Tang Yuantian <Yuantian.Tang@freescale.com>
Signed-off-by: Wang Dongsheng <dongsheng.wang@freescale.com>
---
*v4*
- Change patch subject.
- A few grammatical mistakes.
- Change "rcpm-wakeup" property to "fsl,rcpm-wakeup" property.
- Remove a few "fsl,<chip>-rcpm" examples.
- Now the value of "fsl,#rcpm-wakeup-cells" is not contain rcpm node.
- Add a NOTE to describe IPPDEXPCR register.

*v3*
- Add "fsl,#rcpm-wakeup-cells" for rcpm node. The number of cells
  correspond rcpm-wakeup property.
- Modify rcpm-wakeup property description.

*v2*
- Remove P4080 example.
- Modify rcpm-wakeup property description.

diff --git a/Documentation/devicetree/bindings/soc/fsl/rcpm.txt b/Documentation/devicetree/bindings/soc/fsl/rcpm.txt
new file mode 100644
index 0000000..757e0eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/fsl/rcpm.txt
@@ -0,0 +1,64 @@
+* Run Control and Power Management
+-------------------------------------------
+The RCPM performs all device-level tasks associated with device run control
+and power management.
+
+Required properites:
+  - reg : Offset and length of the register set of the RCPM block.
+  - fsl,#rcpm-wakeup-cells : The number of IPPDEXPCR register cells in the
+	fsl,rcpm-wakeup property.
+  - compatible : Must contain a chip-specific RCPM block compatible string
+	and (if applicable) may contain a chassis-version RCPM compatible
+	string. Chip-specific strings are of the form "fsl,<chip>-rcpm",
+	such as:
+	* "fsl,p2041-rcpm"
+	* "fsl,p5020-rcpm"
+	* "fsl,t4240-rcpm"
+
+	Chassis-version strings are of the form "fsl,qoriq-rcpm-<version>",
+	such as:
+	* "fsl,qoriq-rcpm-1.0": for chassis 1.0 rcpm
+	* "fsl,qoriq-rcpm-2.0": for chassis 2.0 rcpm
+	* "fsl,qoriq-rcpm-2.1": for chassis 2.1 rcpm
+
+All references to "1.0" and "2.0" refer to the QorIQ chassis version to
+which the chip complies.
+Chassis Version		Example Chips
+---------------		-------------------------------
+1.0				p4080, p5020, p5040, p2041, p3041
+2.0				t4240, b4860, b4420
+2.1				t1040, ls1021
+
+Example:
+The RCPM node for T4240:
+	rcpm: global-utilities@e2000 {
+		compatible = "fsl,t4240-rcpm", "fsl,qoriq-rcpm-2.0";
+		reg = <0xe2000 0x1000>;
+		fsl,#rcpm-wakeup-cells = <2>;
+	};
+
+* Freescale RCPM Wakeup Source Device Tree Bindings
+-------------------------------------------
+Required fsl,rcpm-wakeup property should be added to a device node if the device
+can be used as a wakeup source.
+
+  - fsl,rcpm-wakeup: Consists of a pointer to the rcpm node and the IPPDEXPCR
+	register cells. The number of IPPDEXPCR register cells is defined in
+	"fsl,#rcpm-wakeup-cells" in the rcpm node. The first register cell is
+	the bit mask that should be set in IPPDEXPCR0, and the second register
+	cell is for IPPDEXPCR1, and so on.
+
+	Note: IPPDEXPCR(IP Powerdown Exception Control Register) provides a
+	mechanism for keeping certain blocks awake during STANDBY and MEM, in
+	order to use them as wake-up sources.
+
+Example:
+	lpuart0: serial@2950000 {
+		compatible = "fsl,ls1021a-lpuart";
+		reg = <0x0 0x2950000 0x0 0x1000>;
+		interrupts = <GIC_SPI 80 IRQ_TYPE_LEVEL_HIGH>;
+		clocks = <&sysclk>;
+		clock-names = "ipg";
+		fsl,rcpm-wakeup = <&rcpm 0x0 0x40000000>;
+		status = "disabled";
+	};
-- 
2.1.0.27.g96db324

Re: [PATCH v4] Documentation: dt: binding: fsl: add devicetree binding for describing RCPM

[Rob Herring]

+Sudeep

On Mon, Oct 26, 2015 at 02:44:12PM +0800, Dongsheng Wang wrote:
> From: Wang Dongsheng <dongsheng.wang@freescale.com>
> 
> RCPM is the Run Control and Power Management module performs all
> device-level tasks associated with device run control and power
> management.
> 
> Add this for freescale powerpc platform and layerscape platform.

[...]

> @@ -0,0 +1,64 @@
> +* Run Control and Power Management
> +-------------------------------------------
> +The RCPM performs all device-level tasks associated with device run control
> +and power management.
> +
> +Required properites:
> +  - reg : Offset and length of the register set of the RCPM block.
> +  - fsl,#rcpm-wakeup-cells : The number of IPPDEXPCR register cells in the
> +	fsl,rcpm-wakeup property.

[...]

> +* Freescale RCPM Wakeup Source Device Tree Bindings
> +-------------------------------------------
> +Required fsl,rcpm-wakeup property should be added to a device node if the device
> +can be used as a wakeup source.
> +
> +  - fsl,rcpm-wakeup: Consists of a pointer to the rcpm node and the IPPDEXPCR
> +	register cells. The number of IPPDEXPCR register cells is defined in
> +	"fsl,#rcpm-wakeup-cells" in the rcpm node. The first register cell is
> +	the bit mask that should be set in IPPDEXPCR0, and the second register
> +	cell is for IPPDEXPCR1, and so on.

We just merged a common wakeup source binding[1]. It doesn't really work 
in a similar way to what you have done, but I'd like to see something 
common here. How exactly wakeup is done tends to depend on whether 
interrupts are also wakeup signals or wake-up signally is completely 
separate from interrupts. Depending on that, I think there are 2 options 
here:

- Use the common binding and implement a stacked irqdomain for the 
wakeup controller.

- Extend the common binding to allow a phandle+args value to point to 
the wakeup controller.

Rob

[1] Documentation/devicetree/bindings/power/wakeup-source.txt

Re: [PATCH v4] Documentation: dt: binding: fsl: add devicetree binding for describing RCPM

[Scott Wood]

On Mon, 2015-11-16 at 11:26 -0600, Rob Herring wrote:
> +Sudeep
> 
> On Mon, Oct 26, 2015 at 02:44:12PM +0800, Dongsheng Wang wrote:
> > From: Wang Dongsheng <dongsheng.wang@freescale.com>
> > 
> > RCPM is the Run Control and Power Management module performs all
> > device-level tasks associated with device run control and power
> > management.
> > 
> > Add this for freescale powerpc platform and layerscape platform.
> 
> [...]
> 
> > @@ -0,0 +1,64 @@
> > +* Run Control and Power Management
> > +-------------------------------------------
> > +The RCPM performs all device-level tasks associated with device run
> > control
> > +and power management.
> > +
> > +Required properites:
> > +  - reg : Offset and length of the register set of the RCPM block.
> > +  - fsl,#rcpm-wakeup-cells : The number of IPPDEXPCR register cells in
> > the
> > +	fsl,rcpm-wakeup property.
> 
> [...]
> 
> > +* Freescale RCPM Wakeup Source Device Tree Bindings
> > +-------------------------------------------
> > +Required fsl,rcpm-wakeup property should be added to a device node if the
> > device
> > +can be used as a wakeup source.
> > +
> > +  - fsl,rcpm-wakeup: Consists of a pointer to the rcpm node and the
> > IPPDEXPCR
> > +	register cells. The number of IPPDEXPCR register cells is defined
> > in
> > +	"fsl,#rcpm-wakeup-cells" in the rcpm node. The first register
> > cell is
> > +	the bit mask that should be set in IPPDEXPCR0, and the second
> > register
> > +	cell is for IPPDEXPCR1, and so on.
> 
> We just merged a common wakeup source binding[1]. It doesn't really work 
> in a similar way to what you have done, but I'd like to see something 
> common here. How exactly wakeup is done tends to depend on whether 
> interrupts are also wakeup signals or wake-up signally is completely 
> separate from interrupts. Depending on that, I think there are 2 options 
> here:
> 
> - Use the common binding and implement a stacked irqdomain for the 
> wakeup controller.

I'm not sure what a stacked irqdomain is, but the mechanism described here
isn't about interrupts at all.  It's about controlling whether certain devices
are kept awake in order to have the possibility of generating a wakeup.  I
believe the actual wakeup comes via the ordinary device interrupt.

> - Extend the common binding to allow a phandle+args value to point to 
> the wakeup controller.

Possibly, but the description in the common binding would have to be fairly
vague to make the semantics fit.

The current common binding is also a bit confusing by saying that the presence
of the property means that all of the device's interrupts can be used as
wakeup events, but then saying that there can also be a dedicated wakeup but
not making it clear how to represent that...  Overloading it with device power
control might muddy things even further.

-Scott

Re: [PATCH v4] Documentation: dt: binding: fsl: add devicetree binding for describing RCPM

[Rob Herring]

On Mon, Nov 16, 2015 at 8:07 PM, Scott Wood <scottwood@freescale.com> wrote:
> On Mon, 2015-11-16 at 11:26 -0600, Rob Herring wrote:
>> +Sudeep
>>
>> On Mon, Oct 26, 2015 at 02:44:12PM +0800, Dongsheng Wang wrote:
>> > From: Wang Dongsheng <dongsheng.wang@freescale.com>
>> >
>> > RCPM is the Run Control and Power Management module performs all
>> > device-level tasks associated with device run control and power
>> > management.
>> >
>> > Add this for freescale powerpc platform and layerscape platform.
>>
>> [...]
>>
>> > @@ -0,0 +1,64 @@
>> > +* Run Control and Power Management
>> > +-------------------------------------------
>> > +The RCPM performs all device-level tasks associated with device run
>> > control
>> > +and power management.
>> > +
>> > +Required properites:
>> > +  - reg : Offset and length of the register set of the RCPM block.
>> > +  - fsl,#rcpm-wakeup-cells : The number of IPPDEXPCR register cells in
>> > the
>> > +   fsl,rcpm-wakeup property.
>>
>> [...]
>>
>> > +* Freescale RCPM Wakeup Source Device Tree Bindings
>> > +-------------------------------------------
>> > +Required fsl,rcpm-wakeup property should be added to a device node if the
>> > device
>> > +can be used as a wakeup source.
>> > +
>> > +  - fsl,rcpm-wakeup: Consists of a pointer to the rcpm node and the
>> > IPPDEXPCR
>> > +   register cells. The number of IPPDEXPCR register cells is defined
>> > in
>> > +   "fsl,#rcpm-wakeup-cells" in the rcpm node. The first register
>> > cell is
>> > +   the bit mask that should be set in IPPDEXPCR0, and the second
>> > register
>> > +   cell is for IPPDEXPCR1, and so on.
>>
>> We just merged a common wakeup source binding[1]. It doesn't really work
>> in a similar way to what you have done, but I'd like to see something
>> common here. How exactly wakeup is done tends to depend on whether
>> interrupts are also wakeup signals or wake-up signally is completely
>> separate from interrupts. Depending on that, I think there are 2 options
>> here:
>>
>> - Use the common binding and implement a stacked irqdomain for the
>> wakeup controller.
>
> I'm not sure what a stacked irqdomain is, but the mechanism described here
> isn't about interrupts at all.  It's about controlling whether certain devices
> are kept awake in order to have the possibility of generating a wakeup.  I
> believe the actual wakeup comes via the ordinary device interrupt.

Stacked irqdomains were recently added. They allow you to have
multiple layers of control of interrupt lines. What you typically see
is device interrupts will go to both the main interrupt controller and
a special wake-up controller. So both devices need to be controlled.
The main controller can be powered down in suspend, but the wake-up
controller remains powered and can bring the cpu and interrupt
controller back up.

Keeping a device awake (clocks and power on) is somewhat different
than wake-up mechanisms and we generally have the subsystems needed
for that. Directly exposing another block's registers to a client
driver is generally not the right way to do things. Although there is
syscon for all the misc signals the h/w designers just clumped
together.

>> - Extend the common binding to allow a phandle+args value to point to
>> the wakeup controller.
>
> Possibly, but the description in the common binding would have to be fairly
> vague to make the semantics fit.
>
> The current common binding is also a bit confusing by saying that the presence
> of the property means that all of the device's interrupts can be used as
> wakeup events, but then saying that there can also be a dedicated wakeup but
> not making it clear how to represent that...  Overloading it with device power
> control might muddy things even further.

I believe it just means any device interrupt can be used or only the
irq named "wakeup" can be used.

Rob

Re: [PATCH v4] Documentation: dt: binding: fsl: add devicetree binding for describing RCPM

[Scott Wood]

On Tue, 2015-11-17 at 16:05 -0600, Rob Herring wrote:
> On Mon, Nov 16, 2015 at 8:07 PM, Scott Wood <scottwood@freescale.com> wrote:
> > On Mon, 2015-11-16 at 11:26 -0600, Rob Herring wrote:
> > > We just merged a common wakeup source binding[1]. It doesn't really work
> > > in a similar way to what you have done, but I'd like to see something
> > > common here. How exactly wakeup is done tends to depend on whether
> > > interrupts are also wakeup signals or wake-up signally is completely
> > > separate from interrupts. Depending on that, I think there are 2 options
> > > here:
> > > 
> > > - Use the common binding and implement a stacked irqdomain for the
> > > wakeup controller.
> > 
> > I'm not sure what a stacked irqdomain is, but the mechanism described here
> > isn't about interrupts at all.  It's about controlling whether certain
> > devices
> > are kept awake in order to have the possibility of generating a wakeup.  I
> > believe the actual wakeup comes via the ordinary device interrupt.
> 
> Stacked irqdomains were recently added. They allow you to have
> multiple layers of control of interrupt lines. What you typically see
> is device interrupts will go to both the main interrupt controller and
> a special wake-up controller. So both devices need to be controlled.
> The main controller can be powered down in suspend, but the wake-up
> controller remains powered and can bring the cpu and interrupt
> controller back up.
> 
> Keeping a device awake (clocks and power on) is somewhat different
> than wake-up mechanisms and we generally have the subsystems needed
> for that.

I'm not sure how we'd map this to the clock infrastructure either.  We don't
have a control that turns the block on or off; instead, we have a bit that we
can set to tell the chip to not automatically turn a certain block off when
the chip goes to sleep.

> Directly exposing another block's registers to a client
> driver is generally not the right way to do things. Although there is
> syscon for all the misc signals the h/w designers just clumped
> together.

It's not really exposing the registers; it's exposing a wakeup specifier that
happens to match the content of a specific register.  The actual I/O is done
in the RCPM driver, not the client.

> > > - Extend the common binding to allow a phandle+args value to point to
> > > the wakeup controller.
> > 
> > Possibly, but the description in the common binding would have to be
> > fairly
> > vague to make the semantics fit.
> > 
> > The current common binding is also a bit confusing by saying that the
> > presence
> > of the property means that all of the device's interrupts can be used as
> > wakeup events, but then saying that there can also be a dedicated wakeup
> > but
> > not making it clear how to represent that...  Overloading it with device
> > power
> > control might muddy things even further.
> 
> I believe it just means any device interrupt can be used or only the
> irq named "wakeup" can be used.

That's what the examples show, but the binding itself says "device specific
interrupt name", not "wakeup".

-Scott