[RFC,7/8] dt-bindings: Add bindings documentation for RISC-V idle states

Message ID 20210221093758.210981-8-anup.patel@wdc.com
State Superseded
Headers show
Series
  • RISC-V CPU Idle Support
Related show

Commit Message

Anup Patel Feb. 21, 2021, 9:37 a.m.
The RISC-V CPU idle states will be described in DT under the
/cpus/riscv-idle-states DT node. This patch adds the bindings
documentation for riscv-idle-states DT nodes and idle state DT
nodes under it.

Signed-off-by: Anup Patel <anup.patel@wdc.com>
---
 .../bindings/riscv/idle-states.yaml           | 250 ++++++++++++++++++
 1 file changed, 250 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/riscv/idle-states.yaml

Comments

Rob Herring March 5, 2021, 11:22 p.m. | #1
On Sun, Feb 21, 2021 at 03:07:57PM +0530, Anup Patel wrote:
> The RISC-V CPU idle states will be described in DT under the

> /cpus/riscv-idle-states DT node. This patch adds the bindings

> documentation for riscv-idle-states DT nodes and idle state DT

> nodes under it.

> 

> Signed-off-by: Anup Patel <anup.patel@wdc.com>

> ---

>  .../bindings/riscv/idle-states.yaml           | 250 ++++++++++++++++++

>  1 file changed, 250 insertions(+)

>  create mode 100644 Documentation/devicetree/bindings/riscv/idle-states.yaml

> 

> diff --git a/Documentation/devicetree/bindings/riscv/idle-states.yaml b/Documentation/devicetree/bindings/riscv/idle-states.yaml

> new file mode 100644

> index 000000000000..3eff763fed23

> --- /dev/null

> +++ b/Documentation/devicetree/bindings/riscv/idle-states.yaml

> @@ -0,0 +1,250 @@

> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

> +%YAML 1.2

> +---

> +$id: http://devicetree.org/schemas/riscv/idle-states.yaml#

> +$schema: http://devicetree.org/meta-schemas/core.yaml#

> +

> +title: RISC-V idle states binding description

> +

> +maintainers:

> +  - Anup Patel <anup.patel@wdc.com>

> +

> +description: |+

> +  RISC-V systems can manage power consumption dynamically, where HARTs

> +  (or CPUs) [1] can be put in different platform specific suspend (or

> +  idle) states (ranging from simple WFI, power gating, etc). The RISC-V

> +  SBI [2] hart state management extension provides a standard mechanism

> +  for OSes to request HART state transitions.

> +

> +  The platform specific suspend (or idle) states of a hart can be either

> +  retentive or non-rententive in nature. A retentive suspend state will

> +  preserve hart register and CSR values for all privilege modes whereas

> +  a non-retentive suspend state will not preserve hart register and CSR

> +  values. The suspend (or idle) state entered by executing the WFI

> +  instruction is considered standard on all RISC-V systems and therefore

> +  must not be listed in device tree.

> +

> +  The device tree binding definition for RISC-V idle states described

> +  in this document is quite similar to the ARM idle states [3].

> +

> +  References

> +

> +  [1] RISC-V Linux Kernel documentation - CPUs bindings

> +      Documentation/devicetree/bindings/riscv/cpus.yaml

> +

> +  [2] RISC-V Supervisor Binary Interface (SBI)

> +      http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc

> +

> +  [3] ARM idle states binding description - Idle states bindings

> +      Documentation/devicetree/bindings/arm/idle-states.yaml


I'd assume there's common parts we can share.

> +

> +properties:

> +  $nodename:

> +    const: riscv-idle-states


Just 'idle-states' like Arm.

> +

> +patternProperties:

> +  "^(cpu|cluster)-":

> +    type: object

> +    description: |

> +      Each state node represents an idle state description and must be

> +      defined as follows.

> +


       additionalProperties: false

> +    properties:

> +      compatible:

> +        const: riscv,idle-state

> +

> +      local-timer-stop:

> +        description:

> +          If present the CPU local timer control logic is lost on state

> +          entry, otherwise it is retained.

> +        type: boolean

> +

> +      entry-latency-us:

> +        description:

> +          Worst case latency in microseconds required to enter the idle state.

> +

> +      exit-latency-us:

> +        description:

> +          Worst case latency in microseconds required to exit the idle state.

> +          The exit-latency-us duration may be guaranteed only after

> +          entry-latency-us has passed.

> +

> +      min-residency-us:

> +        description:

> +          Minimum residency duration in microseconds, inclusive of preparation

> +          and entry, for this idle state to be considered worthwhile energy

> +          wise (refer to section 2 of this document for a complete description).

> +

> +      wakeup-latency-us:

> +        description: |

> +          Maximum delay between the signaling of a wake-up event and the CPU

> +          being able to execute normal code again. If omitted, this is assumed

> +          to be equal to:

> +

> +            entry-latency-us + exit-latency-us

> +

> +          It is important to supply this value on systems where the duration

> +          of PREP phase (see diagram 1, section 2) is non-neglibigle. In such

> +          systems entry-latency-us + exit-latency-us will exceed

> +          wakeup-latency-us by this duration.

> +

> +      idle-state-name:

