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        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
190required:
191  - compatible
192  - reg
193  - reg-names
194  - interrupts
195  - interrupt-names
196  - clocks
197  - clock-names
198  - resets
199  - reset-names
200
201allOf:
202  - $ref: thermal-sensor.yaml
203  - if:
204      properties:
205        compatible:
206          contains:
207            enum:
208              - nvidia,tegra124-soctherm
209              - nvidia,tegra210-soctherm
210    then:
211      properties:
212        reg:
213          items:
214            - description: SOCTHERM register set
215            - description: clock and reset controller registers
216
217        reg-names:
218          items:
219            - const: soctherm-reg
220            - const: car-reg
221
222    else:
223      properties:
224        reg:
225          items:
226            - description: SOCTHERM register set
227            - description: CCROC registers
228
229        reg-names:
230          items:
231            - const: soctherm-reg
232            - const: ccroc-reg
233
234additionalProperties: false
235
236examples:
237  - |
238    #include <dt-bindings/clock/tegra124-car.h>
239    #include <dt-bindings/interrupt-controller/arm-gic.h>
240    #include <dt-bindings/thermal/tegra124-soctherm.h>
241
242    soctherm@700e2000 {
243        compatible = "nvidia,tegra124-soctherm";
244        reg = <0x700e2000 0x600>, /* SOC_THERM reg_base */
245              <0x60006000 0x400>; /* CAR reg_base */
246        reg-names = "soctherm-reg", "car-reg";
247        interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>,
248                     <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>;
249        interrupt-names = "thermal", "edp";
250        clocks = <&tegra_car TEGRA124_CLK_TSENSOR>,
251                 <&tegra_car TEGRA124_CLK_SOC_THERM>;
252        clock-names = "tsensor", "soctherm";
253        resets = <&tegra_car 78>;
254        reset-names = "soctherm";
255
256        #thermal-sensor-cells = <1>;
257
258        nvidia,thermtrips = <TEGRA124_SOCTHERM_SENSOR_CPU 102500>,
259                            <TEGRA124_SOCTHERM_SENSOR_GPU 103000>;
260
261        throttle-cfgs {
262            /*
263             * When the "heavy" cooling device triggered,
264             * the HW will skip cpu clock's pulse in 85% depth,
265             * skip gpu clock's pulse in 85% level
266             */
267            heavy {
268                nvidia,priority = <100>;
269                nvidia,cpu-throt-percent = <85>;
270                nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>;
271
272                #cooling-cells = <2>;
273            };
274
275            /*
276             * When the "light" cooling device triggered,
277             * the HW will skip cpu clock's pulse in 50% depth,
278             * skip gpu clock's pulse in 50% level
279             */
280            light {
281                nvidia,priority = <80>;
282                nvidia,cpu-throt-percent = <50>;
283                nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_LOW>;
284
285                #cooling-cells = <2>;
286            };
287
288            /*
289             * If these two devices are triggered in same time, the HW throttle
290             * arbiter will select the highest priority as the final throttle
291             * settings to skip cpu pulse.
292             */
293
294            oc1 {
295                nvidia,priority = <50>;
296                nvidia,polarity-active-low;
297                nvidia,count-threshold = <100>;
298                nvidia,alarm-filter = <5100000>;
299                nvidia,throttle-period-us = <0>;
300                nvidia,cpu-throt-percent = <75>;
301                nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>;
302            };
303        };
304    };
305
306  # referring to Tegra132's "reg", "reg-names" and "throttle-cfgs"
307  - |
308    thermal-sensor@700e2000 {
309        compatible = "nvidia,tegra132-soctherm";
310        reg = <0x700e2000 0x600>, /* SOC_THERM reg_base */
311              <0x70040000 0x200>; /* CCROC reg_base */
312        reg-names = "soctherm-reg", "ccroc-reg";
313        interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>,
314                     <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>;
315        interrupt-names = "thermal", "edp";
316        clocks = <&tegra_car TEGRA124_CLK_TSENSOR>,
317                 <&tegra_car TEGRA124_CLK_SOC_THERM>;
318        clock-names = "tsensor", "soctherm";
319        resets = <&tegra_car 78>;
320        reset-names = "soctherm";
321        #thermal-sensor-cells = <1>;
322
323        throttle-cfgs {
324            /*
325             * When the "heavy" cooling device triggered,
326             * the HW will skip cpu clock's pulse in HIGH level
327             */
328            heavy {
329                nvidia,priority = <100>;
330                nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>;
331
332                #cooling-cells = <2>;
333            };
334
335            /*
336             * When the "light" cooling device triggered,
337             * the HW will skip cpu clock's pulse in MED level
338             */
339            light {
340                nvidia,priority = <80>;
341                nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>;
342
343                #cooling-cells = <2>;
344            };
345
346            /*
347             * If these two devices are triggered in same time, the HW throttle
348             * arbiter will select the highest priority as the final throttle
349             * settings to skip cpu pulse.
350             */
351        };
352    };
353
354  # referring to thermal sensors
355  - |
356    thermal-zones {
357        cpu-thermal {
358            polling-delay-passive = <1000>;
359            polling-delay = <1000>;
360
361            thermal-sensors = <&soctherm TEGRA124_SOCTHERM_SENSOR_CPU>;
362
363            trips {
364                cpu_shutdown_trip: shutdown-trip {
365                    temperature = <102500>;
366                    hysteresis = <1000>;
367                    type = "critical";
368                };
369
370                cpu_throttle_trip: throttle-trip {
371                    temperature = <100000>;
372                    hysteresis = <1000>;
373                    type = "hot";
374                };
375            };
376
377            cooling-maps {
378                map0 {
379                    trip = <&cpu_throttle_trip>;
380                    cooling-device = <&throttle_heavy 1 1>;
381                };
382            };
383        };
384    };
385