[PATCH v3 0/3] Convert thermal bindings to yaml

[PATCH v3 0/3] Convert thermal bindings to yaml

[Amit Kucheria]

Hi all,

Here is a series splitting up the thermal bindings into 3 separate bindings
in YAML, one each of the sensor, cooling-device and the thermal zones.

A series to remove thermal.txt and change over all references to it will
follow shortly. Another series to fixup problems found by enforcing this
yaml definition across dts files will also follow.

Changes since v2:
- Addressed review comment from Rob
- Added required properties for thermal-zones node
- Added select: true to thermal-cooling-devices.yaml
- Fixed up example to pass dt_binding_check

Changes since v1:
- Addressed review comments from Rob
- Moved the license back to GPLv2, waiting for other authors to give
  permission to relicense to BSD-2-Clause as well
- Fixed up warnings thrown by dt_binding_check

I have to add that the bindings as they exist today, don't really follow
the "describe the hardware" model of devicetree. e.g. the entire
thermal-zone binding is a software abstraction to tie arbitrary,
board-specific trip points to cooling strategies. This doesn't fit well
into the model where the same SoC in two different form-factor devices e.g.
mobile and laptop, will have fairly different thermal profiles and might
benefit from different trip points and mitigation heuristics. I've started
some experiments with moving the thermal zone data to a board-specific
platform data that is used to initialise a "thermal zone driver".

In any case, if we ever move down that path, it'll probably end up being v2
of the binding, so this series is still relevant.

Please help review.

Regards,
Amit

Amit Kucheria (3):
  dt-bindings: thermal: Add yaml bindings for thermal sensors
  dt-bindings: thermal: Add yaml bindings for thermal cooling-devices
  dt-bindings: thermal: Add yaml bindings for thermal zones

 .../thermal/thermal-cooling-devices.yaml      | 116 +++++++
 .../bindings/thermal/thermal-sensor.yaml      |  72 ++++
 .../bindings/thermal/thermal-zones.yaml       | 324 ++++++++++++++++++
 3 files changed, 512 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
 create mode 100644 Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
 create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml

-- 
2.20.1

[PATCH v3 1/3] dt-bindings: thermal: Add yaml bindings for thermal sensors

[Amit Kucheria]

As part of moving the thermal bindings to YAML, split it up into 3
bindings: thermal sensors, cooling devices and thermal zones.

The property #thermal-sensor-cells is required in each device that acts
as a thermal sensor. It is used to uniquely identify the instance of the
thermal sensor inside the system.

Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
---
 .../bindings/thermal/thermal-sensor.yaml      | 72 +++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/thermal/thermal-sensor.yaml

diff --git a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
new file mode 100644
index 000000000000..920ee7667591
--- /dev/null
+++ b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0)
+# Copyright 2020 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/thermal/thermal-sensor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Thermal sensor binding
+
+maintainers:
+  - Amit Kucheria <amitk@kernel.org>
+
+description: |
+  Thermal management is achieved in devicetree by describing the sensor hardware
+  and the software abstraction of thermal zones required to take appropriate
+  action to mitigate thermal overloads.
+
+  The following node types are used to completely describe a thermal management
+  system in devicetree:
+   - thermal-sensor: device that measures temperature, has SoC-specific bindings
+   - cooling-device: device used to dissipate heat either passively or artively
+   - thermal-zones: a container of the following node types used to describe all
+     thermal data for the platform
+
+  This binding describes the thermal-sensor.
+
+  Thermal sensor devices provide temperature sensing capabilities on thermal
+  zones. Typical devices are I2C ADC converters and bandgaps. Thermal sensor
+  devices may control one or more internal sensors.
+
+properties:
+  "#thermal-sensor-cells":
+    description:
+      Used to uniquely identify a thermal sensor instance within an IC. Will be
+      0 on sensor nodes with only a single sensor and at least 1 on nodes
+      containing several internal sensors.
+    enum: [0, 1]
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    // Example 1: SDM845 TSENS
+    soc: soc@0 {
+            #address-cells = <2>;
+            #size-cells = <2>;
+
+            /* ... */
+
+            tsens0: thermal-sensor@c263000 {
+                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
+                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
+                          <0 0x0c222000 0 0x1ff>; /* SROT */
+                    #qcom,sensors = <13>;
+                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
+                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
+                    interrupt-names = "uplow", "critical";
+                    #thermal-sensor-cells = <1>;
+            };
+
+            tsens1: thermal-sensor@c265000 {
+                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
+                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
+                          <0 0x0c223000 0 0x1ff>; /* SROT */
+                    #qcom,sensors = <8>;
+                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
+                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
+                    interrupt-names = "uplow", "critical";
+                    #thermal-sensor-cells = <1>;
+            };
+    };
+...
-- 
2.20.1

[PATCH v3 2/3] dt-bindings: thermal: Add yaml bindings for thermal cooling-devices

[Amit Kucheria]

As part of moving the thermal bindings to YAML, split it up into 3
bindings: thermal sensors, cooling devices and thermal zones.

The property #cooling-cells is required in each device that acts as a
cooling device - whether active or passive. So any device that can
throttle its performance to passively reduce heat dissipation (e.g.
cpus, gpus) and any device that can actively dissipate heat at different
levels (e.g. fans) will contain this property.

Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
---
 .../thermal/thermal-cooling-devices.yaml      | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml

diff --git a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
new file mode 100644
index 000000000000..b5599f7859f8
--- /dev/null
+++ b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: (GPL-2.0)
+# Copyright 2020 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/thermal/thermal-cooling-devices.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Thermal cooling device binding
+
+maintainers:
+  - Amit Kucheria <amitk@kernel.org>
+
+description: |
+  Thermal management is achieved in devicetree by describing the sensor hardware
+  and the software abstraction of cooling devices and thermal zones required to
+  take appropriate action to mitigate thermal overload.
+
+  The following node types are used to completely describe a thermal management
+  system in devicetree:
+   - thermal-sensor: device that measures temperature, has SoC-specific bindings
+   - cooling-device: device used to dissipate heat either passively or artively
+   - thermal-zones: a container of the following node types used to describe all
+     thermal data for the platform
+
+  This binding describes the cooling devices.
+
+  There are essentially two ways to provide control on power dissipation:
+    - Passive cooling: by means of regulating device performance. A typical
+      passive cooling mechanism is a CPU that has dynamic voltage and frequency
+      scaling (DVFS), and uses lower frequencies as cooling states.
+    - Active cooling: by means of activating devices in order to remove the
+      dissipated heat, e.g. regulating fan speeds.
+
+  Any cooling device has a range of cooling states (i.e. different levels of
+  heat dissipation). They also have a way to determine the state of cooling in
+  which the device is. For example, a fan's cooling states correspond to the
+  different fan speeds possible. Cooling states are referred to by single
+  unsigned integers, where larger numbers mean greater heat dissipation. The
+  precise set of cooling states associated with a device should be defined in
+  a particular device's binding.
+
+select: true
+
+properties:
+  "#cooling-cells":
+    description:
+        Must be 2, in order to specify minimum and maximum cooling state used in
+        the cooling-maps reference. The first cell is the minimum cooling state
+        and the second cell is the maximum cooling state requested.
+    const: 2
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+    #include <dt-bindings/thermal/thermal.h>
+
+    // Example 1: Cpufreq cooling device on CPU0
+    cpus {
+            #address-cells = <2>;
+            #size-cells = <0>;
+
+            CPU0: cpu@0 {
+                    device_type = "cpu";
+                    compatible = "qcom,kryo385";
+                    reg = <0x0 0x0>;
+                    enable-method = "psci";
+                    cpu-idle-states = <&LITTLE_CPU_SLEEP_0
+                                       &LITTLE_CPU_SLEEP_1
+                                       &CLUSTER_SLEEP_0>;
+                    capacity-dmips-mhz = <607>;
+                    dynamic-power-coefficient = <100>;
+                    qcom,freq-domain = <&cpufreq_hw 0>;
+                    #cooling-cells = <2>;
+                    next-level-cache = <&L2_0>;
+                    L2_0: l2-cache {
+                            compatible = "cache";
+                            next-level-cache = <&L3_0>;
+                            L3_0: l3-cache {
+                                    compatible = "cache";
+                            };
+                    };
+          };
+
+          /* ... */
+
+    };
+
+    /* ... */
+
+    thermal-zones {
+            cpu0-thermal {
+                    polling-delay-passive = <250>;
+                    polling-delay = <1000>;
+
+                    thermal-sensors = <&tsens0 1>;
+
+                    trips {
+                            cpu0_alert0: trip-point0 {
+                                    temperature = <90000>;
+                                    hysteresis = <2000>;
+                                    type = "passive";
+                            };
+                    };
+
+                    cooling-maps {
+                            map0 {
+                                    trip = <&cpu0_alert0>;
+                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>;
+                            };
+                    };
+            };
+
+            /* ... */
+    };
+...
-- 
2.20.1

[PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Amit Kucheria]

As part of moving the thermal bindings to YAML, split it up into 3
bindings: thermal sensors, cooling devices and thermal zones.

The thermal-zone binding is a software abstraction to capture the
properties of each zone - how often they should be checked, the
temperature thresholds (trips) at which mitigation actions need to be
taken and the level of mitigation needed at those thresholds.

Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
---
Changes since v2:
- Addressed review comment from Rob
- Added required properties for thermal-zones node
- Added select: true to thermal-cooling-devices.yaml
- Fixed up example to pass dt_binding_check

 .../bindings/thermal/thermal-zones.yaml       | 324 ++++++++++++++++++
 1 file changed, 324 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml

diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
new file mode 100644
index 000000000000..5632304dcf62
--- /dev/null
+++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
@@ -0,0 +1,324 @@
+# SPDX-License-Identifier: (GPL-2.0)
+# Copyright 2020 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
+$schema: http://devicetree.org/meta-schemas/base.yaml#
+
+title: Thermal zone binding
+
+maintainers:
+  - Amit Kucheria <amitk@kernel.org>
+
+description: |
+  Thermal management is achieved in devicetree by describing the sensor hardware
+  and the software abstraction of cooling devices and thermal zones required to
+  take appropriate action to mitigate thermal overloads.
+
+  The following node types are used to completely describe a thermal management
+  system in devicetree:
+   - thermal-sensor: device that measures temperature, has SoC-specific bindings
+   - cooling-device: device used to dissipate heat either passively or actively
+   - thermal-zones: a container of the following node types used to describe all
+     thermal data for the platform
+
+  This binding describes the thermal-zones.
+
+  The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
+  (temperature derivative over time) in two situations for a thermal zone:
+    1. when passive cooling is activated (polling-delay-passive)
+    2. when the zone just needs to be monitored (polling-delay) or when
+       active cooling is activated.
+
+  The maximum dT/dt is highly bound to hardware power consumption and
+  dissipation capability. The delays should be chosen to account for said
+  max dT/dt, such that a device does not cross several trip boundaries
+  unexpectedly between polls. Choosing the right polling delays shall avoid
+  having the device in temperature ranges that may damage the silicon structures
+  and reduce silicon lifetime.
+
+properties:
+  $nodename:
+    const: thermal-zones
+    description:
+      A /thermal-zones node is required in order to use the thermal framework to
+      manage input from the various thermal zones in the system in order to
+      mitigate thermal overload conditions. It does not represent a real device
+      in the system, but acts as a container to link thermal sensor devices,
+      platform-data regarding temperature thresholds and the mitigation actions
+      to take when the temperature crosses those thresholds.
+
+patternProperties:
+  "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
+    type: object
+    description:
+      Each thermal zone node contains information about how frequently it
+      must be checked, the sensor responsible for reporting temperature for
+      this zone, one sub-node containing the various trip points for this
+      zone and one sub-node containing all the zone cooling-maps.
+
+    properties:
+      polling-delay:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          The maximum number of milliseconds to wait between polls when
+          checking this thermal zone. Setting this to 0 disables the polling
+          timers setup by the thermal framework and assumes that the thermal
+          sensors in this zone support interrupts.
+
+      polling-delay-passive:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          The maximum number of milliseconds to wait between polls when
+          checking this thermal zone while doing passive cooling. Setting
+          this to 0 disables the polling timers setup by the thermal
+          framework and assumes that the thermal sensors in this zone
+          support interrupts.
+
+      thermal-sensors:
+        $ref: /schemas/types.yaml#/definitions/phandle-array
+        description:
+          A list of thermal sensor phandles and sensor specifiers used to
+          monitor this thermal zone.
+
+      trips:
+        type: object
+        description:
+          This node describes a set of points in the temperature domain at
+          which the thermal framework needs to takes action. The actions to
+          be taken are defined in another node called cooling-maps.
+
+        patternProperties:
+          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
+            type: object
+
+            properties:
+              temperature:
+                $ref: /schemas/types.yaml#/definitions/int32
+                minimum: -273000
+                maximum: 200000
+                description:
+                  An integer expressing the trip temperature in millicelsius.
+
+              hysteresis:
+                $ref: /schemas/types.yaml#/definitions/uint32
+                description:
+                  An unsigned integer expressing the hysteresis delta with
+                  respect to the trip temperature property above, also in
+                  millicelsius.
+
+              type:
+                $ref: /schemas/types.yaml#/definitions/string
+                enum:
+                  - active   # enable active cooling e.g. fans
+                  - passive  # enable passive cooling e.g. throttling cpu
+                  - hot      # send notification to driver
+                  - critical # send notification to driver, trigger shutdown
+                description: |
+                  There are four valid trip types: active, passive, hot,
+                  critical.
+
+                  The critical trip type is used to set the maximum
+                  temperature threshold above which the HW becomes
+                  unstable and underlying firmware might even trigger a
+                  reboot. Hitting the critical threshold triggers a system
+                  shutdown.
+
+                  The hot trip type can be used to send a notification to
+                  the thermal driver (if a .notify callback is registered).
+                  The action to be taken is left to the driver.
+
+                  The passive trip type can be used to slow down HW e.g. run
+                  the CPU, GPU, bus at a lower frequency.
+
+                  The active trip type can be used to control other HW to
+                  help in cooling e.g. fans can be sped up or slowed down
+
+            required:
+              - temperature
+              - hysteresis
+              - type
+            additionalProperties: false
+
+        additionalProperties: false
+
+      cooling-maps:
+        type: object
+        description:
+          This node describes the action to be taken when a thermal zone
+          crosses one of the temperature thresholds described in the trips
+          node. The action takes the form of a mapping relation between a
+          trip and the target cooling device state.
+
+        patternProperties:
+          "^map[-a-zA-Z0-9]*$":
+            type: object
+
+            properties:
+              trip:
+                $ref: /schemas/types.yaml#/definitions/phandle
+                description:
+                  A phandle of a trip point node within this thermal zone.
+
+              cooling-device:
+                $ref: /schemas/types.yaml#/definitions/phandle-array
+                description:
+                  A list of cooling device phandles along with the minimum
+                  and maximum cooling state specifiers for each cooling
+                  device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
+                  cooling-device phandle limit specifier lets the framework
+                  use the minimum and maximum cooling state for that cooling
+                  device automatically.
+
+              contribution:
+                $ref: /schemas/types.yaml#/definitions/uint32
+                minimum: 0
+                maximum: 100
+                description:
+                  The contribution of the cooling devices at the trip
+                  temperature, both referenced in this map, to this thermal
+                  zone as a percentage.
+
+            required:
+              - trip
+              - cooling-device
+            additionalProperties: false
+
+    required:
+      - polling-delay
+      - polling-delay-passive
+      - thermal-sensors
+      - trips
+    additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+    #include <dt-bindings/thermal/thermal.h>
+
+    // Example 1: SDM845 TSENS
+    soc: soc@0 {
+            #address-cells = <2>;
+            #size-cells = <2>;
+
+            /* ... */
+
+            tsens0: thermal-sensor@c263000 {
+                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
+                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
+                          <0 0x0c222000 0 0x1ff>; /* SROT */
+                    #qcom,sensors = <13>;
+                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
+                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
+                    interrupt-names = "uplow", "critical";
+                    #thermal-sensor-cells = <1>;
+            };
+
+            tsens1: thermal-sensor@c265000 {
+                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
+                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
+                          <0 0x0c223000 0 0x1ff>; /* SROT */
+                    #qcom,sensors = <8>;
+                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
+                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
+                    interrupt-names = "uplow", "critical";
+                    #thermal-sensor-cells = <1>;
+            };
+    };
+
+    /* ... */
+
+    thermal-zones {
+            cpu0-thermal {
+                    polling-delay-passive = <250>;
+                    polling-delay = <1000>;
+
+                    thermal-sensors = <&tsens0 1>;
+
+                    trips {
+                            cpu0_alert0: trip-point0 {
+                                    temperature = <90000>;
+                                    hysteresis = <2000>;
+                                    type = "passive";
+                            };
+
+                            cpu0_alert1: trip-point1 {
+                                    temperature = <95000>;
+                                    hysteresis = <2000>;
+                                    type = "passive";
+                            };
+
+                            cpu0_crit: cpu_crit {
+                                    temperature = <110000>;
+                                    hysteresis = <1000>;
+                                    type = "critical";
+                            };
+                    };
+
+                    cooling-maps {
+                            map0 {
+                                    trip = <&cpu0_alert0>;
+                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>,
+                                                     <&CPU1 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>,
+                                                     <&CPU2 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>,
+                                                     <&CPU3 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>;
+                            };
+
+                            map1 {
+                                    trip = <&cpu0_alert1>;
+                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>,
+                                                     <&CPU1 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>,
+                                                     <&CPU2 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>,
+                                                     <&CPU3 THERMAL_NO_LIMIT
+                                                            THERMAL_NO_LIMIT>;
+                            };
+                    };
+            };
+
+            /* ... */
+
+            cluster0-thermal {
+                    polling-delay-passive = <250>;
+                    polling-delay = <1000>;
+
+                    thermal-sensors = <&tsens0 5>;
+
+                    trips {
+                            cluster0_alert0: trip-point0 {
+                                    temperature = <90000>;
+                                    hysteresis = <2000>;
+                                    type = "hot";
+                            };
+                            cluster0_crit: cluster0_crit {
+                                    temperature = <110000>;
+                                    hysteresis = <2000>;
+                                    type = "critical";
+                            };
+                    };
+            };
+
+            /* ... */
+
+            gpu-top-thermal {
+                    polling-delay-passive = <250>;
+                    polling-delay = <1000>;
+
+                    thermal-sensors = <&tsens0 11>;
+
+                    trips {
+                            gpu1_alert0: trip-point0 {
+                                    temperature = <90000>;
+                                    hysteresis = <2000>;
+                                    type = "hot";
+                            };
+                    };
+            };
+    };
+...
-- 
2.20.1

