[v2,02/13] dt-bindings: thermal: tegra: Document throttle temperature

From: Thierry Reding <treding@nvidia.com>

Each throttling configuration needs to specify the temperature threshold
at which it should start throttling. Previously this was tied to a given
trip point as a cooling device and used the temperature specified for
that trip point. This doesn't work well because the throttling mechanism
is not a cooling device in the traditional sense.

Instead, allow device trees to specify the throttle temperature in the
throttle configuration directly so that the throttle doesn't need to be
exposed as a cooling device.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
Changes in v2:
- rename temperature to temperature-millicelsius and drop $ref
- add hysteresis-millicelsius property

 .../bindings/thermal/nvidia,tegra124-soctherm.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

On Thu, Oct 12, 2023 at 07:58:23PM +0200, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Each throttling configuration needs to specify the temperature threshold
> at which it should start throttling. Previously this was tied to a given
> trip point as a cooling device and used the temperature specified for
> that trip point. This doesn't work well because the throttling mechanism
> is not a cooling device in the traditional sense.
> 
> Instead, allow device trees to specify the throttle temperature in the
> throttle configuration directly so that the throttle doesn't need to be
> exposed as a cooling device.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
> Changes in v2:
> - rename temperature to temperature-millicelsius and drop $ref
> - add hysteresis-millicelsius property
> 
>  .../bindings/thermal/nvidia,tegra124-soctherm.yaml | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml
> index 04a2ba1aa946..0eb6277082fe 100644
> --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml
> +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml
> @@ -121,6 +121,20 @@ properties:
>                # high (85%, TEGRA_SOCTHERM_THROT_LEVEL_HIGH)
>                - 3
>  
> +          temperature-millicelsius:

'temperature' is redundant since we have units. Perhaps 
'throttle-millicelsius' or 'auto-throttle-millicelsius' instead to say 
what the temperature is for.

> +            minimum: -273000
> +            maximum: 200000

Quite impressive operating range.

> +            description: The temperature threshold (in millicelsius) that,
> +              when crossed, will trigger the configured automatic throttling.
> +
> +          hysteresis-millicelsius:
> +            description: An unsigned integer expressing the hysteresis delta
> +              (in millicelsius) with respect to the threshold temperature
> +              property above. Throttling will be initiated when the
> +              temperature falls below (temperature - hysteresis). This avoids
> +              situations where throttling is repeatedly initiated and stopped
> +              because of minor temperature variations.
> +
>            # optional
>            # Tegra210 specific and valid only for OCx throttle events
>            nvidia,count-threshold:
> -- 
> 2.42.0
>

On Mon, Oct 16, 2023 at 09:02:49AM -0500, Rob Herring wrote:
> On Thu, Oct 12, 2023 at 07:58:23PM +0200, Thierry Reding wrote:
> > From: Thierry Reding <treding@nvidia.com>
> > 
> > Each throttling configuration needs to specify the temperature threshold
> > at which it should start throttling. Previously this was tied to a given
> > trip point as a cooling device and used the temperature specified for
> > that trip point. This doesn't work well because the throttling mechanism
> > is not a cooling device in the traditional sense.
> > 
> > Instead, allow device trees to specify the throttle temperature in the
> > throttle configuration directly so that the throttle doesn't need to be
> > exposed as a cooling device.
> > 
> > Signed-off-by: Thierry Reding <treding@nvidia.com>
> > ---
> > Changes in v2:
> > - rename temperature to temperature-millicelsius and drop $ref
> > - add hysteresis-millicelsius property
> > 
> >  .../bindings/thermal/nvidia,tegra124-soctherm.yaml | 14 ++++++++++++++
> >  1 file changed, 14 insertions(+)
> > 
> > diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml
> > index 04a2ba1aa946..0eb6277082fe 100644
> > --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml
> > +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml
> > @@ -121,6 +121,20 @@ properties:
> >                # high (85%, TEGRA_SOCTHERM_THROT_LEVEL_HIGH)
> >                - 3
> >  
> > +          temperature-millicelsius:
> 
> 'temperature' is redundant since we have units. Perhaps 
> 'throttle-millicelsius' or 'auto-throttle-millicelsius' instead to say 
> what the temperature is for.

Okay, will do.

> 
> > +            minimum: -273000
> > +            maximum: 200000
> 
> Quite impressive operating range.

Yeah, I don't actually know where these come from. Looking at the manual
these sensors are actually limited to -127°C - 127°C. I'll fix that up.

Thierry