> +        $ref: /schemas/types.yaml#/definitions/string

> +        description:

> +          A string used as a descriptive name for the idle state.

> +

> +    required:

> +      - compatible

> +      - entry-latency-us

> +      - exit-latency-us

> +      - min-residency-us

> +

> +additionalProperties: false

> +

> +examples:

> +  - |

> +

> +    cpus {

> +        #size-cells = <0>;

> +        #address-cells = <1>;

> +

> +        cpu@0 {

> +            device_type = "cpu";

> +            compatible = "riscv";

> +            reg = <0x0>;

> +            riscv,isa = "rv64imafdc";

> +            mmu-type = "riscv,sv48";

> +            cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0

> +                            &CLUSTER_RET_0 &CLUSTER_NONRET_0>;


You should need to add this property to your cpu schema.

> +

> +            cpu_intc0: interrupt-controller {

> +                #interrupt-cells = <1>;

> +                compatible = "riscv,cpu-intc";

> +                interrupt-controller;

> +            };

> +        };

> +

> +        cpu@1 {

> +            device_type = "cpu";

> +            compatible = "riscv";

> +            reg = <0x1>;

> +            riscv,isa = "rv64imafdc";

> +            mmu-type = "riscv,sv48";

> +            cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0

> +                            &CLUSTER_RET_0 &CLUSTER_NONRET_0>;

> +

> +            cpu_intc1: interrupt-controller {

> +                #interrupt-cells = <1>;

> +                compatible = "riscv,cpu-intc";

> +                interrupt-controller;

> +            };

> +        };

> +

> +        cpu@10 {

> +            device_type = "cpu";

> +            compatible = "riscv";

> +            reg = <0x10>;

> +            riscv,isa = "rv64imafdc";

> +            mmu-type = "riscv,sv48";

> +            cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0

> +                            &CLUSTER_RET_1 &CLUSTER_NONRET_1>;

> +

> +            cpu_intc10: interrupt-controller {

> +                #interrupt-cells = <1>;

> +                compatible = "riscv,cpu-intc";

> +                interrupt-controller;

> +            };

> +        };

> +

> +        cpu@11 {

> +            device_type = "cpu";

> +            compatible = "riscv";

> +            reg = <0x11>;

> +            riscv,isa = "rv64imafdc";

> +            mmu-type = "riscv,sv48";

> +            cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0

> +                            &CLUSTER_RET_1 &CLUSTER_NONRET_1>;

> +

> +            cpu_intc11: interrupt-controller {

> +                #interrupt-cells = <1>;

> +                compatible = "riscv,cpu-intc";

> +                interrupt-controller;

> +            };

> +        };

> +

> +        riscv-idle-states {

> +            CPU_RET_0_0: cpu-retentive-0-0 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x10000000>;


Not documented.

> +                entry-latency-us = <20>;

> +                exit-latency-us = <40>;

> +                min-residency-us = <80>;

> +            };

> +

> +            CPU_NONRET_0_0: cpu-nonretentive-0-0 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x90000000>;

> +                entry-latency-us = <250>;

> +                exit-latency-us = <500>;

> +                min-residency-us = <950>;

> +            };

> +

> +            CLUSTER_RET_0: cluster-retentive-0 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x11000000>;

> +                local-timer-stop;

> +                entry-latency-us = <50>;

> +                exit-latency-us = <100>;

> +                min-residency-us = <250>;

> +                wakeup-latency-us = <130>;

> +            };

> +

> +            CLUSTER_NONRET_0: cluster-nonretentive-0 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x91000000>;

> +                local-timer-stop;

> +                entry-latency-us = <600>;

> +                exit-latency-us = <1100>;

> +                min-residency-us = <2700>;

> +                wakeup-latency-us = <1500>;

> +            };

> +

> +            CPU_RET_1_0: cpu-retentive-1-0 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x10000010>;

> +                entry-latency-us = <20>;

> +                exit-latency-us = <40>;

> +                min-residency-us = <80>;

> +            };

> +

> +            CPU_NONRET_1_0: cpu-nonretentive-1-0 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x90000010>;

> +                entry-latency-us = <250>;

> +                exit-latency-us = <500>;

> +                min-residency-us = <950>;

> +            };

> +

> +            CLUSTER_RET_1: cluster-retentive-1 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x11000010>;

> +                local-timer-stop;

> +                entry-latency-us = <50>;

> +                exit-latency-us = <100>;

> +                min-residency-us = <250>;

> +                wakeup-latency-us = <130>;

> +            };

> +

> +            CLUSTER_NONRET_1: cluster-nonretentive-1 {

> +                compatible = "riscv,idle-state";

> +                riscv,sbi-suspend-param = <0x91000010>;

> +                local-timer-stop;

> +                entry-latency-us = <600>;

> +                exit-latency-us = <1100>;

> +                min-residency-us = <2700>;

> +                wakeup-latency-us = <1500>;

> +            };

> +        };

> +    };

> +

> +...

> -- 

> 2.25.1

>
Anup Patel March 8, 2021, 3:18 a.m. | #2
On Sat, Mar 6, 2021 at 4:52 AM Rob Herring <robh@kernel.org> wrote:
>