Re: [PATCH v3 2/3] dt-bindings: thermal: Add yaml bindings for thermal cooling-devices

[Lukasz Luba]

Hi Amit,

On 3/25/20 6:34 AM, Amit Kucheria wrote:
> As part of moving the thermal bindings to YAML, split it up into 3
> bindings: thermal sensors, cooling devices and thermal zones.
> 
> The property #cooling-cells is required in each device that acts as a
> cooling device - whether active or passive. So any device that can
> throttle its performance to passively reduce heat dissipation (e.g.
> cpus, gpus) and any device that can actively dissipate heat at different
> levels (e.g. fans) will contain this property.
> 
> Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> ---
>   .../thermal/thermal-cooling-devices.yaml      | 116 ++++++++++++++++++
>   1 file changed, 116 insertions(+)
>   create mode 100644 Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> 
> diff --git a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> new file mode 100644
> index 000000000000..b5599f7859f8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> @@ -0,0 +1,116 @@
> +# SPDX-License-Identifier: (GPL-2.0)
> +# Copyright 2020 Linaro Ltd.
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/thermal/thermal-cooling-devices.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Thermal cooling device binding
> +
> +maintainers:
> +  - Amit Kucheria <amitk@kernel.org>
> +
> +description: |
> +  Thermal management is achieved in devicetree by describing the sensor hardware
> +  and the software abstraction of cooling devices and thermal zones required to
> +  take appropriate action to mitigate thermal overload.
> +
> +  The following node types are used to completely describe a thermal management
> +  system in devicetree:
> +   - thermal-sensor: device that measures temperature, has SoC-specific bindings
> +   - cooling-device: device used to dissipate heat either passively or artively
> +   - thermal-zones: a container of the following node types used to describe all
> +     thermal data for the platform
> +
> +  This binding describes the cooling devices.
> +
> +  There are essentially two ways to provide control on power dissipation:
> +    - Passive cooling: by means of regulating device performance. A typical
> +      passive cooling mechanism is a CPU that has dynamic voltage and frequency
> +      scaling (DVFS), and uses lower frequencies as cooling states.
> +    - Active cooling: by means of activating devices in order to remove the
> +      dissipated heat, e.g. regulating fan speeds.
> +
> +  Any cooling device has a range of cooling states (i.e. different levels of
> +  heat dissipation). They also have a way to determine the state of cooling in
> +  which the device is. For example, a fan's cooling states correspond to the
> +  different fan speeds possible. Cooling states are referred to by single
> +  unsigned integers, where larger numbers mean greater heat dissipation. The
> +  precise set of cooling states associated with a device should be defined in
> +  a particular device's binding.

[snip]

