Re: [PATCH v3 2/4] dt-bindings: iio: temperature: ltc2983: refine

From: Cosmin Tanislav
Date: Thu Oct 27 2022 - 03:49:46 EST


On Wed, 2022-10-26 at 15:03 -0500, Rob Herring wrote:
> On Tue, Oct 25, 2022 at 11:18:40AM +0300, Cosmin Tanislav wrote:
> > From: Cosmin Tanislav <cosmin.tanislav@xxxxxxxxxx>
>
> 'refine' is not a great subject. That's due to doing many things in 1
> patch. I'd at least split out all the 'description' changes from
> actual
> schema changes to separate patches.
>
> >
> >  * make sure addresses are represented as hex
> >  * add note about wrong unit value for adi,mux-delay-config-us
> >  * simplify descriptions
> >  * add descriptions for the items of custom sensor tables
> >  * add default property values where applicable
> >  * use conditionals to extend minimum reg value
> >    for single ended sensors
> >  * remove " around phandle schema $ref
> >  * remove label from example and use generic temperature
> >    sensor name
> >
> > Signed-off-by: Cosmin Tanislav <cosmin.tanislav@xxxxxxxxxx>
> > ---
> >  .../bindings/iio/temperature/adi,ltc2983.yaml | 270 ++++++++++----
> > ----
> >  1 file changed, 144 insertions(+), 126 deletions(-)
> >
> > diff --git
> > a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yam
> > l
> > b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yam
> > l
> > index 722781aa4697..a878fd84636f 100644
> > ---
> > a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yam
> > l
> > +++
> > b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yam
> > l
> > @@ -26,25 +26,25 @@ properties:
> >  
> >    adi,mux-delay-config-us:
> >      description:
> > -      The LTC2983 performs 2 or 3 internal conversion cycles per
> > temperature
> > -      result. Each conversion cycle is performed with different
> > excitation and
> > -      input multiplexer configurations. Prior to each conversion,
> > these
> > -      excitation circuits and input switch configurations are
> > changed and an
> > -      internal 1ms delay ensures settling prior to the conversion
> > cycle in most
> > -      cases. An extra delay can be configured using this property.
> > The value is
> > -      rounded to nearest 100us.
> > +      Extra delay prior to each conversion, in addition to the
> > internal 1ms
> > +      delay, for the multiplexer to switch input configurations
> > and
> > +      excitation values.
> > +
> > +      This property is supposed to be in microseconds, but to
> > maintain
> > +      compatibility, this value will be multiplied by 100 before
> > usage.
>
> You need '|' for the block if you want to retain formatting.
>
> >      maximum: 255
> > +    default: 0
> >  
> >    adi,filter-notch-freq:
> >      description:
> > -      Set's the default setting of the digital filter. The default
> > is
> > -      simultaneous 50/60Hz rejection.
> > +      Notch frequency of the digital filter.
> >        0 - 50/60Hz rejection
> >        1 - 60Hz rejection
> >        2 - 50Hz rejection
> >      $ref: /schemas/types.yaml#/definitions/uint32
> >      minimum: 0
> >      maximum: 2
> > +    default: 0
> >  
> >    '#address-cells':
> >      const: 1
> > @@ -53,19 +53,19 @@ properties:
> >      const: 0
> >  
> >  patternProperties:
> > -  "@([1-9]|1[0-9]|20)$":
> > +  "@([0-9a-f]+)$":
>
> Before 1-20 was supported which matched 'reg' and now there is no
> limit.
> However, you did fix that the unit address should be hex. So it
> should
> be:
>
> "@([1-9a-f]|1[0-4])$"
>

The address is supposed to match reg, isn't it?
I made it unlimited because there's no way to modify the node name of
the patternProperty conditionally, so parts with 10 channels will be
invalid anyway.


