diff mbox series

[v3] dt-bindings: hwmon: Convert NTC thermistor to YAML

Message ID 20210922233901.1871274-1-linus.walleij@linaro.org
State Accepted
Commit 7bcc5a7a5c2bf03e21bc2eea422b9ec5f6615e83
Headers show
Series [v3] dt-bindings: hwmon: Convert NTC thermistor to YAML | expand

Commit Message

Linus Walleij Sept. 22, 2021, 11:39 p.m. UTC 
This converts the NTC thermistor DT bindings to YAML. Some care had to
be taken since I had to add some illustrations to make the connection
layouts graspable.

Cc: Javier Martinez Canillas <javier@dowhile0.org>
Cc: Johannes Pointner <johannes.pointner@gmail.com>
Cc: Peter Rosin <peda@axentia.se>
Cc: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

---
ChangeLog v2->v3:
- Rebase on v5.15-rc1
- Drop comment reference to thermal-sensor.yaml
- Keep the oneOf rather than using an enum for the compatible:
  I can't figure out how to make deprecated work for enums?
  https://lore.kernel.org/linux-hwmon/CACRpkdZDLSA5YJtc3XCkfPZUNqo1MOWLBwVDGQ4vN8cDXD3aYg@mail.gmail.com/
ChangeLog v1->v2:
- Realize I need to CC devicetree@vger.kernel.org on this.
- Fix Javier's mail address.
- Drop Naveen's mail (bouncing)
---
 .../bindings/hwmon/ntc-thermistor.yaml        | 141 ++++++++++++++++++
 .../bindings/hwmon/ntc_thermistor.txt         |  44 ------
 2 files changed, 141 insertions(+), 44 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml
 delete mode 100644 Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt

-- 
2.31.1

Comments

Rob Herring (Arm) Sept. 23, 2021, 1:10 p.m. UTC | #1 
On Thu, 23 Sep 2021 01:39:01 +0200, Linus Walleij wrote:
> This converts the NTC thermistor DT bindings to YAML. Some care had to

> be taken since I had to add some illustrations to make the connection

> layouts graspable.

> 

> Cc: Javier Martinez Canillas <javier@dowhile0.org>

> Cc: Johannes Pointner <johannes.pointner@gmail.com>

> Cc: Peter Rosin <peda@axentia.se>

> Cc: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> Cc: devicetree@vger.kernel.org

> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

> ---

> ChangeLog v2->v3:

> - Rebase on v5.15-rc1

> - Drop comment reference to thermal-sensor.yaml

> - Keep the oneOf rather than using an enum for the compatible:

>   I can't figure out how to make deprecated work for enums?

>   https://lore.kernel.org/linux-hwmon/CACRpkdZDLSA5YJtc3XCkfPZUNqo1MOWLBwVDGQ4vN8cDXD3aYg@mail.gmail.com/

> ChangeLog v1->v2:

> - Realize I need to CC devicetree@vger.kernel.org on this.

> - Fix Javier's mail address.

> - Drop Naveen's mail (bouncing)

> ---

>  .../bindings/hwmon/ntc-thermistor.yaml        | 141 ++++++++++++++++++

>  .../bindings/hwmon/ntc_thermistor.txt         |  44 ------

>  2 files changed, 141 insertions(+), 44 deletions(-)

>  create mode 100644 Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml

>  delete mode 100644 Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt

> 


My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/linux-dt-review/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.example.dt.yaml: ncp15wb473: $nodename:0: 'ncp15wb473' does not match '^thermistor(.*)?$'
	From schema: /builds/robherring/linux-dt-review/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/1531471

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.
Rob Herring (Arm) Sept. 23, 2021, 4:41 p.m. UTC | #2 
On Thu, 23 Sep 2021 01:39:01 +0200, Linus Walleij wrote:
> This converts the NTC thermistor DT bindings to YAML. Some care had to

> be taken since I had to add some illustrations to make the connection

> layouts graspable.

> 

> Cc: Javier Martinez Canillas <javier@dowhile0.org>

> Cc: Johannes Pointner <johannes.pointner@gmail.com>

> Cc: Peter Rosin <peda@axentia.se>