> On Sun, Feb 21, 2021 at 03:07:57PM +0530, Anup Patel wrote:

> > The RISC-V CPU idle states will be described in DT under the

> > /cpus/riscv-idle-states DT node. This patch adds the bindings

> > documentation for riscv-idle-states DT nodes and idle state DT

> > nodes under it.

> >

> > Signed-off-by: Anup Patel <anup.patel@wdc.com>

> > ---

> >  .../bindings/riscv/idle-states.yaml           | 250 ++++++++++++++++++

> >  1 file changed, 250 insertions(+)

> >  create mode 100644 Documentation/devicetree/bindings/riscv/idle-states.yaml

> >

> > diff --git a/Documentation/devicetree/bindings/riscv/idle-states.yaml b/Documentation/devicetree/bindings/riscv/idle-states.yaml

> > new file mode 100644

> > index 000000000000..3eff763fed23

> > --- /dev/null

> > +++ b/Documentation/devicetree/bindings/riscv/idle-states.yaml

> > @@ -0,0 +1,250 @@

> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

> > +%YAML 1.2

> > +---

> > +$id: http://devicetree.org/schemas/riscv/idle-states.yaml#

> > +$schema: http://devicetree.org/meta-schemas/core.yaml#

> > +

> > +title: RISC-V idle states binding description

> > +

> > +maintainers:

> > +  - Anup Patel <anup.patel@wdc.com>

> > +

> > +description: |+

> > +  RISC-V systems can manage power consumption dynamically, where HARTs

> > +  (or CPUs) [1] can be put in different platform specific suspend (or

> > +  idle) states (ranging from simple WFI, power gating, etc). The RISC-V

> > +  SBI [2] hart state management extension provides a standard mechanism

> > +  for OSes to request HART state transitions.

> > +

> > +  The platform specific suspend (or idle) states of a hart can be either

> > +  retentive or non-rententive in nature. A retentive suspend state will

> > +  preserve hart register and CSR values for all privilege modes whereas

> > +  a non-retentive suspend state will not preserve hart register and CSR

> > +  values. The suspend (or idle) state entered by executing the WFI

> > +  instruction is considered standard on all RISC-V systems and therefore

> > +  must not be listed in device tree.

> > +

> > +  The device tree binding definition for RISC-V idle states described

> > +  in this document is quite similar to the ARM idle states [3].

> > +

> > +  References

> > +

> > +  [1] RISC-V Linux Kernel documentation - CPUs bindings

> > +      Documentation/devicetree/bindings/riscv/cpus.yaml

> > +

> > +  [2] RISC-V Supervisor Binary Interface (SBI)

> > +      http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc

> > +

> > +  [3] ARM idle states binding description - Idle states bindings

> > +      Documentation/devicetree/bindings/arm/idle-states.yaml

>

> I'd assume there's common parts we can share.


Yes, except few properties most are the same.

We can have a shared DT bindings for both ARM and RISC-V but
both architectures will always have some architecture specific details
(or properties) which need to be documented under arch specific
DT documentation. Is it okay if this is done as a separate series ?

>

> > +

> > +properties:

> > +  $nodename:

> > +    const: riscv-idle-states

>

> Just 'idle-states' like Arm.


I had tried "idle-states" node name but DT bindings check complaints
conflict with ARM idle state bindings.

>

> > +

> > +patternProperties:

> > +  "^(cpu|cluster)-":

> > +    type: object

> > +    description: |

> > +      Each state node represents an idle state description and must be

> > +      defined as follows.

> > +

>

>        additionalProperties: false


okay, will update.

>

> > +    properties:

> > +      compatible:

> > +        const: riscv,idle-state

> > +

> > +      local-timer-stop:

> > +        description:

> > +          If present the CPU local timer control logic is lost on state

> > +          entry, otherwise it is retained.

> > +        type: boolean

> > +

> > +      entry-latency-us:

> > +        description:

> > +          Worst case latency in microseconds required to enter the idle state.

> > +

> > +      exit-latency-us:

> > +        description:

> > +          Worst case latency in microseconds required to exit the idle state.

> > +          The exit-latency-us duration may be guaranteed only after

> > +          entry-latency-us has passed.

> > +

> > +      min-residency-us:

> > +        description:

> > +          Minimum residency duration in microseconds, inclusive of preparation

> > +          and entry, for this idle state to be considered worthwhile energy

> > +          wise (refer to section 2 of this document for a complete description).

> > +

> > +      wakeup-latency-us:

> > +        description: |

> > +          Maximum delay between the signaling of a wake-up event and the CPU

> > +          being able to execute normal code again. If omitted, this is assumed

> > +          to be equal to:

> > +

> > +            entry-latency-us + exit-latency-us

> > +

> > +          It is important to supply this value on systems where the duration

> > +          of PREP phase (see diagram 1, section 2) is non-neglibigle. In such

> > +          systems entry-latency-us + exit-latency-us will exceed

> > +          wakeup-latency-us by this duration.

> > +

> > +      idle-state-name:

> > +        $ref: /schemas/types.yaml#/definitions/string

> > +        description:

> > +          A string used as a descriptive name for the idle state.

> > +

> > +    required:

> > +      - compatible

> > +      - entry-latency-us