> >      type: object
> > -
> > +    description: Sensor.
> >      properties:
> >        reg:
> >          description:
> > -          The channel number. It can be connected to one of the 20
> > channels of
> > -          the device.
> > +          Channel number. Connects the sensor to the channel with
> > this number
> > +          of the device.
> >          minimum: 1
> >          maximum: 20
> >  
> >        adi,sensor-type:
> > -        description: Identifies the type of sensor connected to
> > the device.
> > +        description: Type of sensor connected to the device.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >  
> >      required:
> > @@ -74,10 +74,7 @@ patternProperties:
> >  
> >    "^thermocouple@":
> >      type: object
> > -    description:
> > -      Represents a thermocouple sensor which is connected to one
> > of the device
> > -      channels.
> > -
>
> Keep the blank line.
>
> > +    description: Thermocouple sensor.
> >      properties:
> >        adi,sensor-type:
> >          description: |
> > @@ -95,87 +92,86 @@ patternProperties:
> >          maximum: 9
> >  
> >        adi,single-ended:
> > -        description:
> > -          Boolean property which set's the thermocouple as single-
> > ended.
> > +        description: Whether the sensor is single-ended.
> >          type: boolean
> >  
> >        adi,sensor-oc-current-microamp:
> > -        description:
> > -          This property set's the pulsed current value applied
> > during
> > -          open-circuit detect.
> > +        description: Pulsed current value applied during open-
> > circuit detect.
> >          enum: [10, 100, 500, 1000]
> > +        default: 10
> >  
> >        adi,cold-junction-handle:
> >          description:
> > -          Phandle which points to a sensor object responsible for
> > measuring
> > -          the thermocouple cold junction temperature.
> > -        $ref: "/schemas/types.yaml#/definitions/phandle"
> > +          Sensor responsible for measuring the thermocouple cold
> > junction
> > +          temperature.
> > +        $ref: /schemas/types.yaml#/definitions/phandle
> >  
> >        adi,custom-thermocouple:
> >          description:
> > -          This is a table, where each entry should be a pair of
> > -          voltage(mv)-temperature(K). The entries must be given in
> > nv and uK
> > -          so that, the original values must be multiplied by
> > 1000000. For
> > -          more details look at table 69 and 70.
> > -          Note should be signed, but dtc doesn't currently
> > maintain the
> > -          sign.
> > +          Used for digitizing custom thermocouples.
> > +          See Page 59 of the datasheet.
> >          $ref: /schemas/types.yaml#/definitions/uint64-matrix
> >          minItems: 3
> >          maxItems: 64
> >          items:
> > -          minItems: 2
> > -          maxItems: 2
> > +          items:
> > +            - description: Voltage point in nV, signed.
> > +            - description: Temperature point in uK.
> > +
> > +    allOf:
> > +      - if:
> > +          properties:
> > +            adi,sensor-type:
> > +              const: 9
> > +        then:
> > +          required:
> > +            - adi,custom-thermocouple
> >  
> >    "^diode@":
> >      type: object
> > -    description:
> > -      Represents a diode sensor which is connected to one of the
> > device
> > -      channels.
> > -
> > +    description: Diode sensor.
> >      properties:
> >        adi,sensor-type:
> > -        description: Identifies the sensor as a diode.
> > +        description: Sensor type for diodes.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >          const: 28
> >  
> >        adi,single-ended:
> > -        description: Boolean property which set's the diode as
> > single-ended.
> > +        description: Whether the sensor is single-ended.
> >          type: boolean
> >  
> >        adi,three-conversion-cycles:
> >          description:
> > -          Boolean property which set's three conversion cycles
> > removing
> > -          parasitic resistance effects between the LTC2983 and the
> > diode.
> > +          Whether to use three conversion cycles to remove
> > parasitic
> > +          resistance between the device and the diode.
> >          type: boolean
> >  
> >        adi,average-on:
> >          description:
> > -          Boolean property which enables a running average of the
> > diode
> > -          temperature reading. This reduces the noise when the
> > diode is used
> > -          as a cold junction temperature element on an isothermal
> > block
> > -          where temperatures change slowly.
> > +          Whether to use a running average of the diode
> > temperature
> > +          reading to reduce the noise when the diode is used as a
> > cold
> > +          junction temperature element on an isothermal block
> > where
> > +          temperatures change slowly.
> >          type: boolean
> >  
> >        adi,excitation-current-microamp:
> >          description:
> > -          This property controls the magnitude of the excitation
> > current
> > -          applied to the diode. Depending on the number of
> > conversions
> > -          cycles, this property will assume different predefined
> > values on
> > -          each cycle. Just set the value of the first cycle (1l).
> > +          Magnitude of the 1l excitation current applied to the
> > diode.
> > +          4l excitation current will be 4 times this value, and 8l
> > +          excitation current will be 8 times value.
> >          enum: [10, 20, 40, 80]
> > +        default: 10
> >  
> >        adi,ideal-factor-value:
> >          description:
> > -          This property sets the diode ideality factor. The real
> > value must
> > -          be multiplied by 1000000 to remove the fractional part.
> > For more
> > -          information look at table 20 of the datasheet.
> > +          Diode ideality factor.
> > +          Set this property to 1000000 times the real value.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> > +        default: 0
> >  
> >    "^rtd@":
> >      type: object
> > -    description:
> > -      Represents a rtd sensor which is connected to one of the
> > device channels.
> > -
> > +    description: RTD sensor.
>
> Keep the blank line. And any other case.
>
> >      properties:
> >        reg:
> >          minimum: 2
> > @@ -197,56 +193,57 @@ patternProperties:
> >          maximum: 18
> >  
> >        adi,rsense-handle:
> > -        description:
> > -          Phandle pointing to a rsense object associated with this
> > RTD.
> > -        $ref: "/schemas/types.yaml#/definitions/phandle"
> > +        description: Associated sense resistor sensor.
> > +        $ref: /schemas/types.yaml#/definitions/phandle
> >  
> >        adi,number-of-wires:
> >          description:
> > -          Identifies the number of wires used by the RTD. Setting
> > this
> > -          property to 5 means 4 wires with Kelvin Rsense.
> > +          Number of wires used by the RTD.
> > +          5 means 4 wires with Kelvin sense resistor.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >          enum: [2, 3, 4, 5]
> > +        default: 2
> >  
> >        adi,rsense-share:
> >          description:
> > -          Boolean property which enables Rsense sharing, where one
> > sense
> > -          resistor is used for multiple 2-, 3-, and/or 4-wire
> > RTDs.
> > +          Whether to enable sense resistor sharing, where one
> > sense
> > +          resistor is used by multiple sensors.
> >          type: boolean
> >  
> >        adi,current-rotate:
> >          description:
> > -          Boolean property which enables excitation current
> > rotation to
> > -          automatically remove parasitic thermocouple effects.
> > Note that
> > -          this property is not allowed for 2- and 3-wire RTDs.
> > +          Whether to enable excitation current rotation to
> > automatically
> > +          remove parasitic thermocouple effects.
> >          type: boolean
> >  
> >        adi,excitation-current-microamp:
> > -        description:
> > -          This property controls the magnitude of the excitation
> > current
> > -          applied to the RTD.
> > +        description: Excitation current applied to the RTD.
> >          enum: [5, 10, 25, 50, 100, 250, 500, 1000]
> > +        default: 5
> >  
> >        adi,rtd-curve:
> >          description:
> > -          This property set the RTD curve used and the
> > corresponding
> > -          Callendar-VanDusen constants. Look at table 30 of the
> > datasheet.
> > +          RTD curve and the corresponding Callendar-VanDusen
> > constants.
> > +          0 - European
> > +          1 - American
> > +          2 - Japanese
> > +          3 - ITS-90
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >          minimum: 0
> >          maximum: 3
> > +        default: 0
> >  
> >        adi,custom-rtd:
> >          description:
> > -          This is a table, where each entry should be a pair of
> > -          resistance(ohm)-temperature(K). The entries added here
> > are in uohm
> > -          and uK. For more details values look at table 74 and 75.
> > +          Used for digitizing custom RTDs.
> > +          See Page 62 of the datasheet.
> >          $ref: /schemas/types.yaml#/definitions/uint64-matrix
> > +        minItems: 3
> > +        maxItems: 64
> >          items:
> > -          minItems: 3
> > -          maxItems: 64
> >            items:
> > -            minItems: 2
> > -            maxItems: 2
> > +            - description: Resistance point in uOhms.
> > +            - description: Temperature point in uK.
> >  
> >      required:
> >        - adi,rsense-handle
> > @@ -254,12 +251,25 @@ patternProperties:
> >      dependencies:
> >        adi,current-rotate: [ "adi,rsense-share" ]
> >  
> > +    allOf:
> > +      - if:
> > +          properties:
> > +            adi,number-of-wires:
> > +              enum: [2, 3]
>
> This is also true if adi,number-of-wires is not present. You need
> 'required' if that's not ensured already. (Unless this was
> intentional)
>
> > +        then:
> > +          properties:
> > +            adi,current-rotate: false
> > +      - if:
> > +          properties:
> > +            adi,sensor-type:
> > +              const: 18
> > +        then:
> > +          required:
> > +            - adi,custom-rtd
> > +
> >    "^thermistor@":
> >      type: object
> > -    description:
> > -      Represents a thermistor sensor which is connected to one of
> > the device
> > -      channels.
> > -
> > +    description: Thermistor sensor.
> >      properties:
> >        adi,sensor-type:
> >          description:
> > @@ -277,61 +287,53 @@ patternProperties:
> >          maximum: 27
> >  
> >        adi,rsense-handle:
> > -        description:
> > -          Phandle pointing to a rsense object associated with this
> > -          thermistor.
> > -        $ref: "/schemas/types.yaml#/definitions/phandle"
> > +        description: Associated sense resistor sensor.
> > +        $ref: /schemas/types.yaml#/definitions/phandle
> >  
> >        adi,single-ended:
> > -        description:
> > -          Boolean property which set's the thermistor as single-
> > ended.
> > +        description: Whether the sensor is single-ended.
> >          type: boolean
> >  
> >        adi,rsense-share:
> >          description:
> > -          Boolean property which enables Rsense sharing, where one
> > sense
> > -          resistor is used for multiple thermistors. Note that
> > this property
> > -          is ignored if adi,single-ended is set.
> > +          Whether to enable sense resistor sharing, where one
> > sense
> > +          resistor is used by multiple sensors.
> >          type: boolean
> >  
> >        adi,current-rotate:
> >          description:
> > -          Boolean property which enables excitation current
> > rotation to
> > -          automatically remove parasitic thermocouple effects.
> > +          Whether to enable excitation current rotation to
> > automatically
> > +          remove parasitic thermocouple effects.
> >          type: boolean
> >  
> >        adi,excitation-current-nanoamp:
> >          description:
> > -          This property controls the magnitude of the excitation
> > current
> > -          applied to the thermistor. Value 0 set's the sensor in
> > auto-range
> > -          mode.
> > +          Excitation current applied to the thermistor.
> > +          0 sets the sensor in auto-range mode.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >          enum: [0, 250, 500, 1000, 5000, 10000, 25000, 50000,
> > 100000, 250000,
> >                 500000, 1000000]
> > +        default: 0
> > +
> > +      adi,custom-steinhart:
> > +        description:
> > +          Steinhart-Hart coefficients in raw format, used for
> > digitizing
> > +          custom thermistors.
> > +          See Page 68 of the datasheet.
> > +        $ref: /schemas/types.yaml#/definitions/uint32-array
> > +        maxItems: 6
> >  
> >        adi,custom-thermistor:
> >          description:
> > -          This is a table, where each entry should be a pair of
> > -          resistance(ohm)-temperature(K). The entries added here
> > are in uohm
> > -          and uK only for custom thermistors. For more details
> > look at table
> > -          78 and 79.
> > +          Used for digitizing custom thermistors.
> > +          See Page 65 of the datasheet.
> >          $ref: /schemas/types.yaml#/definitions/uint64-matrix
> >          minItems: 3
> >          maxItems: 64
> >          items:
> > -          minItems: 2
> > -          maxItems: 2
> > -
> > -      adi,custom-steinhart:
> > -        description:
> > -          Steinhart-Hart coefficients are also supported and can
> > -          be programmed into the device memory using this
> > property. For
> > -          Steinhart sensors the coefficients are given in the raw
> > -          format. Look at table 82 for more information.
> > -        $ref: /schemas/types.yaml#/definitions/uint32-array
> > -        items:
> > -          minItems: 6
> > -          maxItems: 6
> > +          items:
> > +            - description: Resistance point in uOhms.
> > +            - description: Temperature point in uK.
> >  
> >      required:
> >        - adi,rsense-handle
> > @@ -339,40 +341,56 @@ patternProperties:
> >      dependencies:
> >        adi,current-rotate: [ "adi,rsense-share" ]
> >  
> > +    allOf:
> > +      - if:
> > +          properties:
> > +            adi,sensor-type:
> > +              const: 26
> > +        then:
> > +          properties:
> > +            adi,excitation-current-nanoamp:
> > +              default: 1000
> > +          required:
> > +            - adi,custom-steinhart
> > +      - if:
> > +          properties:
> > +            adi,sensor-type:
> > +              const: 27
> > +        then:
> > +          properties:
> > +            adi,excitation-current-nanoamp:
> > +              default: 1000
> > +          required:
> > +            - adi,custom-thermistor
> > +
> >    "^adc@":
> >      type: object
> > -    description: Represents a channel which is being used as a
> > direct adc.
> > -
> > +    description: Direct ADC sensor.
> >      properties:
> >        adi,sensor-type:
> > -        description: Identifies the sensor as a direct adc.
> > +        description: Sensor type for direct ADC sensors.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >          const: 30
> >  
> >        adi,single-ended:
> > -        description: Boolean property which set's the adc as
> > single-ended.
> > +        description: Whether the sensor is single-ended.
> >          type: boolean
> >  
> >    "^rsense@":
> >      type: object
> > -    description:
> > -      Represents a rsense which is connected to one of the device
> > channels.
> > -      Rsense are used by thermistors and RTD's.
> > -
> > +    description: Sense resistor sensor.
> >      properties:
> >        reg:
> >          minimum: 2
> >          maximum: 20
> >  
> >        adi,sensor-type:
> > -        description: Identifies the sensor as a rsense.
> > +        description: Sensor type sense resistor sensors.
> >          $ref: /schemas/types.yaml#/definitions/uint32
> >          const: 29
> >  
> >        adi,rsense-val-milli-ohms:
> > -        description:
> > -          Sets the value of the sense resistor. Look at table 20
> > of the
> > -          datasheet for information.
> > +        description: Value of the sense resistor.
> >  
> >      required:
> >        - adi,rsense-val-milli-ohms
> > @@ -391,7 +409,7 @@ examples:
> >          #address-cells = <1>;
> >          #size-cells = <0>;
> >  
> > -        sensor_ltc2983: ltc2983@0 {
> > +        temp@0 {
> >                  compatible = "adi,ltc2983";
> >                  reg = <0>;
> >  
> > --
> > 2.38.1
> >
> >