> Cc: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> Cc: devicetree@vger.kernel.org

> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

> ---

> ChangeLog v2->v3:

> - Rebase on v5.15-rc1

> - Drop comment reference to thermal-sensor.yaml

> - Keep the oneOf rather than using an enum for the compatible:

>   I can't figure out how to make deprecated work for enums?

>   https://lore.kernel.org/linux-hwmon/CACRpkdZDLSA5YJtc3XCkfPZUNqo1MOWLBwVDGQ4vN8cDXD3aYg@mail.gmail.com/

> ChangeLog v1->v2:

> - Realize I need to CC devicetree@vger.kernel.org on this.

> - Fix Javier's mail address.

> - Drop Naveen's mail (bouncing)

> ---

>  .../bindings/hwmon/ntc-thermistor.yaml        | 141 ++++++++++++++++++

>  .../bindings/hwmon/ntc_thermistor.txt         |  44 ------

>  2 files changed, 141 insertions(+), 44 deletions(-)

>  create mode 100644 Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml

>  delete mode 100644 Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt

> 


The error introduced can be fixed in a separate patch, so:

Reviewed-by: Rob Herring <robh@kernel.org>
Guenter Roeck Oct. 8, 2021, 12:56 p.m. UTC | #3 
On Thu, Sep 23, 2021 at 01:39:01AM +0200, Linus Walleij wrote:
> This converts the NTC thermistor DT bindings to YAML. Some care had to

> be taken since I had to add some illustrations to make the connection

> layouts graspable.

> 

> Cc: Javier Martinez Canillas <javier@dowhile0.org>

> Cc: Johannes Pointner <johannes.pointner@gmail.com>

> Cc: Peter Rosin <peda@axentia.se>

> Cc: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> Cc: devicetree@vger.kernel.org

> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

> Reviewed-by: Rob Herring <robh@kernel.org>


Applied.

Thanks,
Guenter

> ---

> ChangeLog v2->v3:

> - Rebase on v5.15-rc1

> - Drop comment reference to thermal-sensor.yaml

> - Keep the oneOf rather than using an enum for the compatible:

>   I can't figure out how to make deprecated work for enums?

>   https://lore.kernel.org/linux-hwmon/CACRpkdZDLSA5YJtc3XCkfPZUNqo1MOWLBwVDGQ4vN8cDXD3aYg@mail.gmail.com/

> ChangeLog v1->v2:

> - Realize I need to CC devicetree@vger.kernel.org on this.

> - Fix Javier's mail address.

> - Drop Naveen's mail (bouncing)

> ---

>  .../bindings/hwmon/ntc-thermistor.yaml        | 141 ++++++++++++++++++

>  .../bindings/hwmon/ntc_thermistor.txt         |  44 ------

>  2 files changed, 141 insertions(+), 44 deletions(-)

>  create mode 100644 Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml

>  delete mode 100644 Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt

> 

> diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml

> new file mode 100644

> index 000000000000..9e77cee07dbc

> --- /dev/null

> +++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml

> @@ -0,0 +1,141 @@

> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)

> +---

> +$id: http://devicetree.org/schemas/hwmon/ntc-thermistor.yaml#

> +$schema: http://devicetree.org/meta-schemas/core.yaml#

> +

> +title: NTC thermistor temperature sensors

> +

> +maintainers:

> +  - Naveen Krishna Chatradhi <ch.naveen@samsung.com>

> +  - Linus Walleij <linus.walleij@linaro.org>

> +

> +description: |

> +  Thermistors with negative temperature coefficient (NTC) are resistors that

> +  vary in resistance in an often non-linear way in relation to temperature.

> +  The negative temperature coefficient means that the resistance decreases

> +  as the temperature rises. Since the relationship between resistance and

> +  temperature is non-linear, software drivers most often need to use a look

> +  up table and interpolation to get from resistance to temperature.

> +

> +  When used in practice, a thermistor is often connected between ground, a

> +  pull-up resistor or/and a pull-down resistor and a fixed voltage like this:

> +

> +      + e.g. 5V = pull-up voltage (puv)

> +      |

> +     +-+

> +     | |

> +     | | Pull-up resistor