> > +      - exit-latency-us

> > +      - min-residency-us

> > +

> > +additionalProperties: false


I will move this up.

> > +

> > +examples:

> > +  - |

> > +

> > +    cpus {

> > +        #size-cells = <0>;

> > +        #address-cells = <1>;

> > +

> > +        cpu@0 {

> > +            device_type = "cpu";

> > +            compatible = "riscv";

> > +            reg = <0x0>;

> > +            riscv,isa = "rv64imafdc";

> > +            mmu-type = "riscv,sv48";

> > +            cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0

> > +                            &CLUSTER_RET_0 &CLUSTER_NONRET_0>;

>

> You should need to add this property to your cpu schema.


Okay, will update.

>

> > +

> > +            cpu_intc0: interrupt-controller {

> > +                #interrupt-cells = <1>;

> > +                compatible = "riscv,cpu-intc";

> > +                interrupt-controller;

> > +            };

> > +        };

> > +

> > +        cpu@1 {

> > +            device_type = "cpu";

> > +            compatible = "riscv";

> > +            reg = <0x1>;

> > +            riscv,isa = "rv64imafdc";

> > +            mmu-type = "riscv,sv48";

> > +            cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0

> > +                            &CLUSTER_RET_0 &CLUSTER_NONRET_0>;

> > +

> > +            cpu_intc1: interrupt-controller {

> > +                #interrupt-cells = <1>;

> > +                compatible = "riscv,cpu-intc";

> > +                interrupt-controller;

> > +            };

> > +        };

> > +

> > +        cpu@10 {

> > +            device_type = "cpu";

> > +            compatible = "riscv";

> > +            reg = <0x10>;

> > +            riscv,isa = "rv64imafdc";

> > +            mmu-type = "riscv,sv48";

> > +            cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0

> > +                            &CLUSTER_RET_1 &CLUSTER_NONRET_1>;

> > +

> > +            cpu_intc10: interrupt-controller {

> > +                #interrupt-cells = <1>;

> > +                compatible = "riscv,cpu-intc";

> > +                interrupt-controller;

> > +            };

> > +        };

> > +

> > +        cpu@11 {

> > +            device_type = "cpu";

> > +            compatible = "riscv";

> > +            reg = <0x11>;

> > +            riscv,isa = "rv64imafdc";

> > +            mmu-type = "riscv,sv48";

> > +            cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0

> > +                            &CLUSTER_RET_1 &CLUSTER_NONRET_1>;

> > +

> > +            cpu_intc11: interrupt-controller {

> > +                #interrupt-cells = <1>;

> > +                compatible = "riscv,cpu-intc";

> > +                interrupt-controller;

> > +            };

> > +        };

> > +

> > +        riscv-idle-states {

> > +            CPU_RET_0_0: cpu-retentive-0-0 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x10000000>;

>

> Not documented.


Ahh, I missed this one. I will add it in next patch revision.

>

> > +                entry-latency-us = <20>;

> > +                exit-latency-us = <40>;

> > +                min-residency-us = <80>;

> > +            };

> > +

> > +            CPU_NONRET_0_0: cpu-nonretentive-0-0 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x90000000>;

> > +                entry-latency-us = <250>;

> > +                exit-latency-us = <500>;

> > +                min-residency-us = <950>;

> > +            };

> > +

> > +            CLUSTER_RET_0: cluster-retentive-0 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x11000000>;

> > +                local-timer-stop;

> > +                entry-latency-us = <50>;

> > +                exit-latency-us = <100>;

> > +                min-residency-us = <250>;

> > +                wakeup-latency-us = <130>;

> > +            };

> > +

> > +            CLUSTER_NONRET_0: cluster-nonretentive-0 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x91000000>;

> > +                local-timer-stop;

> > +                entry-latency-us = <600>;

> > +                exit-latency-us = <1100>;

> > +                min-residency-us = <2700>;

> > +                wakeup-latency-us = <1500>;

> > +            };

> > +

> > +            CPU_RET_1_0: cpu-retentive-1-0 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x10000010>;

> > +                entry-latency-us = <20>;

> > +                exit-latency-us = <40>;

> > +                min-residency-us = <80>;

> > +            };

> > +

> > +            CPU_NONRET_1_0: cpu-nonretentive-1-0 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x90000010>;

> > +                entry-latency-us = <250>;

> > +                exit-latency-us = <500>;

> > +                min-residency-us = <950>;

> > +            };

> > +

> > +            CLUSTER_RET_1: cluster-retentive-1 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x11000010>;

> > +                local-timer-stop;

> > +                entry-latency-us = <50>;

> > +                exit-latency-us = <100>;

> > +                min-residency-us = <250>;

> > +                wakeup-latency-us = <130>;

> > +            };

> > +

> > +            CLUSTER_NONRET_1: cluster-nonretentive-1 {

> > +                compatible = "riscv,idle-state";

> > +                riscv,sbi-suspend-param = <0x91000010>;

> > +                local-timer-stop;

> > +                entry-latency-us = <600>;

> > +                exit-latency-us = <1100>;

> > +                min-residency-us = <2700>;

> > +                wakeup-latency-us = <1500>;

> > +            };

> > +        };

