dt-bindings: thermal: Add yaml bindings for thermal cooling-devices

# 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 actively

   - 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>;

                                    /* Corresponds to 1000MHz in OPP table */

                                    cooling-device = <&CPU0 5 5>;

                            };

                    };

            };

            /* ... */

    };

...