> +     | | (puo)

> +     +-+

> +      |-------------------------o

> +     +-+ |                      ^

> +     | |/                       |

> +     | /                        |

> +     |/| Thermistor             | Measured voltage (mv)

> +     / |                        | "connected ground"

> +    /| |                        |

> +     +-+                        |

> +      |-------------------------o

> +     +-+                        ^

> +     | |                        |

> +     | | Pull-down resistor     | Measured voltage (mv)

> +     | | (pdo)                  | "connected positive"

> +     +-+                        |

> +      |                         |

> +      |                         v

> +      + GND                     GND

> +

> +  The arrangements of where we measure the voltage over the thermistor are

> +  called "connected ground" and "connected positive" and shall be understood as

> +  the cases when either pull-up or pull-down resistance is zero.

> +

> +  If the pull-up resistance is 0 one end of the thermistor is connected to the

> +  positive voltage and we get the thermistor on top of a pull-down resistor

> +  and we take the measure between the thermistor and the pull-down resistor.

> +

> +  Conversely if the pull-down resistance is zero, one end of the thermistor is

> +  connected to ground and we get the thermistor under the pull-up resistor

> +  and we take the measure between the pull-up resistor and the thermistor.

> +

> +  We can use both pull-up and pull-down resistors at the same time, and then

> +  the figure illustrates where the voltage will be measured for the "connected

> +  ground" and "connected positive" cases.

> +

> +properties:

> +  $nodename:

> +    pattern: "^thermistor(.*)?$"

> +

> +  compatible:

> +    oneOf:

> +      - const: epcos,b57330v2103

> +      - const: epcos,b57891s0103

> +      - const: murata,ncp15wb473

> +      - const: murata,ncp18wb473

> +      - const: murata,ncp21wb473

> +      - const: murata,ncp03wb473

> +      - const: murata,ncp15wl333

> +      - const: murata,ncp03wf104

> +      - const: murata,ncp15xh103

> +      # Deprecated "ntp," compatible strings

> +      - const: ntc,ncp15wb473

> +        deprecated: true

> +      - const: ntc,ncp18wb473

> +        deprecated: true

> +      - const: ntc,ncp21wb473

> +        deprecated: true

> +      - const: ntc,ncp03wb473

> +        deprecated: true

> +      - const: ntc,ncp15wl333

> +        deprecated: true

> +

> +  "#thermal-sensor-cells":

> +    description: Thermal sensor cells if used for thermal sensoring.

> +    const: 0

> +

> +  pullup-uv:

> +    $ref: /schemas/types.yaml#/definitions/uint32

> +    description: Pull-up voltage in micro volts. Must always be specified.

> +

> +  pullup-ohm:

> +    $ref: /schemas/types.yaml#/definitions/uint32

> +    description: Pull-up resistance in ohms. Must always be specified, even

> +      if zero.

> +

> +  pulldown-ohm:

> +    $ref: /schemas/types.yaml#/definitions/uint32

> +    description: Pull-down resistance in ohms. Must always be specified, even

> +      if zero.

> +

> +  connected-positive:

> +    $ref: /schemas/types.yaml#/definitions/flag

> +    description: Indicates how the thermistor is connected in series with

> +      a pull-up and/or a pull-down resistor. See the description above for

> +      an illustration. If this flag is NOT specified, the thermistor is assumed

> +      to be connected-ground, which usually means a pull-down resistance of

> +      zero but complex arrangements are possible.

> +

> +  # See /schemas/iio/adc/adc.yaml

> +  io-channels:

> +    maxItems: 1

> +    description: IIO ADC channel to read the voltage over the resistor. Must

> +      always be specified.

> +

> +required:

> +  - compatible

> +  - pullup-uv

> +  - pullup-ohm

> +  - pulldown-ohm

> +  - io-channels

> +

> +additionalProperties: false

> +

> +examples:

> +  - |

> +    thermistor0 {

> +      compatible = "murata,ncp18wb473";

> +      io-channels = <&gpadc 0x06>;

> +      pullup-uv = <1800000>;

> +      pullup-ohm = <220000>;

> +      pulldown-ohm = <0>;

> +      #thermal-sensor-cells = <0>;

> +    };

> diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt

> deleted file mode 100644

> index 4c5c3712970e..000000000000

> --- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt

> +++ /dev/null

> @@ -1,44 +0,0 @@

> -NTC Thermistor hwmon sensors

> --------------------------------

> -

> -Requires node properties:

> -- "compatible" value : one of

> -	"epcos,b57330v2103"

> -	"epcos,b57891s0103"

> -	"murata,ncp15wb473"

> -	"murata,ncp18wb473"

> -	"murata,ncp21wb473"

> -	"murata,ncp03wb473"

> -	"murata,ncp15wl333"

> -	"murata,ncp03wf104"

> -	"murata,ncp15xh103"

> -

> -/* Usage of vendor name "ntc" is deprecated */

> -<DEPRECATED>	"ntc,ncp15wb473"

> -<DEPRECATED>	"ntc,ncp18wb473"

> -<DEPRECATED>	"ntc,ncp21wb473"

> -<DEPRECATED>	"ntc,ncp03wb473"

> -<DEPRECATED>	"ntc,ncp15wl333"

> -

> -- "pullup-uv"	Pull up voltage in micro volts

> -- "pullup-ohm"	Pull up resistor value in ohms

> -- "pulldown-ohm" Pull down resistor value in ohms

> -- "connected-positive" Always ON, If not specified.

> -		Status change is possible.

> -- "io-channels"	Channel node of ADC to be used for

> -		conversion.

> -

> -Optional node properties:

> -- "#thermal-sensor-cells" Used to expose itself to thermal fw.

> -

> -Read more about iio bindings at

> -	https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/

> -

> -Example:

> -	ncp15wb473@0 {

> -		compatible = "murata,ncp15wb473";

> -		pullup-uv = <1800000>;

> -		pullup-ohm = <47000>;

> -		pulldown-ohm = <0>;

> -		io-channels = <&adc 3>;

> -	};
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml
new file mode 100644
index 000000000000..9e77cee07dbc
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml
@@ -0,0 +1,141 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+---
+$id: http://devicetree.org/schemas/hwmon/ntc-thermistor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NTC thermistor temperature sensors
+
+maintainers:
+  - Naveen Krishna Chatradhi <ch.naveen@samsung.com>
+  - Linus Walleij <linus.walleij@linaro.org>
+
+description: |
+  Thermistors with negative temperature coefficient (NTC) are resistors that
+  vary in resistance in an often non-linear way in relation to temperature.
+  The negative temperature coefficient means that the resistance decreases
+  as the temperature rises. Since the relationship between resistance and
+  temperature is non-linear, software drivers most often need to use a look
+  up table and interpolation to get from resistance to temperature.
+
+  When used in practice, a thermistor is often connected between ground, a
+  pull-up resistor or/and a pull-down resistor and a fixed voltage like this:
+
+      + e.g. 5V = pull-up voltage (puv)
+      |
+     +-+
+     | |
+     | | Pull-up resistor
+     | | (puo)
+     +-+
+      |-------------------------o
+     +-+ |                      ^
+     | |/                       |
+     | /                        |
+     |/| Thermistor             | Measured voltage (mv)
+     / |                        | "connected ground"
+    /| |                        |
+     +-+                        |
+      |-------------------------o
+     +-+                        ^
+     | |                        |
+     | | Pull-down resistor     | Measured voltage (mv)
+     | | (pdo)                  | "connected positive"
+     +-+                        |
+      |                         |
+      |                         v
+      + GND                     GND
+
+  The arrangements of where we measure the voltage over the thermistor are
+  called "connected ground" and "connected positive" and shall be understood as
+  the cases when either pull-up or pull-down resistance is zero.
+
+  If the pull-up resistance is 0 one end of the thermistor is connected to the
+  positive voltage and we get the thermistor on top of a pull-down resistor
+  and we take the measure between the thermistor and the pull-down resistor.
+
+  Conversely if the pull-down resistance is zero, one end of the thermistor is
+  connected to ground and we get the thermistor under the pull-up resistor
+  and we take the measure between the pull-up resistor and the thermistor.
+
+  We can use both pull-up and pull-down resistors at the same time, and then
+  the figure illustrates where the voltage will be measured for the "connected
+  ground" and "connected positive" cases.
+
+properties:
+  $nodename:
+    pattern: "^thermistor(.*)?$"
+
+  compatible:
+    oneOf:
+      - const: epcos,b57330v2103
+      - const: epcos,b57891s0103
+      - const: murata,ncp15wb473
+      - const: murata,ncp18wb473
+      - const: murata,ncp21wb473
+      - const: murata,ncp03wb473
+      - const: murata,ncp15wl333
+      - const: murata,ncp03wf104
+      - const: murata,ncp15xh103
+      # Deprecated "ntp," compatible strings
+      - const: ntc,ncp15wb473
+        deprecated: true
+      - const: ntc,ncp18wb473
+        deprecated: true
+      - const: ntc,ncp21wb473
+        deprecated: true
+      - const: ntc,ncp03wb473
+        deprecated: true
+      - const: ntc,ncp15wl333
+        deprecated: true
+
+  "#thermal-sensor-cells":
+    description: Thermal sensor cells if used for thermal sensoring.
+    const: 0
+
+  pullup-uv:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Pull-up voltage in micro volts. Must always be specified.
+
+  pullup-ohm:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Pull-up resistance in ohms. Must always be specified, even
+      if zero.
+
+  pulldown-ohm:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Pull-down resistance in ohms. Must always be specified, even
+      if zero.
+
+  connected-positive:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: Indicates how the thermistor is connected in series with
+      a pull-up and/or a pull-down resistor. See the description above for
+      an illustration. If this flag is NOT specified, the thermistor is assumed
+      to be connected-ground, which usually means a pull-down resistance of
+      zero but complex arrangements are possible.
+
+  # See /schemas/iio/adc/adc.yaml
+  io-channels:
+    maxItems: 1
+    description: IIO ADC channel to read the voltage over the resistor. Must
+      always be specified.
+
+required:
+  - compatible
+  - pullup-uv
+  - pullup-ohm
+  - pulldown-ohm
+  - io-channels
+
+additionalProperties: false
+
+examples:
+  - |
+    thermistor0 {
+      compatible = "murata,ncp18wb473";
+      io-channels = <&gpadc 0x06>;
+      pullup-uv = <1800000>;
+      pullup-ohm = <220000>;
+      pulldown-ohm = <0>;
+      #thermal-sensor-cells = <0>;
+    };
diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt
deleted file mode 100644
index 4c5c3712970e..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt
+++ /dev/null
@@ -1,44 +0,0 @@ 
-NTC Thermistor hwmon sensors
--------------------------------
-
-Requires node properties:
-- "compatible" value : one of
-	"epcos,b57330v2103"
-	"epcos,b57891s0103"
-	"murata,ncp15wb473"
-	"murata,ncp18wb473"
-	"murata,ncp21wb473"
-	"murata,ncp03wb473"
-	"murata,ncp15wl333"
-	"murata,ncp03wf104"
-	"murata,ncp15xh103"
-
-/* Usage of vendor name "ntc" is deprecated */
-<DEPRECATED>	"ntc,ncp15wb473"
-<DEPRECATED>	"ntc,ncp18wb473"
-<DEPRECATED>	"ntc,ncp21wb473"
-<DEPRECATED>	"ntc,ncp03wb473"
-<DEPRECATED>	"ntc,ncp15wl333"
-
-- "pullup-uv"	Pull up voltage in micro volts
-- "pullup-ohm"	Pull up resistor value in ohms
-- "pulldown-ohm" Pull down resistor value in ohms
-- "connected-positive" Always ON, If not specified.
-		Status change is possible.
-- "io-channels"	Channel node of ADC to be used for
-		conversion.
-
-Optional node properties:
-- "#thermal-sensor-cells" Used to expose itself to thermal fw.
-
-Read more about iio bindings at
-	https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/
-
-Example:
-	ncp15wb473@0 {
-		compatible = "murata,ncp15wb473";
-		pullup-uv = <1800000>;
-		pullup-ohm = <47000>;
-		pulldown-ohm = <0>;
-		io-channels = <&adc 3>;
-	};