> > +    };

> > +

> > +...

> > --

> > 2.25.1

> >


Regards,
Anup
Rob Herring March 16, 2021, 3:53 p.m. | #3
On Sun, Mar 7, 2021 at 8:18 PM Anup Patel <anup@brainfault.org> wrote:
>
> On Sat, Mar 6, 2021 at 4:52 AM Rob Herring <robh@kernel.org> wrote:
> >
> > On Sun, Feb 21, 2021 at 03:07:57PM +0530, Anup Patel wrote:
> > > The RISC-V CPU idle states will be described in DT under the
> > > /cpus/riscv-idle-states DT node. This patch adds the bindings
> > > documentation for riscv-idle-states DT nodes and idle state DT
> > > nodes under it.
> > >
> > > Signed-off-by: Anup Patel <anup.patel@wdc.com>
> > > ---
> > >  .../bindings/riscv/idle-states.yaml           | 250 ++++++++++++++++++
> > >  1 file changed, 250 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/riscv/idle-states.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/riscv/idle-states.yaml b/Documentation/devicetree/bindings/riscv/idle-states.yaml
> > > new file mode 100644
> > > index 000000000000..3eff763fed23
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/riscv/idle-states.yaml
> > > @@ -0,0 +1,250 @@
> > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/riscv/idle-states.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: RISC-V idle states binding description
> > > +
> > > +maintainers:
> > > +  - Anup Patel <anup.patel@wdc.com>
> > > +
> > > +description: |+
> > > +  RISC-V systems can manage power consumption dynamically, where HARTs
> > > +  (or CPUs) [1] can be put in different platform specific suspend (or
> > > +  idle) states (ranging from simple WFI, power gating, etc). The RISC-V
> > > +  SBI [2] hart state management extension provides a standard mechanism
> > > +  for OSes to request HART state transitions.
> > > +
> > > +  The platform specific suspend (or idle) states of a hart can be either
> > > +  retentive or non-rententive in nature. A retentive suspend state will
> > > +  preserve hart register and CSR values for all privilege modes whereas
> > > +  a non-retentive suspend state will not preserve hart register and CSR
> > > +  values. The suspend (or idle) state entered by executing the WFI
> > > +  instruction is considered standard on all RISC-V systems and therefore
> > > +  must not be listed in device tree.
> > > +
> > > +  The device tree binding definition for RISC-V idle states described
> > > +  in this document is quite similar to the ARM idle states [3].
> > > +
> > > +  References
> > > +
> > > +  [1] RISC-V Linux Kernel documentation - CPUs bindings
> > > +      Documentation/devicetree/bindings/riscv/cpus.yaml
> > > +
> > > +  [2] RISC-V Supervisor Binary Interface (SBI)
> > > +      http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc
> > > +
> > > +  [3] ARM idle states binding description - Idle states bindings
> > > +      Documentation/devicetree/bindings/arm/idle-states.yaml
> >
> > I'd assume there's common parts we can share.
>
> Yes, except few properties most are the same.
>
> We can have a shared DT bindings for both ARM and RISC-V but
> both architectures will always have some architecture specific details
> (or properties) which need to be documented under arch specific
> DT documentation. Is it okay if this is done as a separate series ?

No...

> > > +
> > > +properties:
> > > +  $nodename:
> > > +    const: riscv-idle-states
> >
> > Just 'idle-states' like Arm.
>
> I had tried "idle-states" node name but DT bindings check complaints
> conflict with ARM idle state bindings.

...and this being one reason why.

Actually, I think this can all be in 1 doc if you want. It's fine with
me if a common doc has RiscV and Arm specific properties.

> > > +
> > > +patternProperties:
> > > +  "^(cpu|cluster)-":
> > > +    type: object
> > > +    description: |
> > > +      Each state node represents an idle state description and must be
> > > +      defined as follows.
> > > +
> >
> >        additionalProperties: false
>
> okay, will update.
>
> >
> > > +    properties:
> > > +      compatible:
> > > +        const: riscv,idle-state
> > > +
> > > +      local-timer-stop:
> > > +        description:
> > > +          If present the CPU local timer control logic is lost on state
> > > +          entry, otherwise it is retained.
> > > +        type: boolean
> > > +
> > > +      entry-latency-us:
> > > +        description:
> > > +          Worst case latency in microseconds required to enter the idle state.
> > > +
> > > +      exit-latency-us:
> > > +        description:
> > > +          Worst case latency in microseconds required to exit the idle state.
> > > +          The exit-latency-us duration may be guaranteed only after
> > > +          entry-latency-us has passed.
> > > +
> > > +      min-residency-us:
> > > +        description:
> > > +          Minimum residency duration in microseconds, inclusive of preparation
> > > +          and entry, for this idle state to be considered worthwhile energy
> > > +          wise (refer to section 2 of this document for a complete description).
> > > +
> > > +      wakeup-latency-us:
> > > +        description: |
> > > +          Maximum delay between the signaling of a wake-up event and the CPU
> > > +          being able to execute normal code again. If omitted, this is assumed
> > > +          to be equal to:
> > > +
> > > +            entry-latency-us + exit-latency-us
> > > +
> > > +          It is important to supply this value on systems where the duration
> > > +          of PREP phase (see diagram 1, section 2) is non-neglibigle. In such
> > > +          systems entry-latency-us + exit-latency-us will exceed
> > > +          wakeup-latency-us by this duration.
> > > +
> > > +      idle-state-name:
> > > +        $ref: /schemas/types.yaml#/definitions/string
> > > +        description:
> > > +          A string used as a descriptive name for the idle state.
> > > +
> > > +    required:
> > > +      - compatible
> > > +      - entry-latency-us
> > > +      - exit-latency-us
> > > +      - min-residency-us
> > > +
> > > +additionalProperties: false
>
> I will move this up.