> +
> +    thermal-zones {
> +            cpu0-thermal {
> +                    polling-delay-passive = <250>;
> +                    polling-delay = <1000>;
> +
> +                    thermal-sensors = <&tsens0 1>;
> +
> +                    trips {
> +                            cpu0_alert0: trip-point0 {
> +                                    temperature = <90000>;
> +                                    hysteresis = <2000>;
> +                                    type = "passive";
> +                            };
> +                    };
> +
> +                    cooling-maps {
> +                            map0 {
> +                                    trip = <&cpu0_alert0>;
> +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>;

Maybe add something like this, to better reflect the description:

			trip = <&cpu0_alert0>;
			/* Corresponds to 1000MHz in OPP table */
			cooling-device = <&CPU0 5 5>;

This is less confusing than THERMAL_NO_LIMIT.
			
Regards,
Lukasz

Re: [PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Lukasz Luba]

On 3/25/20 6:34 AM, Amit Kucheria wrote:
> As part of moving the thermal bindings to YAML, split it up into 3
> bindings: thermal sensors, cooling devices and thermal zones.
> 
> The thermal-zone binding is a software abstraction to capture the
> properties of each zone - how often they should be checked, the
> temperature thresholds (trips) at which mitigation actions need to be
> taken and the level of mitigation needed at those thresholds.
> 
> Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> ---
> Changes since v2:
> - Addressed review comment from Rob
> - Added required properties for thermal-zones node
> - Added select: true to thermal-cooling-devices.yaml
> - Fixed up example to pass dt_binding_check
> 
>   .../bindings/thermal/thermal-zones.yaml       | 324 ++++++++++++++++++
>   1 file changed, 324 insertions(+)
>   create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> 
> diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> new file mode 100644
> index 000000000000..5632304dcf62
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> @@ -0,0 +1,324 @@
> +# SPDX-License-Identifier: (GPL-2.0)
> +# Copyright 2020 Linaro Ltd.
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
> +$schema: http://devicetree.org/meta-schemas/base.yaml#
> +
> +title: Thermal zone binding
> +
> +maintainers:
> +  - Amit Kucheria <amitk@kernel.org>
> +
> +description: |
> +  Thermal management is achieved in devicetree by describing the sensor hardware
> +  and the software abstraction of cooling devices and thermal zones required to
> +  take appropriate action to mitigate thermal overloads.
> +
> +  The following node types are used to completely describe a thermal management
> +  system in devicetree:
> +   - thermal-sensor: device that measures temperature, has SoC-specific bindings
> +   - cooling-device: device used to dissipate heat either passively or actively
> +   - thermal-zones: a container of the following node types used to describe all
> +     thermal data for the platform
> +
> +  This binding describes the thermal-zones.
> +
> +  The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
> +  (temperature derivative over time) in two situations for a thermal zone:
> +    1. when passive cooling is activated (polling-delay-passive)
> +    2. when the zone just needs to be monitored (polling-delay) or when
> +       active cooling is activated.
> +
> +  The maximum dT/dt is highly bound to hardware power consumption and
> +  dissipation capability. The delays should be chosen to account for said
> +  max dT/dt, such that a device does not cross several trip boundaries
> +  unexpectedly between polls. Choosing the right polling delays shall avoid
> +  having the device in temperature ranges that may damage the silicon structures
> +  and reduce silicon lifetime.
> +
> +properties:
> +  $nodename:
> +    const: thermal-zones
> +    description:
> +      A /thermal-zones node is required in order to use the thermal framework to
> +      manage input from the various thermal zones in the system in order to
> +      mitigate thermal overload conditions. It does not represent a real device
> +      in the system, but acts as a container to link thermal sensor devices,

I would say 'thermal sensor device', since there is 1-to-1 mapping and
aggregating a few sensors inside one tz is not allowed (or I missed
some patches queuing).

> +      platform-data regarding temperature thresholds and the mitigation actions
> +      to take when the temperature crosses those thresholds.
> +
> +patternProperties:
> +  "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
> +    type: object
> +    description:
> +      Each thermal zone node contains information about how frequently it
> +      must be checked, the sensor responsible for reporting temperature for
> +      this zone, one sub-node containing the various trip points for this
> +      zone and one sub-node containing all the zone cooling-maps.
> +
> +    properties:
> +      polling-delay:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          The maximum number of milliseconds to wait between polls when
> +          checking this thermal zone. Setting this to 0 disables the polling
> +          timers setup by the thermal framework and assumes that the thermal
> +          sensors in this zone support interrupts.
> +
> +      polling-delay-passive:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          The maximum number of milliseconds to wait between polls when
> +          checking this thermal zone while doing passive cooling. Setting
> +          this to 0 disables the polling timers setup by the thermal
> +          framework and assumes that the thermal sensors in this zone
> +          support interrupts.
> +
> +      thermal-sensors:
> +        $ref: /schemas/types.yaml#/definitions/phandle-array
> +        description:
> +          A list of thermal sensor phandles and sensor specifiers used to
> +          monitor this thermal zone.

I don't know why it's not consistent with the actual code in
of-thermal.c, where there is even a comment stated:
/* For now, thermal framework supports only 1 sensor per zone */

I think this is the place where developers should be informed about
the limitation and not even try to put more sensors into the list.

> +
> +      trips:
> +        type: object
> +        description:
> +          This node describes a set of points in the temperature domain at
> +          which the thermal framework needs to takes action. The actions to

s/needs to takes/needs to take/

> +          be taken are defined in another node called cooling-maps.
> +
> +        patternProperties:
> +          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
> +            type: object
> +
> +            properties:
> +              temperature:
> +                $ref: /schemas/types.yaml#/definitions/int32
> +                minimum: -273000
> +                maximum: 200000
> +                description:
> +                  An integer expressing the trip temperature in millicelsius.
> +
> +              hysteresis:
> +                $ref: /schemas/types.yaml#/definitions/uint32
> +                description:
> +                  An unsigned integer expressing the hysteresis delta with
> +                  respect to the trip temperature property above, also in
> +                  millicelsius.

This property is worth a bit longer description.

> +
> +              type:
> +                $ref: /schemas/types.yaml#/definitions/string
> +                enum:
> +                  - active   # enable active cooling e.g. fans
> +                  - passive  # enable passive cooling e.g. throttling cpu
> +                  - hot      # send notification to driver
> +                  - critical # send notification to driver, trigger shutdown
> +                description: |
> +                  There are four valid trip types: active, passive, hot,
> +                  critical.

[snip]

> +
> +    thermal-zones {
> +            cpu0-thermal {
> +                    polling-delay-passive = <250>;
> +                    polling-delay = <1000>;
> +
> +                    thermal-sensors = <&tsens0 1>;
> +
> +                    trips {
> +                            cpu0_alert0: trip-point0 {
> +                                    temperature = <90000>;
> +                                    hysteresis = <2000>;
> +                                    type = "passive";
> +                            };
> +
> +                            cpu0_alert1: trip-point1 {
> +                                    temperature = <95000>;
> +                                    hysteresis = <2000>;
> +                                    type = "passive";
> +                            };
> +
> +                            cpu0_crit: cpu_crit {
> +                                    temperature = <110000>;
> +                                    hysteresis = <1000>;
> +                                    type = "critical";
> +                            };
> +                    };
> +
> +                    cooling-maps {
> +                            map0 {
> +                                    trip = <&cpu0_alert0>;
> +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>,
> +                                                     <&CPU1 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>,
> +                                                     <&CPU2 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>,
> +                                                     <&CPU3 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>;
> +                            };
> +
> +                            map1 {
> +                                    trip = <&cpu0_alert1>;
> +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>,
> +                                                     <&CPU1 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>,
> +                                                     <&CPU2 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>,
> +                                                     <&CPU3 THERMAL_NO_LIMIT
> +                                                            THERMAL_NO_LIMIT>;

 From this two examples of handling cpu0_alert0 and cpu0_alert1 you
cannot conclude anything (if you don't understand thermal framework (and
probably IPA). As a simple example it would be better to put a comment
with a description and limit min, max to a specific OPP:

map0 {
     trip = <&cpu0_alert0>;
     /* Corresponds to 1400MHz in OPP table */
     cooling-device = <&CPU0 3 3>, <&CPU1 3 3>, <&CPU2 3 3>, <&CPU3 3 3>;
};

map1 {
     trip = <&cpu0_alert1>;
     /* Corresponds to 1000MHz in OPP table */
     cooling-device = <&CPU0 5 5>, <&CPU1 5 5>, <&CPU2 5 5>, <&CPU3 5 5>;
};

IMHO this kind of example would tell more to an avg driver developer.

Regards,
Lukasz

Re: [PATCH v3 2/3] dt-bindings: thermal: Add yaml bindings for thermal cooling-devices

[Amit Kucheria]

On Wed, Mar 25, 2020 at 3:51 PM Lukasz Luba <lukasz.luba@arm.com> wrote:
>
> Hi Amit,
>
> On 3/25/20 6:34 AM, Amit Kucheria wrote:
> > As part of moving the thermal bindings to YAML, split it up into 3
> > bindings: thermal sensors, cooling devices and thermal zones.
> >
> > The property #cooling-cells is required in each device that acts as a
> > cooling device - whether active or passive. So any device that can
> > throttle its performance to passively reduce heat dissipation (e.g.
> > cpus, gpus) and any device that can actively dissipate heat at different
> > levels (e.g. fans) will contain this property.
> >
> > Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> > ---
> >   .../thermal/thermal-cooling-devices.yaml      | 116 ++++++++++++++++++
> >   1 file changed, 116 insertions(+)
> >   create mode 100644 Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> > new file mode 100644
> > index 000000000000..b5599f7859f8
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> > @@ -0,0 +1,116 @@
> > +# SPDX-License-Identifier: (GPL-2.0)
> > +# Copyright 2020 Linaro Ltd.
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/thermal/thermal-cooling-devices.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Thermal cooling device binding
> > +
> > +maintainers:
> > +  - Amit Kucheria <amitk@kernel.org>
> > +
> > +description: |
> > +  Thermal management is achieved in devicetree by describing the sensor hardware
> > +  and the software abstraction of cooling devices and thermal zones required to
> > +  take appropriate action to mitigate thermal overload.
> > +
> > +  The following node types are used to completely describe a thermal management
> > +  system in devicetree:
> > +   - thermal-sensor: device that measures temperature, has SoC-specific bindings
> > +   - cooling-device: device used to dissipate heat either passively or artively
> > +   - thermal-zones: a container of the following node types used to describe all
> > +     thermal data for the platform
> > +
> > +  This binding describes the cooling devices.
> > +
> > +  There are essentially two ways to provide control on power dissipation:
> > +    - Passive cooling: by means of regulating device performance. A typical
> > +      passive cooling mechanism is a CPU that has dynamic voltage and frequency
> > +      scaling (DVFS), and uses lower frequencies as cooling states.
> > +    - Active cooling: by means of activating devices in order to remove the
> > +      dissipated heat, e.g. regulating fan speeds.
> > +
> > +  Any cooling device has a range of cooling states (i.e. different levels of
> > +  heat dissipation). They also have a way to determine the state of cooling in
> > +  which the device is. For example, a fan's cooling states correspond to the
> > +  different fan speeds possible. Cooling states are referred to by single
> > +  unsigned integers, where larger numbers mean greater heat dissipation. The
> > +  precise set of cooling states associated with a device should be defined in
> > +  a particular device's binding.
>
> [snip]
>
> > +
> > +    thermal-zones {
> > +            cpu0-thermal {
> > +                    polling-delay-passive = <250>;
> > +                    polling-delay = <1000>;
> > +
> > +                    thermal-sensors = <&tsens0 1>;
> > +
> > +                    trips {
> > +                            cpu0_alert0: trip-point0 {
> > +                                    temperature = <90000>;
> > +                                    hysteresis = <2000>;
> > +                                    type = "passive";
> > +                            };
> > +                    };
> > +
> > +                    cooling-maps {
> > +                            map0 {
> > +                                    trip = <&cpu0_alert0>;
> > +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>;
>
> Maybe add something like this, to better reflect the description:
>
>                         trip = <&cpu0_alert0>;
>                         /* Corresponds to 1000MHz in OPP table */
>                         cooling-device = <&CPU0 5 5>;
>
> This is less confusing than THERMAL_NO_LIMIT.

Thanks for the review.

Will fix.

Re: [PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Amit Kucheria]

On Wed, Mar 25, 2020 at 4:36 PM Lukasz Luba <lukasz.luba@arm.com> wrote:
>
>
>
> On 3/25/20 6:34 AM, Amit Kucheria wrote:
> > As part of moving the thermal bindings to YAML, split it up into 3
> > bindings: thermal sensors, cooling devices and thermal zones.
> >
> > The thermal-zone binding is a software abstraction to capture the
> > properties of each zone - how often they should be checked, the
> > temperature thresholds (trips) at which mitigation actions need to be
> > taken and the level of mitigation needed at those thresholds.
> >
> > Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> > ---
> > Changes since v2:
> > - Addressed review comment from Rob
> > - Added required properties for thermal-zones node
> > - Added select: true to thermal-cooling-devices.yaml
> > - Fixed up example to pass dt_binding_check
> >
> >   .../bindings/thermal/thermal-zones.yaml       | 324 ++++++++++++++++++
> >   1 file changed, 324 insertions(+)
> >   create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> > new file mode 100644
> > index 000000000000..5632304dcf62
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> > @@ -0,0 +1,324 @@
> > +# SPDX-License-Identifier: (GPL-2.0)
> > +# Copyright 2020 Linaro Ltd.
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
> > +$schema: http://devicetree.org/meta-schemas/base.yaml#
> > +
> > +title: Thermal zone binding
> > +
> > +maintainers:
> > +  - Amit Kucheria <amitk@kernel.org>
> > +
> > +description: |
> > +  Thermal management is achieved in devicetree by describing the sensor hardware
> > +  and the software abstraction of cooling devices and thermal zones required to
> > +  take appropriate action to mitigate thermal overloads.
> > +
> > +  The following node types are used to completely describe a thermal management
> > +  system in devicetree:
> > +   - thermal-sensor: device that measures temperature, has SoC-specific bindings
> > +   - cooling-device: device used to dissipate heat either passively or actively
> > +   - thermal-zones: a container of the following node types used to describe all
> > +     thermal data for the platform
> > +
> > +  This binding describes the thermal-zones.
> > +
> > +  The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
> > +  (temperature derivative over time) in two situations for a thermal zone:
> > +    1. when passive cooling is activated (polling-delay-passive)
> > +    2. when the zone just needs to be monitored (polling-delay) or when
> > +       active cooling is activated.
> > +
> > +  The maximum dT/dt is highly bound to hardware power consumption and
> > +  dissipation capability. The delays should be chosen to account for said
> > +  max dT/dt, such that a device does not cross several trip boundaries
> > +  unexpectedly between polls. Choosing the right polling delays shall avoid
> > +  having the device in temperature ranges that may damage the silicon structures
> > +  and reduce silicon lifetime.
> > +
> > +properties:
> > +  $nodename:
> > +    const: thermal-zones
> > +    description:
> > +      A /thermal-zones node is required in order to use the thermal framework to
> > +      manage input from the various thermal zones in the system in order to
> > +      mitigate thermal overload conditions. It does not represent a real device
> > +      in the system, but acts as a container to link thermal sensor devices,
>
> I would say 'thermal sensor device', since there is 1-to-1 mapping and
> aggregating a few sensors inside one tz is not allowed (or I missed
> some patches queuing).

See below.

>
> > +      platform-data regarding temperature thresholds and the mitigation actions
> > +      to take when the temperature crosses those thresholds.
> > +
> > +patternProperties:
> > +  "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
> > +    type: object
> > +    description:
> > +      Each thermal zone node contains information about how frequently it
> > +      must be checked, the sensor responsible for reporting temperature for
> > +      this zone, one sub-node containing the various trip points for this
> > +      zone and one sub-node containing all the zone cooling-maps.
> > +
> > +    properties:
> > +      polling-delay:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          The maximum number of milliseconds to wait between polls when
> > +          checking this thermal zone. Setting this to 0 disables the polling
> > +          timers setup by the thermal framework and assumes that the thermal
> > +          sensors in this zone support interrupts.
> > +
> > +      polling-delay-passive:
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description:
> > +          The maximum number of milliseconds to wait between polls when
> > +          checking this thermal zone while doing passive cooling. Setting
> > +          this to 0 disables the polling timers setup by the thermal
> > +          framework and assumes that the thermal sensors in this zone
> > +          support interrupts.
> > +
> > +      thermal-sensors:
> > +        $ref: /schemas/types.yaml#/definitions/phandle-array
> > +        description:
> > +          A list of thermal sensor phandles and sensor specifiers used to
> > +          monitor this thermal zone.
>
> I don't know why it's not consistent with the actual code in
> of-thermal.c, where there is even a comment stated:
> /* For now, thermal framework supports only 1 sensor per zone */
>
> I think this is the place where developers should be informed about
> the limitation and not even try to put more sensors into the list.

That is a good point. I'm currently "porting" the existing binding as
described in thermal.txt to yaml. If you look at some of the example
(c) in there, the bindings allow many sensors to a zone mapping but
the thermal core doesn't implement that functionality.

So should we fix the core code or change the bindings? Thoughts - Rob,
Daniel, Rui?

> > +
> > +      trips:
> > +        type: object
> > +        description:
> > +          This node describes a set of points in the temperature domain at
> > +          which the thermal framework needs to takes action. The actions to
>
> s/needs to takes/needs to take/

Will fix.

> > +          be taken are defined in another node called cooling-maps.
> > +
> > +        patternProperties:
> > +          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
> > +            type: object
> > +
> > +            properties:
> > +              temperature:
> > +                $ref: /schemas/types.yaml#/definitions/int32
> > +                minimum: -273000
> > +                maximum: 200000
> > +                description:
> > +                  An integer expressing the trip temperature in millicelsius.
> > +
> > +              hysteresis:
> > +                $ref: /schemas/types.yaml#/definitions/uint32
> > +                description:
> > +                  An unsigned integer expressing the hysteresis delta with
> > +                  respect to the trip temperature property above, also in
> > +                  millicelsius.
>
> This property is worth a bit longer description.

Will improve the description.

> > +
> > +              type:
> > +                $ref: /schemas/types.yaml#/definitions/string
> > +                enum:
> > +                  - active   # enable active cooling e.g. fans
> > +                  - passive  # enable passive cooling e.g. throttling cpu
> > +                  - hot      # send notification to driver
> > +                  - critical # send notification to driver, trigger shutdown
> > +                description: |
> > +                  There are four valid trip types: active, passive, hot,
> > +                  critical.
>
> [snip]
>
> > +
> > +    thermal-zones {
> > +            cpu0-thermal {
> > +                    polling-delay-passive = <250>;
> > +                    polling-delay = <1000>;
> > +
> > +                    thermal-sensors = <&tsens0 1>;
> > +
> > +                    trips {
> > +                            cpu0_alert0: trip-point0 {
> > +                                    temperature = <90000>;
> > +                                    hysteresis = <2000>;
> > +                                    type = "passive";
> > +                            };
> > +
> > +                            cpu0_alert1: trip-point1 {
> > +                                    temperature = <95000>;
> > +                                    hysteresis = <2000>;
> > +                                    type = "passive";
> > +                            };
> > +
> > +                            cpu0_crit: cpu_crit {
> > +                                    temperature = <110000>;
> > +                                    hysteresis = <1000>;
> > +                                    type = "critical";
> > +                            };
> > +                    };
> > +
> > +                    cooling-maps {
> > +                            map0 {
> > +                                    trip = <&cpu0_alert0>;
> > +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>,
> > +                                                     <&CPU1 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>,
> > +                                                     <&CPU2 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>,
> > +                                                     <&CPU3 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>;
> > +                            };
> > +
> > +                            map1 {
> > +                                    trip = <&cpu0_alert1>;
> > +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>,
> > +                                                     <&CPU1 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>,
> > +                                                     <&CPU2 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>,
> > +                                                     <&CPU3 THERMAL_NO_LIMIT
> > +                                                            THERMAL_NO_LIMIT>;
>
>  From this two examples of handling cpu0_alert0 and cpu0_alert1 you
> cannot conclude anything (if you don't understand thermal framework (and
> probably IPA). As a simple example it would be better to put a comment
> with a description and limit min, max to a specific OPP:
>
> map0 {
>      trip = <&cpu0_alert0>;
>      /* Corresponds to 1400MHz in OPP table */
>      cooling-device = <&CPU0 3 3>, <&CPU1 3 3>, <&CPU2 3 3>, <&CPU3 3 3>;
> };
>
> map1 {
>      trip = <&cpu0_alert1>;
>      /* Corresponds to 1000MHz in OPP table */
>      cooling-device = <&CPU0 5 5>, <&CPU1 5 5>, <&CPU2 5 5>, <&CPU3 5 5>;
> };
>
> IMHO this kind of example would tell more to an avg driver developer.

Will fix.

Thanks for the review.

Regards,
Amit

Re: [PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Amit Kucheria]

On Wed, Mar 25, 2020 at 9:12 PM Amit Kucheria <amit.kucheria@linaro.org> wrote:
>
> On Wed, Mar 25, 2020 at 4:36 PM Lukasz Luba <lukasz.luba@arm.com> wrote:
> >
> >
> >
> > On 3/25/20 6:34 AM, Amit Kucheria wrote:
> > > As part of moving the thermal bindings to YAML, split it up into 3
> > > bindings: thermal sensors, cooling devices and thermal zones.
> > >
> > > The thermal-zone binding is a software abstraction to capture the
> > > properties of each zone - how often they should be checked, the
> > > temperature thresholds (trips) at which mitigation actions need to be
> > > taken and the level of mitigation needed at those thresholds.
> > >
> > > Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> > > ---
> > > Changes since v2:
> > > - Addressed review comment from Rob
> > > - Added required properties for thermal-zones node
> > > - Added select: true to thermal-cooling-devices.yaml
> > > - Fixed up example to pass dt_binding_check
> > >
> > >   .../bindings/thermal/thermal-zones.yaml       | 324 ++++++++++++++++++
> > >   1 file changed, 324 insertions(+)
> > >   create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> > > new file mode 100644
> > > index 000000000000..5632304dcf62
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> > > @@ -0,0 +1,324 @@
> > > +# SPDX-License-Identifier: (GPL-2.0)
> > > +# Copyright 2020 Linaro Ltd.
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/base.yaml#
> > > +
> > > +title: Thermal zone binding
> > > +
> > > +maintainers:
> > > +  - Amit Kucheria <amitk@kernel.org>
> > > +
> > > +description: |
> > > +  Thermal management is achieved in devicetree by describing the sensor hardware
> > > +  and the software abstraction of cooling devices and thermal zones required to
> > > +  take appropriate action to mitigate thermal overloads.
> > > +
> > > +  The following node types are used to completely describe a thermal management
> > > +  system in devicetree:
> > > +   - thermal-sensor: device that measures temperature, has SoC-specific bindings
> > > +   - cooling-device: device used to dissipate heat either passively or actively
> > > +   - thermal-zones: a container of the following node types used to describe all
> > > +     thermal data for the platform
> > > +
> > > +  This binding describes the thermal-zones.
> > > +
> > > +  The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
> > > +  (temperature derivative over time) in two situations for a thermal zone:
> > > +    1. when passive cooling is activated (polling-delay-passive)
> > > +    2. when the zone just needs to be monitored (polling-delay) or when
> > > +       active cooling is activated.
> > > +
> > > +  The maximum dT/dt is highly bound to hardware power consumption and
> > > +  dissipation capability. The delays should be chosen to account for said
> > > +  max dT/dt, such that a device does not cross several trip boundaries
> > > +  unexpectedly between polls. Choosing the right polling delays shall avoid
> > > +  having the device in temperature ranges that may damage the silicon structures
> > > +  and reduce silicon lifetime.
> > > +
> > > +properties:
> > > +  $nodename:
> > > +    const: thermal-zones
> > > +    description:
> > > +      A /thermal-zones node is required in order to use the thermal framework to
> > > +      manage input from the various thermal zones in the system in order to
> > > +      mitigate thermal overload conditions. It does not represent a real device
> > > +      in the system, but acts as a container to link thermal sensor devices,
> >
> > I would say 'thermal sensor device', since there is 1-to-1 mapping and
> > aggregating a few sensors inside one tz is not allowed (or I missed
> > some patches queuing).
>
> See below.
>
> >
> > > +      platform-data regarding temperature thresholds and the mitigation actions
> > > +      to take when the temperature crosses those thresholds.
> > > +
> > > +patternProperties:
> > > +  "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
> > > +    type: object
> > > +    description:
> > > +      Each thermal zone node contains information about how frequently it
> > > +      must be checked, the sensor responsible for reporting temperature for
> > > +      this zone, one sub-node containing the various trip points for this
> > > +      zone and one sub-node containing all the zone cooling-maps.
> > > +
> > > +    properties:
> > > +      polling-delay:
> > > +        $ref: /schemas/types.yaml#/definitions/uint32
> > > +        description:
> > > +          The maximum number of milliseconds to wait between polls when
> > > +          checking this thermal zone. Setting this to 0 disables the polling
> > > +          timers setup by the thermal framework and assumes that the thermal
> > > +          sensors in this zone support interrupts.
> > > +
> > > +      polling-delay-passive:
> > > +        $ref: /schemas/types.yaml#/definitions/uint32
> > > +        description:
> > > +          The maximum number of milliseconds to wait between polls when
> > > +          checking this thermal zone while doing passive cooling. Setting
> > > +          this to 0 disables the polling timers setup by the thermal
> > > +          framework and assumes that the thermal sensors in this zone
> > > +          support interrupts.
> > > +
> > > +      thermal-sensors:
> > > +        $ref: /schemas/types.yaml#/definitions/phandle-array
> > > +        description:
> > > +          A list of thermal sensor phandles and sensor specifiers used to
> > > +          monitor this thermal zone.
> >
> > I don't know why it's not consistent with the actual code in
> > of-thermal.c, where there is even a comment stated:
> > /* For now, thermal framework supports only 1 sensor per zone */
> >
> > I think this is the place where developers should be informed about
> > the limitation and not even try to put more sensors into the list.
>
> That is a good point. I'm currently "porting" the existing binding as
> described in thermal.txt to yaml. If you look at some of the example
> (c) in there, the bindings allow many sensors to a zone mapping but
> the thermal core doesn't implement that functionality.
>
> So should we fix the core code or change the bindings? Thoughts - Rob,
> Daniel, Rui?

Rob, Daniel: Any comments? We don't have any concerns for Linux
backward compatibility since multiple sensors per zone isn't used
anywhere. But asking since bindings are supposed to be OS-agnostic.

> > > +
> > > +      trips:
> > > +        type: object
> > > +        description:
> > > +          This node describes a set of points in the temperature domain at
> > > +          which the thermal framework needs to takes action. The actions to
> >
> > s/needs to takes/needs to take/
>
> Will fix.
>
> > > +          be taken are defined in another node called cooling-maps.
> > > +
> > > +        patternProperties:
> > > +          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
> > > +            type: object
> > > +
> > > +            properties:
> > > +              temperature:
> > > +                $ref: /schemas/types.yaml#/definitions/int32
> > > +                minimum: -273000
> > > +                maximum: 200000
> > > +                description:
> > > +                  An integer expressing the trip temperature in millicelsius.
> > > +
> > > +              hysteresis:
> > > +                $ref: /schemas/types.yaml#/definitions/uint32
> > > +                description:
> > > +                  An unsigned integer expressing the hysteresis delta with
> > > +                  respect to the trip temperature property above, also in
> > > +                  millicelsius.
> >
> > This property is worth a bit longer description.
>
> Will improve the description.
>
> > > +
> > > +              type:
> > > +                $ref: /schemas/types.yaml#/definitions/string
> > > +                enum:
> > > +                  - active   # enable active cooling e.g. fans
> > > +                  - passive  # enable passive cooling e.g. throttling cpu
> > > +                  - hot      # send notification to driver
> > > +                  - critical # send notification to driver, trigger shutdown
> > > +                description: |
> > > +                  There are four valid trip types: active, passive, hot,
> > > +                  critical.
> >
> > [snip]
> >
> > > +
> > > +    thermal-zones {
> > > +            cpu0-thermal {
> > > +                    polling-delay-passive = <250>;
> > > +                    polling-delay = <1000>;
> > > +
> > > +                    thermal-sensors = <&tsens0 1>;
> > > +
> > > +                    trips {
> > > +                            cpu0_alert0: trip-point0 {
> > > +                                    temperature = <90000>;
> > > +                                    hysteresis = <2000>;
> > > +                                    type = "passive";
> > > +                            };
> > > +
> > > +                            cpu0_alert1: trip-point1 {
> > > +                                    temperature = <95000>;
> > > +                                    hysteresis = <2000>;
> > > +                                    type = "passive";
> > > +                            };
> > > +
> > > +                            cpu0_crit: cpu_crit {
> > > +                                    temperature = <110000>;
> > > +                                    hysteresis = <1000>;
> > > +                                    type = "critical";
> > > +                            };
> > > +                    };
> > > +
> > > +                    cooling-maps {
> > > +                            map0 {
> > > +                                    trip = <&cpu0_alert0>;
> > > +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>,
> > > +                                                     <&CPU1 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>,
> > > +                                                     <&CPU2 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>,
> > > +                                                     <&CPU3 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>;
> > > +                            };
> > > +
> > > +                            map1 {
> > > +                                    trip = <&cpu0_alert1>;
> > > +                                    cooling-device = <&CPU0 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>,
> > > +                                                     <&CPU1 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>,
> > > +                                                     <&CPU2 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>,
> > > +                                                     <&CPU3 THERMAL_NO_LIMIT
> > > +                                                            THERMAL_NO_LIMIT>;
> >
> >  From this two examples of handling cpu0_alert0 and cpu0_alert1 you
> > cannot conclude anything (if you don't understand thermal framework (and
> > probably IPA). As a simple example it would be better to put a comment
> > with a description and limit min, max to a specific OPP:
> >
> > map0 {
> >      trip = <&cpu0_alert0>;
> >      /* Corresponds to 1400MHz in OPP table */
> >      cooling-device = <&CPU0 3 3>, <&CPU1 3 3>, <&CPU2 3 3>, <&CPU3 3 3>;
> > };
> >
> > map1 {
> >      trip = <&cpu0_alert1>;
> >      /* Corresponds to 1000MHz in OPP table */
> >      cooling-device = <&CPU0 5 5>, <&CPU1 5 5>, <&CPU2 5 5>, <&CPU3 5 5>;
> > };
> >
> > IMHO this kind of example would tell more to an avg driver developer.
>
> Will fix.
>
> Thanks for the review.
>
> Regards,
> Amit

Re: [PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Daniel Lezcano]

Hi Amit,

On 30/03/2020 12:34, Amit Kucheria wrote:

[ ... ]

>>> I don't know why it's not consistent with the actual code in
>>> of-thermal.c, where there is even a comment stated: /* For now,
>>> thermal framework supports only 1 sensor per zone */
>>>
>>> I think this is the place where developers should be informed
>>> about the limitation and not even try to put more sensors into
>>> the list.
>>
>> That is a good point. I'm currently "porting" the existing
>> binding as described in thermal.txt to yaml. If you look at some
>> of the example (c) in there, the bindings allow many sensors to a
>> zone mapping but the thermal core doesn't implement that
>> functionality.
>>
>> So should we fix the core code or change the bindings? Thoughts -
>> Rob, Daniel, Rui?
>
> Rob, Daniel: Any comments? We don't have any concerns for Linux
> backward compatibility since multiple sensors per zone isn't used
> anywhere. But asking since bindings are supposed to be
> OS-agnostic.

IMO, we should remove it as it is not used anywhere.

We still have to decide how we aggregate multiple sensors.


-- 
<http://www.linaro.org/> Linaro.org │ Open source software for ARM SoCs

Follow Linaro:  <http://www.facebook.com/pages/Linaro> Facebook |
<http://twitter.com/#!/linaroorg> Twitter |
<http://www.linaro.org/linaro-blog/> Blog

Re: [PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Rob Herring]

On Mon, Mar 30, 2020 at 03:07:53PM +0200, Daniel Lezcano wrote:
> 
> Hi Amit,
> 
> On 30/03/2020 12:34, Amit Kucheria wrote:
> 
> [ ... ]
> 
> >>> I don't know why it's not consistent with the actual code in
> >>> of-thermal.c, where there is even a comment stated: /* For now,
> >>> thermal framework supports only 1 sensor per zone */
> >>>
> >>> I think this is the place where developers should be informed
> >>> about the limitation and not even try to put more sensors into
> >>> the list.
> >>
> >> That is a good point. I'm currently "porting" the existing
> >> binding as described in thermal.txt to yaml. If you look at some
> >> of the example (c) in there, the bindings allow many sensors to a
> >> zone mapping but the thermal core doesn't implement that
> >> functionality.
> >>
> >> So should we fix the core code or change the bindings? Thoughts -
> >> Rob, Daniel, Rui?
> >
> > Rob, Daniel: Any comments? We don't have any concerns for Linux
> > backward compatibility since multiple sensors per zone isn't used
> > anywhere. But asking since bindings are supposed to be
> > OS-agnostic.
> 
> IMO, we should remove it as it is not used anywhere.
> 
> We still have to decide how we aggregate multiple sensors.

The schema only needs to pass what currently exists (assuming no 
errors), so extending it later is fine with me.

Rob

Re: [PATCH v3 1/3] dt-bindings: thermal: Add yaml bindings for thermal sensors

[Rob Herring]

On Wed, 25 Mar 2020 12:04:52 +0530, Amit Kucheria wrote:
> As part of moving the thermal bindings to YAML, split it up into 3
> bindings: thermal sensors, cooling devices and thermal zones.
> 
> The property #thermal-sensor-cells is required in each device that acts
> as a thermal sensor. It is used to uniquely identify the instance of the
> thermal sensor inside the system.
> 
> Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> ---
>  .../bindings/thermal/thermal-sensor.yaml      | 72 +++++++++++++++++++
>  1 file changed, 72 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/thermal/thermal-sensor.yaml
> 

Reviewed-by: Rob Herring <robh@kernel.org>

Re: [PATCH v3 2/3] dt-bindings: thermal: Add yaml bindings for thermal cooling-devices

[Rob Herring]

On Wed, 25 Mar 2020 12:04:53 +0530, Amit Kucheria wrote:
> As part of moving the thermal bindings to YAML, split it up into 3
> bindings: thermal sensors, cooling devices and thermal zones.
> 
> The property #cooling-cells is required in each device that acts as a
> cooling device - whether active or passive. So any device that can
> throttle its performance to passively reduce heat dissipation (e.g.
> cpus, gpus) and any device that can actively dissipate heat at different
> levels (e.g. fans) will contain this property.
> 
> Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> ---
>  .../thermal/thermal-cooling-devices.yaml      | 116 ++++++++++++++++++
>  1 file changed, 116 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
> 

Reviewed-by: Rob Herring <robh@kernel.org>

Re: [PATCH v3 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones

[Rob Herring]

On Wed, 25 Mar 2020 12:04:54 +0530, Amit Kucheria wrote:
> As part of moving the thermal bindings to YAML, split it up into 3
> bindings: thermal sensors, cooling devices and thermal zones.
> 
> The thermal-zone binding is a software abstraction to capture the
> properties of each zone - how often they should be checked, the
> temperature thresholds (trips) at which mitigation actions need to be
> taken and the level of mitigation needed at those thresholds.
> 
> Signed-off-by: Amit Kucheria <amit.kucheria@linaro.org>
> ---
> Changes since v2:
> - Addressed review comment from Rob
> - Added required properties for thermal-zones node
> - Added select: true to thermal-cooling-devices.yaml
> - Fixed up example to pass dt_binding_check
> 
>  .../bindings/thermal/thermal-zones.yaml       | 324 ++++++++++++++++++
>  1 file changed, 324 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml
> 

The change discussed doesn't affect the schema other than adding a 
'maxItems: 1', so:

Reviewed-by: Rob Herring <robh@kernel.org>