bindings/thermal/nvidia,tegra124-soctherm.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/thermal/nvidia,tegra124-soctherm.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: NVIDIA Tegra124 SOCTHERM Thermal Management System
   8
   9 maintainers:
  10   - Thierry Reding <thierry.reding@gmail.com>
  11   - Jon Hunter <jonathanh@nvidia.com>
  12
  13 description: The SOCTHERM IP block contains thermal sensors, support for
  14   polled or interrupt-based thermal monitoring, CPU and GPU throttling based
  15   on temperature trip points, and handling external overcurrent notifications.
  16   It is also used to manage emergency shutdown in an overheating situation.
  17
  18 properties:
  19   compatible:
  20     enum:
  21       - nvidia,tegra124-soctherm
  22       - nvidia,tegra132-soctherm
  23       - nvidia,tegra210-soctherm
  24
  25   reg:
  26     maxItems: 2
  27
  28   reg-names:
  29     maxItems: 2
  30
  31   interrupts:
  32     items:
  33       - description: module interrupt
  34       - description: EDP interrupt
  35
  36   interrupt-names:
  37     items:
  38       - const: thermal
  39       - const: edp
  40
  41   clocks:
  42     items:
  43       - description: thermal sensor clock
  44       - description: module clock
  45
  46   clock-names:
  47     items:
  48       - const: tsensor
  49       - const: soctherm
  50
  51   resets:
  52     items:
  53       - description: module reset
  54
  55   reset-names:
  56     items:
  57       - const: soctherm
  58
  59   "#thermal-sensor-cells":
  60     const: 1
  61
  62   throttle-cfgs:
  63     $ref: thermal-cooling-devices.yaml
  64     description: A sub-node which is a container of configuration for each
  65       hardware throttle events. These events can be set as cooling devices.
  66       Throttle event sub-nodes must be named as "light" or "heavy".
  67     unevaluatedProperties: false
  68     patternProperties:
  69       "^(light|heavy|oc1)$":
  70         type: object
  71         additionalProperties: false
  72
  73         properties:
  74           "#cooling-cells":
  75             const: 2
  76
  77           nvidia,priority:
  78             $ref: /schemas/types.yaml#/definitions/uint32
  79             minimum: 1
  80             maximum: 100
  81             description: Each throttles has its own throttle settings, so the
  82               SW need to set priorities for various throttle, the HW arbiter
  83               can select the final throttle settings. Bigger value indicates
  84               higher priority, In general, higher priority translates to lower
  85               target frequency. SW needs to ensure that critical thermal
  86               alarms are given higher priority, and ensure that there is no
  87               race if priority of two vectors is set to the same value.
  88
  89           nvidia,cpu-throt-percent:
  90             description: This property is for Tegra124 and Tegra210. It is the
  91               throttling depth of pulse skippers, it's the percentage
  92               throttling.
  93             minimum: 0
  94             maximum: 100
  95
  96           nvidia,cpu-throt-level:
  97             $ref: /schemas/types.yaml#/definitions/uint32
  98             description: This property is only for Tegra132, it is the level
  99               of pulse skippers, which used to throttle clock frequencies. It
 100               indicates cpu clock throttling depth, and the depth can be
 101               programmed.
 102             enum:
 103               # none (TEGRA_SOCTHERM_THROT_LEVEL_NONE)
 104               - 0
 105               # low (TEGRA_SOCTHERM_THROT_LEVEL_LOW)
 106               - 1
 107               # medium (TEGRA_SOCTHERM_THROT_LEVEL_MED)
 108               - 2
 109               # high (TEGRA_SOCTHERM_THROT_LEVEL_HIGH)
 110               - 3
 111
 112           nvidia,gpu-throt-level:
 113             $ref: /schemas/types.yaml#/definitions/uint32
 114             description: This property is for Tegra124 and Tegra210. It is the
 115               level of pulse skippers, which used to throttle clock
 116               frequencies. It indicates gpu clock throttling depth and can be
 117               programmed to any of the following values which represent a
 118               throttling percentage.
 119             enum:
 120               # none (0%, TEGRA_SOCTHERM_THROT_LEVEL_NONE)
 121               - 0
 122               # low (50%, TEGRA_SOCTHERM_THROT_LEVEL_LOW)
 123               - 1
 124               # medium (75%, TEGRA_SOCTHERM_THROT_LEVEL_MED)
 125               - 2
 126               # high (85%, TEGRA_SOCTHERM_THROT_LEVEL_HIGH)
 127               - 3
 128
 129           # optional
 130           # Tegra210 specific and valid only for OCx throttle events
 131           nvidia,count-threshold:
 132             $ref: /schemas/types.yaml#/definitions/uint32
 133             description: Specifies the number of OC events that are required
 134               for triggering an interrupt. Interrupts are not triggered if the
 135               property is missing. A value of 0 will interrupt on every OC
 136               alarm.
 137
 138           nvidia,polarity-active-low:
 139             $ref: /schemas/types.yaml#/definitions/flag
 140             description: Configures the polarity of the OC alaram signal. If
 141               present, this means assert low, otherwise assert high.
 142
 143           nvidia,alarm-filter:
 144             $ref: /schemas/types.yaml#/definitions/uint32
 145             description: Number of clocks to filter event. When the filter
 146               expires (which means the OC event has not occurred for a long
 147               time), the counter is cleared and filter is rearmed.
 148             default: 0
 149
 150           nvidia,throttle-period-us:
 151             description: Specifies the number of microseconds for which
 152               throttling is engaged after the OC event is deasserted.
 153             default: 0
 154
 155   # optional
 156   nvidia,thermtrips:
 157     $ref: /schemas/types.yaml#/definitions/uint32-matrix
 158     description: |
 159       When present, this property specifies the temperature at which the
 160       SOCTHERM hardware will assert the thermal trigger signal to the Power
 161       Management IC, which can be configured to reset or shutdown the device.
 162       It is an array of pairs where each pair represents a tsensor ID followed
 163       by a temperature in milli Celcius. In the absence of this property the
 164       critical trip point will be used for thermtrip temperature.
 165
 166       Note:
 167       - the "critical" type trip points will be used to set the temperature at
 168         which the SOCTHERM hardware will assert a thermal trigger if the
 169         "nvidia,thermtrips" property is missing.  When the thermtrips property
 170         is present, the breach of a critical trip point is reported back to
 171         the thermal framework to implement software shutdown.
 172
 173       - the "hot" type trip points will be set to SOCTHERM hardware as the
 174         throttle temperature.  Once the temperature of this thermal zone is
 175         higher than it, it will trigger the HW throttle event.
 176     items:
 177       items:
 178         - description: sensor ID
 179           oneOf:
 180             - description: CPU sensor
 181               const: 0
 182             - description: MEM sensor
 183               const: 1
 184             - description: GPU sensor
 185               const: 2
 186             - description: PLLX sensor
 187               const: 3
 188         - description: temperature threshold (in millidegree Celsius)
 189
 190 required:
 191   - compatible
 192   - reg
 193   - reg-names
 194   - interrupts
 195   - interrupt-names
 196   - clocks
 197   - clock-names
 198   - resets
 199   - reset-names
 200   - "#thermal-sensor-cells"
 201
 202 allOf:
 203   - $ref: thermal-sensor.yaml
 204   - if:
 205       properties:
 206         compatible:
 207           contains:
 208             enum:
 209               - nvidia,tegra124-soctherm
 210               - nvidia,tegra210-soctherm
 211     then:
 212       properties:
 213         reg:
 214           items:
 215             - description: SOCTHERM register set
 216             - description: clock and reset controller registers
 217
 218         reg-names:
 219           items:
 220             - const: soctherm-reg
 221             - const: car-reg
 222
 223     else:
 224       properties:
 225         reg:
 226           items:
 227             - description: SOCTHERM register set
 228             - description: CCROC registers
 229
 230         reg-names:
 231           items:
 232             - const: soctherm-reg
 233             - const: ccroc-reg
 234
 235 additionalProperties: false
 236
 237 examples:
 238   - |
 239     #include <dt-bindings/clock/tegra124-car.h>
 240     #include <dt-bindings/interrupt-controller/arm-gic.h>
 241     #include <dt-bindings/thermal/tegra124-soctherm.h>
 242
 243     soctherm@700e2000 {
 244         compatible = "nvidia,tegra124-soctherm";
 245         reg = <0x700e2000 0x600>, /* SOC_THERM reg_base */
 246               <0x60006000 0x400>; /* CAR reg_base */
 247         reg-names = "soctherm-reg", "car-reg";
 248         interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>,
 249                      <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>;
 250         interrupt-names = "thermal", "edp";
 251         clocks = <&tegra_car TEGRA124_CLK_TSENSOR>,
 252                  <&tegra_car TEGRA124_CLK_SOC_THERM>;
 253         clock-names = "tsensor", "soctherm";
 254         resets = <&tegra_car 78>;
 255         reset-names = "soctherm";
 256
 257         #thermal-sensor-cells = <1>;
 258
 259         nvidia,thermtrips = <TEGRA124_SOCTHERM_SENSOR_CPU 102500>,
 260                             <TEGRA124_SOCTHERM_SENSOR_GPU 103000>;
 261
 262         throttle-cfgs {
 263             /*
 264              * When the "heavy" cooling device triggered,
 265              * the HW will skip cpu clock's pulse in 85% depth,
 266              * skip gpu clock's pulse in 85% level
 267              */
 268             heavy {
 269                 nvidia,priority = <100>;
 270                 nvidia,cpu-throt-percent = <85>;
 271                 nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>;
 272
 273                 #cooling-cells = <2>;
 274             };
 275
 276             /*
 277              * When the "light" cooling device triggered,
 278              * the HW will skip cpu clock's pulse in 50% depth,
 279              * skip gpu clock's pulse in 50% level
 280              */
 281             light {
 282                 nvidia,priority = <80>;
 283                 nvidia,cpu-throt-percent = <50>;
 284                 nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_LOW>;
 285
 286                 #cooling-cells = <2>;
 287             };
 288
 289             /*
 290              * If these two devices are triggered in same time, the HW throttle
 291              * arbiter will select the highest priority as the final throttle
 292              * settings to skip cpu pulse.
 293              */
 294
 295             oc1 {
 296                 nvidia,priority = <50>;
 297                 nvidia,polarity-active-low;
 298                 nvidia,count-threshold = <100>;
 299                 nvidia,alarm-filter = <5100000>;
 300                 nvidia,throttle-period-us = <0>;
 301                 nvidia,cpu-throt-percent = <75>;
 302                 nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>;
 303             };
 304         };
 305     };
 306
 307   # referring to Tegra132's "reg", "reg-names" and "throttle-cfgs"
 308   - |
 309     thermal-sensor@700e2000 {
 310         compatible = "nvidia,tegra132-soctherm";
 311         reg = <0x700e2000 0x600>, /* SOC_THERM reg_base */
 312               <0x70040000 0x200>; /* CCROC reg_base */
 313         reg-names = "soctherm-reg", "ccroc-reg";
 314         interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>,
 315                      <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>;
 316         interrupt-names = "thermal", "edp";
 317         clocks = <&tegra_car TEGRA124_CLK_TSENSOR>,
 318                  <&tegra_car TEGRA124_CLK_SOC_THERM>;
 319         clock-names = "tsensor", "soctherm";
 320         resets = <&tegra_car 78>;
 321         reset-names = "soctherm";
 322         #thermal-sensor-cells = <1>;
 323
 324         throttle-cfgs {
 325             /*
 326              * When the "heavy" cooling device triggered,
 327              * the HW will skip cpu clock's pulse in HIGH level
 328              */
 329             heavy {
 330                 nvidia,priority = <100>;
 331                 nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>;
 332
 333                 #cooling-cells = <2>;
 334             };
 335
 336             /*
 337              * When the "light" cooling device triggered,
 338              * the HW will skip cpu clock's pulse in MED level
 339              */
 340             light {
 341                 nvidia,priority = <80>;
 342                 nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>;
 343
 344                 #cooling-cells = <2>;
 345             };
 346
 347             /*
 348              * If these two devices are triggered in same time, the HW throttle
 349              * arbiter will select the highest priority as the final throttle
 350              * settings to skip cpu pulse.
 351              */
 352         };
 353     };
 354
 355   # referring to thermal sensors
 356   - |
 357     thermal-zones {
 358         cpu-thermal {
 359             polling-delay-passive = <1000>;
 360             polling-delay = <1000>;
 361
 362             thermal-sensors = <&soctherm TEGRA124_SOCTHERM_SENSOR_CPU>;
 363
 364             trips {
 365                 cpu_shutdown_trip: shutdown-trip {
 366                     temperature = <102500>;
 367                     hysteresis = <1000>;
 368                     type = "critical";
 369                 };
 370
 371                 cpu_throttle_trip: throttle-trip {
 372                     temperature = <100000>;
 373                     hysteresis = <1000>;
 374                     type = "hot";
 375                 };
 376             };
 377
 378             cooling-maps {
 379                 map0 {
 380                     trip = <&cpu_throttle_trip>;
 381                     cooling-device = <&throttle_heavy 1 1>;
 382                 };
 383             };
 384         };
 385     };