TBC, you need this at 2 levels. Both the idle-states node and child nodes.

Rob
Anup Patel March 18, 2021, 11:02 a.m. | #4
On Tue, Mar 16, 2021 at 9:24 PM Rob Herring <robh@kernel.org> wrote:
>

> On Sun, Mar 7, 2021 at 8:18 PM Anup Patel <anup@brainfault.org> wrote:

> >

> > On Sat, Mar 6, 2021 at 4:52 AM Rob Herring <robh@kernel.org> wrote:

> > >

> > > On Sun, Feb 21, 2021 at 03:07:57PM +0530, Anup Patel wrote:

> > > > The RISC-V CPU idle states will be described in DT under the

> > > > /cpus/riscv-idle-states DT node. This patch adds the bindings

> > > > documentation for riscv-idle-states DT nodes and idle state DT

> > > > nodes under it.

> > > >

> > > > Signed-off-by: Anup Patel <anup.patel@wdc.com>

> > > > ---

> > > >  .../bindings/riscv/idle-states.yaml           | 250 ++++++++++++++++++

> > > >  1 file changed, 250 insertions(+)

> > > >  create mode 100644 Documentation/devicetree/bindings/riscv/idle-states.yaml

> > > >

> > > > diff --git a/Documentation/devicetree/bindings/riscv/idle-states.yaml b/Documentation/devicetree/bindings/riscv/idle-states.yaml

> > > > new file mode 100644

> > > > index 000000000000..3eff763fed23

> > > > --- /dev/null

> > > > +++ b/Documentation/devicetree/bindings/riscv/idle-states.yaml

> > > > @@ -0,0 +1,250 @@

> > > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

> > > > +%YAML 1.2

> > > > +---

> > > > +$id: http://devicetree.org/schemas/riscv/idle-states.yaml#

> > > > +$schema: http://devicetree.org/meta-schemas/core.yaml#

> > > > +

> > > > +title: RISC-V idle states binding description

> > > > +

> > > > +maintainers:

> > > > +  - Anup Patel <anup.patel@wdc.com>

> > > > +

> > > > +description: |+

> > > > +  RISC-V systems can manage power consumption dynamically, where HARTs

> > > > +  (or CPUs) [1] can be put in different platform specific suspend (or

> > > > +  idle) states (ranging from simple WFI, power gating, etc). The RISC-V

> > > > +  SBI [2] hart state management extension provides a standard mechanism

> > > > +  for OSes to request HART state transitions.

> > > > +

> > > > +  The platform specific suspend (or idle) states of a hart can be either

> > > > +  retentive or non-rententive in nature. A retentive suspend state will

> > > > +  preserve hart register and CSR values for all privilege modes whereas

> > > > +  a non-retentive suspend state will not preserve hart register and CSR

> > > > +  values. The suspend (or idle) state entered by executing the WFI

> > > > +  instruction is considered standard on all RISC-V systems and therefore

> > > > +  must not be listed in device tree.

> > > > +

> > > > +  The device tree binding definition for RISC-V idle states described

> > > > +  in this document is quite similar to the ARM idle states [3].

> > > > +

> > > > +  References

> > > > +

> > > > +  [1] RISC-V Linux Kernel documentation - CPUs bindings

> > > > +      Documentation/devicetree/bindings/riscv/cpus.yaml

> > > > +

> > > > +  [2] RISC-V Supervisor Binary Interface (SBI)

> > > > +      http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc

> > > > +

> > > > +  [3] ARM idle states binding description - Idle states bindings

> > > > +      Documentation/devicetree/bindings/arm/idle-states.yaml

> > >

> > > I'd assume there's common parts we can share.

> >

> > Yes, except few properties most are the same.

> >

> > We can have a shared DT bindings for both ARM and RISC-V but

> > both architectures will always have some architecture specific details

> > (or properties) which need to be documented under arch specific

> > DT documentation. Is it okay if this is done as a separate series ?

>

> No...


Okay, I will create a common DT bindings for both ARM and RISC-V
in the next revision.

>

> > > > +

> > > > +properties:

> > > > +  $nodename:

> > > > +    const: riscv-idle-states

> > >

> > > Just 'idle-states' like Arm.

> >

> > I had tried "idle-states" node name but DT bindings check complaints

> > conflict with ARM idle state bindings.

>

> ...and this being one reason why.

>

> Actually, I think this can all be in 1 doc if you want. It's fine with

> me if a common doc has RiscV and Arm specific properties.


Sure, will add common DT bindings.

>

> > > > +

> > > > +patternProperties:

