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

[Guenter Roeck <linux@roeck-us.net>]

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>;
> -	};