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