> > > > +  "^(cpu|cluster)-":

> > > > +    type: object

> > > > +    description: |

> > > > +      Each state node represents an idle state description and must be

> > > > +      defined as follows.

> > > > +

> > >

> > >        additionalProperties: false

> >

> > okay, will update.

> >

> > >

> > > > +    properties:

> > > > +      compatible:

> > > > +        const: riscv,idle-state

> > > > +

> > > > +      local-timer-stop:

> > > > +        description:

> > > > +          If present the CPU local timer control logic is lost on state

> > > > +          entry, otherwise it is retained.

> > > > +        type: boolean

> > > > +

> > > > +      entry-latency-us:

> > > > +        description:

> > > > +          Worst case latency in microseconds required to enter the idle state.

> > > > +

> > > > +      exit-latency-us:

> > > > +        description:

> > > > +          Worst case latency in microseconds required to exit the idle state.

> > > > +          The exit-latency-us duration may be guaranteed only after

> > > > +          entry-latency-us has passed.

> > > > +

> > > > +      min-residency-us:

> > > > +        description:

> > > > +          Minimum residency duration in microseconds, inclusive of preparation

> > > > +          and entry, for this idle state to be considered worthwhile energy

> > > > +          wise (refer to section 2 of this document for a complete description).

> > > > +

> > > > +      wakeup-latency-us:

> > > > +        description: |

> > > > +          Maximum delay between the signaling of a wake-up event and the CPU

> > > > +          being able to execute normal code again. If omitted, this is assumed

> > > > +          to be equal to:

> > > > +

> > > > +            entry-latency-us + exit-latency-us

> > > > +

> > > > +          It is important to supply this value on systems where the duration

> > > > +          of PREP phase (see diagram 1, section 2) is non-neglibigle. In such

> > > > +          systems entry-latency-us + exit-latency-us will exceed

> > > > +          wakeup-latency-us by this duration.

> > > > +

> > > > +      idle-state-name:

> > > > +        $ref: /schemas/types.yaml#/definitions/string

> > > > +        description:

> > > > +          A string used as a descriptive name for the idle state.

> > > > +

> > > > +    required:

> > > > +      - compatible

> > > > +      - entry-latency-us

> > > > +      - exit-latency-us

> > > > +      - min-residency-us

> > > > +

> > > > +additionalProperties: false

> >

> > I will move this up.

>

> TBC, you need this at 2 levels. Both the idle-states node and child nodes.


Sure, I will add at both levels.

Regards,
Anup

Patch

