From patchwork Wed Apr 1 11:15:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Amit Kucheria X-Patchwork-Id: 1265165 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (no SPF record) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=devicetree-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=FbdDNrTR; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 48skC04c9Yz9sSr for ; Wed, 1 Apr 2020 22:15:40 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732121AbgDALPj (ORCPT ); Wed, 1 Apr 2020 07:15:39 -0400 Received: from mail-pj1-f65.google.com ([209.85.216.65]:38854 "EHLO mail-pj1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732388AbgDALPj (ORCPT ); Wed, 1 Apr 2020 07:15:39 -0400 Received: by mail-pj1-f65.google.com with SMTP id m15so2556776pje.3 for ; Wed, 01 Apr 2020 04:15:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=V5DAow7umIWoAdNuh/e+goWjtgRcJmCEdNFZmOOCst4=; b=FbdDNrTR1rEsjP1N92wJt0BbZU1h1vMbPUnnk+XeEz8HfNkMz4RdOeztgYLcCCLCk8 V7k223ZleYtO9TFWzl8SeoGowRT8VfOs348F7CwQi5LzFlw7B1LqcpEMWNIXnc/HLJL6 3Or/vPnKqbpAeluNFB+zBYGLl4Nv6lvZjkUiMq998r/UqMiAbqXy2HgU6p//pYSwzIEI GvcJlmdwd6/ceZDUY5TpY7OmiQToa/sOHgTBLTP6f8zCrQlN+R93Smsf/tJJQSNqUdMR zZV1wxa6H/+SZ2p5NukrvN348AeC97Av2V5C+6RPf+vttb7ZSw8T8J9d01mRSUx+dLx3 XmNg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=V5DAow7umIWoAdNuh/e+goWjtgRcJmCEdNFZmOOCst4=; b=bTv1aNDjuqbMS3A+LZ4m7mT20eNVx7pCQhnbjxKtHR/7AGMPRmpEoejZOumcep2EDS hvko9S3xF7KkLx5Vmr7GLxNnXg4u8xJxKTRYksRiwVEClGSMFtJn7kPW3SN3UUnBW9W3 OX4zv7RDcc54Bxtdz3Oy2mwGEFHBAwle88YuvBv0kKzkK+SJdMOxtchmaaO+mwpuN9ry XyF3B42QO3GFu9fxuwQI7mR4UL3ElGnjQHY5B+ZzXfN1+8v3zOPN4q3Jm9bbJBxeo2Y1 chfqF7fUpJAKOTJF25lkuKWq3EpujVSuPp4bOnuRWIhE0VFTgySN3R+Op0SgHv5q8OPy PLww== X-Gm-Message-State: ANhLgQ1v/PN2bqYnh01saUeTFharTUrueOWo4DUT+4QCv8yhwySmOwJw Aj60JN+geRorYGHh505RRMhTFw== X-Google-Smtp-Source: ADFU+vvVBGvIhVhr1zs31Lyb+iHUNpWCBDeKn6KRUgdZt8UMivaSHVOyGOX91na4FYx2WR1Ob70hjg== X-Received: by 2002:a17:902:fe06:: with SMTP id g6mr22139809plj.263.1585739737563; Wed, 01 Apr 2020 04:15:37 -0700 (PDT) Received: from localhost ([103.195.202.232]) by smtp.gmail.com with ESMTPSA id go9sm1388404pjb.27.2020.04.01.04.15.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Apr 2020 04:15:36 -0700 (PDT) From: Amit Kucheria To: linux-kernel@vger.kernel.org, linux-arm-msm@vger.kernel.org, swboyd@chromium.org, lukasz.luba@arm.com, mka@chromium.org, daniel.lezcano@linaro.org, Amit Kucheria , Zhang Rui Cc: Rob Herring , linux-pm@vger.kernel.org, devicetree@vger.kernel.org Subject: [PATCH v4 1/3] dt-bindings: thermal: Add yaml bindings for thermal sensors Date: Wed, 1 Apr 2020 16:45:25 +0530 Message-Id: <146b5dfebf23321c1eed8190ada957e2264ffe65.1585738725.git.amit.kucheria@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: References: MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org As part of moving the thermal bindings to YAML, split it up into 3 bindings: thermal sensors, cooling devices and thermal zones. The property #thermal-sensor-cells is required in each device that acts as a thermal sensor. It is used to uniquely identify the instance of the thermal sensor inside the system. Signed-off-by: Amit Kucheria Reviewed-by: Rob Herring Reviewed-by: Lukasz Luba --- .../bindings/thermal/thermal-sensor.yaml | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 Documentation/devicetree/bindings/thermal/thermal-sensor.yaml diff --git a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml new file mode 100644 index 0000000000000..920ee7667591d --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0) +# Copyright 2020 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/thermal-sensor.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Thermal sensor binding + +maintainers: + - Amit Kucheria + +description: | + Thermal management is achieved in devicetree by describing the sensor hardware + and the software abstraction of thermal zones required to take appropriate + action to mitigate thermal overloads. + + 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 artively + - thermal-zones: a container of the following node types used to describe all + thermal data for the platform + + This binding describes the thermal-sensor. + + Thermal sensor devices provide temperature sensing capabilities on thermal + zones. Typical devices are I2C ADC converters and bandgaps. Thermal sensor + devices may control one or more internal sensors. + +properties: + "#thermal-sensor-cells": + description: + Used to uniquely identify a thermal sensor instance within an IC. Will be + 0 on sensor nodes with only a single sensor and at least 1 on nodes + containing several internal sensors. + enum: [0, 1] + +examples: + - | + #include + + // Example 1: SDM845 TSENS + soc: soc@0 { + #address-cells = <2>; + #size-cells = <2>; + + /* ... */ + + tsens0: thermal-sensor@c263000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c263000 0 0x1ff>, /* TM */ + <0 0x0c222000 0 0x1ff>; /* SROT */ + #qcom,sensors = <13>; + interrupts = , + ; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + + tsens1: thermal-sensor@c265000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c265000 0 0x1ff>, /* TM */ + <0 0x0c223000 0 0x1ff>; /* SROT */ + #qcom,sensors = <8>; + interrupts = , + ; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + }; +... From patchwork Wed Apr 1 11:15:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Amit Kucheria X-Patchwork-Id: 1265166 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (no SPF record) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=devicetree-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=J9p4I7ha; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 48skC50N4Gz9sSb for ; Wed, 1 Apr 2020 22:15:45 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732423AbgDALPn (ORCPT ); Wed, 1 Apr 2020 07:15:43 -0400 Received: from mail-pg1-f195.google.com ([209.85.215.195]:46757 "EHLO mail-pg1-f195.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732422AbgDALPn (ORCPT ); Wed, 1 Apr 2020 07:15:43 -0400 Received: by mail-pg1-f195.google.com with SMTP id k191so11939792pgc.13 for ; Wed, 01 Apr 2020 04:15:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=iutfgAEMr3aVnETDGpH220S0Jcsh/zdk3Pb7ajXb/+Q=; b=J9p4I7ha9Kr4aCnjJUEmfgDuGIMxLJY57FMqgMrTxiyzl4NanfRaPU5YcNjC4r/WZL nk2/D0Tl7uXpOTYHkSP5WxMpGJk2c+vA+h23xv22k8NUNFpj50vfIIcD4gAJwOLIgx6a WS4B9SZwKrKwNUA+Bav04kd86EchZ0bJIdzsCORhN/TzCwYzny04tcFljyo8xk6IHdFP ev3xUa+1LKjHyvJrF75V+clg0uTz+3kBSb2zF9NHUwx1y1bB1Z15Xfh/dwudjdpdM0Uy Pu084v+RsFqNBd8Bu7PhOUvbd74pHJ026APLoYLdApY+mEFmewbWzx6YF/6Q8Vp7KoYa u5LA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=iutfgAEMr3aVnETDGpH220S0Jcsh/zdk3Pb7ajXb/+Q=; b=JvJH41aYUKpCZfT3cS9iM/8JDgYyI9fNlXJfjvdQVJg22utL/CqYgYOx8uzlUUd0AW kR9TwK/4LJ7ZH9EumZS37QWSOHS9toh18aVDMolits/ZudLyqEMJgemQEIsWrkeNedcc mxomHaf4xsBiyC8daL02IQWdBauYFQRSU/OBJ/azdNY9FCN72j+OTn+6hyhVmX0tzwts xH2NU9KwiRnpaV62rmzxpIK1p23TjFuMqLTyBYUfazL8PM9rgD3v6ql4W9mH5ai2uxI0 NfRnFsm6oyd1mT88UF6vuIkCDXrXe++9tYafBGTRdiKM5/nPftUl+JddturFpH8NSn3Y uKjw== X-Gm-Message-State: ANhLgQ1CTYYLFqbMOxLDIRc336XyzkbA01PUlSTGyUgg+BSpLLKy7JEF iGOROp/SFNzQsdNNrBx96KV2gw== X-Google-Smtp-Source: ADFU+vszJlCQlH8uGs6tDDPH5jgNe2yuSVEB+jC8VaV64tQe6uSeKkPTUlv574C/T6c1WCdCf8PiKQ== X-Received: by 2002:a65:5b49:: with SMTP id y9mr21836208pgr.153.1585739742212; Wed, 01 Apr 2020 04:15:42 -0700 (PDT) Received: from localhost ([103.195.202.232]) by smtp.gmail.com with ESMTPSA id u41sm1277117pgn.8.2020.04.01.04.15.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Apr 2020 04:15:41 -0700 (PDT) From: Amit Kucheria To: linux-kernel@vger.kernel.org, linux-arm-msm@vger.kernel.org, swboyd@chromium.org, lukasz.luba@arm.com, mka@chromium.org, daniel.lezcano@linaro.org, Amit Kucheria , Zhang Rui Cc: Rob Herring , linux-pm@vger.kernel.org, devicetree@vger.kernel.org Subject: [PATCH v4 2/3] dt-bindings: thermal: Add yaml bindings for thermal cooling-devices Date: Wed, 1 Apr 2020 16:45:26 +0530 Message-Id: X-Mailer: git-send-email 2.20.1 In-Reply-To: References: MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org As part of moving the thermal bindings to YAML, split it up into 3 bindings: thermal sensors, cooling devices and thermal zones. The property #cooling-cells is required in each device that acts as a cooling device - whether active or passive. So any device that can throttle its performance to passively reduce heat dissipation (e.g. cpus, gpus) and any device that can actively dissipate heat at different levels (e.g. fans) will contain this property. Signed-off-by: Amit Kucheria Reviewed-by: Rob Herring Reviewed-by: Lukasz Luba --- Changes since v3: - Clarify example by using cooling state numbers and a comment .../thermal/thermal-cooling-devices.yaml | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml diff --git a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml new file mode 100644 index 0000000000000..0dc4a743a1351 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml @@ -0,0 +1,116 @@ +# 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 + +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 artively + - 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 + #include + + // 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>; + }; + }; + }; + + /* ... */ + }; +... From patchwork Wed Apr 1 11:15:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Amit Kucheria X-Patchwork-Id: 1265167 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (no SPF record) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=devicetree-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=Yga5g6vI; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 48skCC3vYdz9sSw for ; Wed, 1 Apr 2020 22:15:51 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732444AbgDALPu (ORCPT ); Wed, 1 Apr 2020 07:15:50 -0400 Received: from mail-pg1-f182.google.com ([209.85.215.182]:45519 "EHLO mail-pg1-f182.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732422AbgDALPt (ORCPT ); Wed, 1 Apr 2020 07:15:49 -0400 Received: by mail-pg1-f182.google.com with SMTP id o26so11950434pgc.12 for ; Wed, 01 Apr 2020 04:15:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=y5rp/BICQeEFC95frY5/x3/iojI34G4jygp7Vh5S5sQ=; b=Yga5g6vIlypTJkcyP7gycGOc9WlFEQyH+0IVQFE5aWyfDZS24YtOSCeuCmuHX5AeXM VsaiN7gsuVsm0cEITQkNgmowbGlT4T/n7522sVjjB0gmgZrSyzTYrElFhxPZ4JgjHF4I bQGjyGYQDeUAVtrQQUGjhmoZRxXmATjBgwZWJ2YHERc2le2ykwi5LzBcZFaAuIKHR2xk 056gvjynCcCVuer6qm5EMBQd9SkoIlAN2IZnx0WaLXrhXR9iF6cChPCXwMavenaqJxec dSh7V+8Vr708eiYX1DzGN3oIDTqb0aHc5gRQLlG8Xf2RG1QKfdWxd+kfUKdkS9UYYRQD B2gA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=y5rp/BICQeEFC95frY5/x3/iojI34G4jygp7Vh5S5sQ=; b=dcSJKqzMyCp7Piaut7eEDfO/6MomnH0PzUGrzbKnMVzhi/FgT+3+kOPOxjEZ1HzIpy as45M/HSSFZ739CU37dVJyF0upc5qtLrdt9kZlwvh8tLG0RsV52g0okdHrl8SUH8wh+s qtcQHQ9DMnw++VtNn5jok65FP47+twBLrO9heRTPpWQXTOLAmRK8fOdvgSgBnGazpCmT ho9mcsBY7QKVT+GOw1YsTgGE2WUQ6fULZwWZoJ8OACSqNB4Ciex+Ms68MEbPAl73YHwd huMBrJ/4VBPhVLlcUw98WXPbkWTsQ81Idv6MfYUYV04xrQw9rC+BbCm9GOcoZWf+X3VC LMwg== X-Gm-Message-State: ANhLgQ0Wt8gSVv1ItmZpLbMitcDmDpNRzTEoIiBsb/kAC3ItofnL7Z9P 40LxVJ5LncU6eVxqfZznPUXTlw== X-Google-Smtp-Source: ADFU+vuvtxckvL9WqY/DCTgFUMssRGqxPC2es6d6x5yvwkdskruYByxPFlHP4rXXqr1cPacakiJxxw== X-Received: by 2002:a63:8048:: with SMTP id j69mr22516800pgd.410.1585739746563; Wed, 01 Apr 2020 04:15:46 -0700 (PDT) Received: from localhost ([103.195.202.232]) by smtp.gmail.com with ESMTPSA id u4sm1230326pgu.5.2020.04.01.04.15.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Apr 2020 04:15:45 -0700 (PDT) From: Amit Kucheria To: linux-kernel@vger.kernel.org, linux-arm-msm@vger.kernel.org, swboyd@chromium.org, lukasz.luba@arm.com, mka@chromium.org, daniel.lezcano@linaro.org, Amit Kucheria , Zhang Rui Cc: Rob Herring , linux-pm@vger.kernel.org, devicetree@vger.kernel.org Subject: [PATCH v4 3/3] dt-bindings: thermal: Add yaml bindings for thermal zones Date: Wed, 1 Apr 2020 16:45:27 +0530 Message-Id: X-Mailer: git-send-email 2.20.1 In-Reply-To: References: MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org As part of moving the thermal bindings to YAML, split it up into 3 bindings: thermal sensors, cooling devices and thermal zones. The thermal-zone binding is a software abstraction to capture the properties of each zone - how often they should be checked, the temperature thresholds (trips) at which mitigation actions need to be taken and the level of mitigation needed at those thresholds. Signed-off-by: Amit Kucheria Reviewed-by: Rob Herring Reviewed-by: Lukasz Luba --- Changes since v3: - Clarify example by using cooling state numbers and a comment - Restrict thermal-sensors to a single reference to reflect actual code where there is a one-to-one mapping between sensors and thermal zones - Add two optional properties that were missed in earlier submissions: coefficients and sustainable-power - Improve description of hysteresis and contribution properties .../bindings/thermal/thermal-zones.yaml | 341 ++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 Documentation/devicetree/bindings/thermal/thermal-zones.yaml diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml new file mode 100644 index 0000000000000..302170d79fe94 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -0,0 +1,341 @@ +# SPDX-License-Identifier: (GPL-2.0) +# Copyright 2020 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml# +$schema: http://devicetree.org/meta-schemas/base.yaml# + +title: Thermal zone binding + +maintainers: + - Amit Kucheria + +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 overloads. + + 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 thermal-zones. + + The polling-delay properties of a thermal-zone are bound to the maximum dT/dt + (temperature derivative over time) in two situations for a thermal zone: + 1. when passive cooling is activated (polling-delay-passive) + 2. when the zone just needs to be monitored (polling-delay) or when + active cooling is activated. + + The maximum dT/dt is highly bound to hardware power consumption and + dissipation capability. The delays should be chosen to account for said + max dT/dt, such that a device does not cross several trip boundaries + unexpectedly between polls. Choosing the right polling delays shall avoid + having the device in temperature ranges that may damage the silicon structures + and reduce silicon lifetime. + +properties: + $nodename: + const: thermal-zones + description: + A /thermal-zones node is required in order to use the thermal framework to + manage input from the various thermal zones in the system in order to + mitigate thermal overload conditions. It does not represent a real device + in the system, but acts as a container to link a thermal sensor device, + platform-data regarding temperature thresholds and the mitigation actions + to take when the temperature crosses those thresholds. + +patternProperties: + "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$": + type: object + description: + Each thermal zone node contains information about how frequently it + must be checked, the sensor responsible for reporting temperature for + this zone, one sub-node containing the various trip points for this + zone and one sub-node containing all the zone cooling-maps. + + properties: + polling-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The maximum number of milliseconds to wait between polls when + checking this thermal zone. Setting this to 0 disables the polling + timers setup by the thermal framework and assumes that the thermal + sensors in this zone support interrupts. + + polling-delay-passive: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The maximum number of milliseconds to wait between polls when + checking this thermal zone while doing passive cooling. Setting + this to 0 disables the polling timers setup by the thermal + framework and assumes that the thermal sensors in this zone + support interrupts. + + thermal-sensors: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 + description: + The thermal sensor phandle and sensor specifier used to monitor this + thermal zone. + + coefficients: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + An array of integers containing the coefficients of a linear equation + that binds all the sensors listed in this thermal zone. + + The linear equation used is as follows, + z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn + where c0, c1, .., cn are the coefficients. + + Coefficients default to 1, in case this property is not specified. The + coefficients are ordered and are matched with sensors by means of the + sensor ID. Additional coefficients are interpreted as constant offset. + + sustainable-power: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + An estimate of the sustainable power (in mW) that this thermal zone + can dissipate at the desired control temperature. For reference, the + sustainable power of a 4-inch phone is typically 2000mW, while on a + 10-inch tablet is around 4500mW. + + trips: + type: object + description: + This node describes a set of points in the temperature domain at + which the thermal framework needs to take action. The actions to + be taken are defined in another node called cooling-maps. + + patternProperties: + "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$": + type: object + + properties: + temperature: + $ref: /schemas/types.yaml#/definitions/int32 + minimum: -273000 + maximum: 200000 + description: + An integer expressing the trip temperature in millicelsius. + + hysteresis: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + An unsigned integer expressing the hysteresis delta with + respect to the trip temperature property above, also in + millicelsius. Any cooling action initiated by the framework is + maintained until the temperature falls below + (trip temperature - hysteresis). This potentially prevents a + situation where the trip gets constantly triggered soon after + cooling action is removed. + + type: + $ref: /schemas/types.yaml#/definitions/string + enum: + - active # enable active cooling e.g. fans + - passive # enable passive cooling e.g. throttling cpu + - hot # send notification to driver + - critical # send notification to driver, trigger shutdown + description: | + There are four valid trip types: active, passive, hot, + critical. + + The critical trip type is used to set the maximum + temperature threshold above which the HW becomes + unstable and underlying firmware might even trigger a + reboot. Hitting the critical threshold triggers a system + shutdown. + + The hot trip type can be used to send a notification to + the thermal driver (if a .notify callback is registered). + The action to be taken is left to the driver. + + The passive trip type can be used to slow down HW e.g. run + the CPU, GPU, bus at a lower frequency. + + The active trip type can be used to control other HW to + help in cooling e.g. fans can be sped up or slowed down + + required: + - temperature + - hysteresis + - type + additionalProperties: false + + additionalProperties: false + + cooling-maps: + type: object + description: + This node describes the action to be taken when a thermal zone + crosses one of the temperature thresholds described in the trips + node. The action takes the form of a mapping relation between a + trip and the target cooling device state. + + patternProperties: + "^map[-a-zA-Z0-9]*$": + type: object + + properties: + trip: + $ref: /schemas/types.yaml#/definitions/phandle + description: + A phandle of a trip point node within this thermal zone. + + cooling-device: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + A list of cooling device phandles along with the minimum + and maximum cooling state specifiers for each cooling + device. Using the THERMAL_NO_LIMIT (-1UL) constant in the + cooling-device phandle limit specifier lets the framework + use the minimum and maximum cooling state for that cooling + device automatically. + + contribution: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 100 + description: + The percentage contribution of the cooling devices at the + specific trip temperature referenced in this map + to this thermal zone + + required: + - trip + - cooling-device + additionalProperties: false + + required: + - polling-delay + - polling-delay-passive + - thermal-sensors + - trips + additionalProperties: false + +examples: + - | + #include + #include + + // Example 1: SDM845 TSENS + soc: soc@0 { + #address-cells = <2>; + #size-cells = <2>; + + /* ... */ + + tsens0: thermal-sensor@c263000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c263000 0 0x1ff>, /* TM */ + <0 0x0c222000 0 0x1ff>; /* SROT */ + #qcom,sensors = <13>; + interrupts = , + ; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + + tsens1: thermal-sensor@c265000 { + compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; + reg = <0 0x0c265000 0 0x1ff>, /* TM */ + <0 0x0c223000 0 0x1ff>; /* SROT */ + #qcom,sensors = <8>; + interrupts = , + ; + interrupt-names = "uplow", "critical"; + #thermal-sensor-cells = <1>; + }; + }; + + /* ... */ + + 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"; + }; + + cpu0_alert1: trip-point1 { + temperature = <95000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu0_crit: cpu_crit { + temperature = <110000>; + hysteresis = <1000>; + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu0_alert0>; + /* Corresponds to 1400MHz in OPP table */ + cooling-device = <&CPU0 3 3>, <&CPU1 3 3>, + <&CPU2 3 3>, <&CPU3 3 3>; + }; + + map1 { + trip = <&cpu0_alert1>; + /* Corresponds to 1400MHz in OPP table */ + cooling-device = <&CPU0 5 5>, <&CPU1 5 5>, + <&CPU2 5 5>, <&CPU3 5 5>; + }; + }; + }; + + /* ... */ + + cluster0-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + + thermal-sensors = <&tsens0 5>; + + trips { + cluster0_alert0: trip-point0 { + temperature = <90000>; + hysteresis = <2000>; + type = "hot"; + }; + cluster0_crit: cluster0_crit { + temperature = <110000>; + hysteresis = <2000>; + type = "critical"; + }; + }; + }; + + /* ... */ + + gpu-top-thermal { + polling-delay-passive = <250>; + polling-delay = <1000>; + + thermal-sensors = <&tsens0 11>; + + trips { + gpu1_alert0: trip-point0 { + temperature = <90000>; + hysteresis = <2000>; + type = "hot"; + }; + }; + }; + }; +...