diff --git a/Documentation/devicetree/bindings/riscv/idle-states.yaml b/Documentation/devicetree/bindings/riscv/idle-states.yaml
new file mode 100644
index 000000000000..3eff763fed23
--- /dev/null
+++ b/Documentation/devicetree/bindings/riscv/idle-states.yaml
@@ -0,0 +1,250 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/riscv/idle-states.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RISC-V idle states binding description
+
+maintainers:
+  - Anup Patel <anup.patel@wdc.com>
+
+description: |+
+  RISC-V systems can manage power consumption dynamically, where HARTs
+  (or CPUs) [1] can be put in different platform specific suspend (or
+  idle) states (ranging from simple WFI, power gating, etc). The RISC-V
+  SBI [2] hart state management extension provides a standard mechanism
+  for OSes to request HART state transitions.
+
+  The platform specific suspend (or idle) states of a hart can be either
+  retentive or non-rententive in nature. A retentive suspend state will
+  preserve hart register and CSR values for all privilege modes whereas
+  a non-retentive suspend state will not preserve hart register and CSR
+  values. The suspend (or idle) state entered by executing the WFI
+  instruction is considered standard on all RISC-V systems and therefore
+  must not be listed in device tree.
+
+  The device tree binding definition for RISC-V idle states described
+  in this document is quite similar to the ARM idle states [3].
+
+  References
+
+  [1] RISC-V Linux Kernel documentation - CPUs bindings
+      Documentation/devicetree/bindings/riscv/cpus.yaml
+
+  [2] RISC-V Supervisor Binary Interface (SBI)
+      http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc
+
+  [3] ARM idle states binding description - Idle states bindings
+      Documentation/devicetree/bindings/arm/idle-states.yaml
+
+properties:
+  $nodename:
+    const: riscv-idle-states
+
+patternProperties:
+  "^(cpu|cluster)-":
+    type: object
+    description: |
+      Each state node represents an idle state description and must be
+      defined as follows.
+
+    properties:
+      compatible:
+        const: riscv,idle-state
+
+      local-timer-stop:
+        description:
+          If present the CPU local timer control logic is lost on state
+          entry, otherwise it is retained.
+        type: boolean
+
+      entry-latency-us:
+        description:
+          Worst case latency in microseconds required to enter the idle state.
+
+      exit-latency-us:
+        description:
+          Worst case latency in microseconds required to exit the idle state.
+          The exit-latency-us duration may be guaranteed only after
+          entry-latency-us has passed.
+
+      min-residency-us:
+        description:
+          Minimum residency duration in microseconds, inclusive of preparation
+          and entry, for this idle state to be considered worthwhile energy
+          wise (refer to section 2 of this document for a complete description).
+
+      wakeup-latency-us:
+        description: |
+          Maximum delay between the signaling of a wake-up event and the CPU
+          being able to execute normal code again. If omitted, this is assumed
+          to be equal to:
+
+            entry-latency-us + exit-latency-us
+
+          It is important to supply this value on systems where the duration
+          of PREP phase (see diagram 1, section 2) is non-neglibigle. In such
+          systems entry-latency-us + exit-latency-us will exceed
+          wakeup-latency-us by this duration.
+
+      idle-state-name:
+        $ref: /schemas/types.yaml#/definitions/string
+        description:
+          A string used as a descriptive name for the idle state.
+
+    required:
+      - compatible
+      - entry-latency-us
+      - exit-latency-us
+      - min-residency-us
+
+additionalProperties: false
+
+examples:
+  - |
+
+    cpus {
+        #size-cells = <0>;
+        #address-cells = <1>;
+
+        cpu@0 {
+            device_type = "cpu";
+            compatible = "riscv";
+            reg = <0x0>;
+            riscv,isa = "rv64imafdc";
+            mmu-type = "riscv,sv48";
+            cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0
+                            &CLUSTER_RET_0 &CLUSTER_NONRET_0>;
+
+            cpu_intc0: interrupt-controller {
+                #interrupt-cells = <1>;
+                compatible = "riscv,cpu-intc";
+                interrupt-controller;
+            };
+        };
+
+        cpu@1 {
+            device_type = "cpu";
+            compatible = "riscv";
+            reg = <0x1>;
+            riscv,isa = "rv64imafdc";
+            mmu-type = "riscv,sv48";
+            cpu-idle-states = <&CPU_RET_0_0 &CPU_NONRET_0_0
+                            &CLUSTER_RET_0 &CLUSTER_NONRET_0>;
+
+            cpu_intc1: interrupt-controller {
+                #interrupt-cells = <1>;
+                compatible = "riscv,cpu-intc";
+                interrupt-controller;
+            };
+        };
+
+        cpu@10 {
+            device_type = "cpu";
+            compatible = "riscv";
+            reg = <0x10>;
+            riscv,isa = "rv64imafdc";
+            mmu-type = "riscv,sv48";
+            cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0
+                            &CLUSTER_RET_1 &CLUSTER_NONRET_1>;
+
+            cpu_intc10: interrupt-controller {
+                #interrupt-cells = <1>;
+                compatible = "riscv,cpu-intc";
+                interrupt-controller;
+            };
+        };
+
+        cpu@11 {
+            device_type = "cpu";
+            compatible = "riscv";
+            reg = <0x11>;
+            riscv,isa = "rv64imafdc";
+            mmu-type = "riscv,sv48";
+            cpu-idle-states = <&CPU_RET_1_0 &CPU_NONRET_1_0
+                            &CLUSTER_RET_1 &CLUSTER_NONRET_1>;
+
+            cpu_intc11: interrupt-controller {
+                #interrupt-cells = <1>;
+                compatible = "riscv,cpu-intc";
+                interrupt-controller;
+            };
+        };
+
+        riscv-idle-states {
+            CPU_RET_0_0: cpu-retentive-0-0 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x10000000>;
+                entry-latency-us = <20>;
+                exit-latency-us = <40>;
+                min-residency-us = <80>;
+            };
+
+            CPU_NONRET_0_0: cpu-nonretentive-0-0 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x90000000>;
+                entry-latency-us = <250>;
+                exit-latency-us = <500>;
+                min-residency-us = <950>;
+            };
+
+            CLUSTER_RET_0: cluster-retentive-0 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x11000000>;
+                local-timer-stop;
+                entry-latency-us = <50>;
+                exit-latency-us = <100>;
+                min-residency-us = <250>;
+                wakeup-latency-us = <130>;
+            };
+
+            CLUSTER_NONRET_0: cluster-nonretentive-0 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x91000000>;
+                local-timer-stop;
+                entry-latency-us = <600>;
+                exit-latency-us = <1100>;
+                min-residency-us = <2700>;
+                wakeup-latency-us = <1500>;
+            };
+
+            CPU_RET_1_0: cpu-retentive-1-0 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x10000010>;
+                entry-latency-us = <20>;
+                exit-latency-us = <40>;
+                min-residency-us = <80>;
+            };
+
+            CPU_NONRET_1_0: cpu-nonretentive-1-0 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x90000010>;
+                entry-latency-us = <250>;
+                exit-latency-us = <500>;
+                min-residency-us = <950>;
+            };
+
+            CLUSTER_RET_1: cluster-retentive-1 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x11000010>;
+                local-timer-stop;
+                entry-latency-us = <50>;
+                exit-latency-us = <100>;
+                min-residency-us = <250>;
+                wakeup-latency-us = <130>;
+            };
+
+            CLUSTER_NONRET_1: cluster-nonretentive-1 {
+                compatible = "riscv,idle-state";
+                riscv,sbi-suspend-param = <0x91000010>;
+                local-timer-stop;
+                entry-latency-us = <600>;
+                exit-latency-us = <1100>;
+                min-residency-us = <2700>;
+                wakeup-latency-us = <1500>;
+            };
+        };
+    };
+
+...