Re: [PATCH 2/3] dt-bindings: iio: temperature: ltc2983: support more parts

[Krzysztof Kozlowski]

On 17/10/2022 02:53, Cosmin Tanislav wrote:
> 
> 
> On 10/17/22 04:59, Krzysztof Kozlowski wrote:
>> On 14/10/2022 08:37, Cosmin Tanislav wrote:
>>> From: Cosmin Tanislav <cosmin.tanislav@xxxxxxxxxx>
>>>
>>> Add support for the following parts:
>>>   * LTC2984
>>>   * LTC2986
>>>   * LTM2985
>>>
>>> The LTC2984 is a variant of the LTC2983 with EEPROM.
>>> The LTC2986 is a variant of the LTC2983 with only 10 channels,
>>> EEPROM and support for active analog temperature sensors.
>>> The LTM2985 is software-compatible with the LTC2986.
>>>
>>> Signed-off-by: Cosmin Tanislav <cosmin.tanislav@xxxxxxxxxx>
>>> ---
>>>   .../bindings/iio/temperature/adi,ltc2983.yaml | 63 +++++++++++++++++--
>>>   1 file changed, 59 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml
>>> index 722781aa4697..c33ab524fb64 100644
>>> --- a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml
>>> +++ b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml
>>> @@ -4,19 +4,27 @@
>>>   $id: http://devicetree.org/schemas/iio/temperature/adi,ltc2983.yaml#
>>>   $schema: http://devicetree.org/meta-schemas/core.yaml#
>>>   
>>> -title: Analog Devices LTC2983 Multi-sensor Temperature system
>>> +title: Analog Devices LTC2983, LTC2986, LTM2985 Multi-sensor Temperature system
>>>   
>>>   maintainers:
>>>     - Nuno Sá <nuno.sa@xxxxxxxxxx>
>>>   
>>>   description: |
>>> -  Analog Devices LTC2983 Multi-Sensor Digital Temperature Measurement System
>>> +  Analog Devices LTC2983, LTC2984, LTC2986, LTM2985 Multi-Sensor Digital
>>> +  Temperature Measurement Systems
>>> +
>>>     https://www.analog.com/media/en/technical-documentation/data-sheets/2983fc.pdf
>>> +  https://www.analog.com/media/en/technical-documentation/data-sheets/2984fb.pdf
>>> +  https://www.analog.com/media/en/technical-documentation/data-sheets/29861fa.pdf
>>> +  https://www.analog.com/media/en/technical-documentation/data-sheets/ltm2985.pdf
>>>   
>>>   properties:
>>>     compatible:
>>>       enum:
>>>         - adi,ltc2983
>>> +      - adi,ltc2984
>>> +      - adi,ltc2986
>>> +      - adi,ltm2985
>>>   
>>>     reg:
>>>       maxItems: 1
>>> @@ -26,7 +34,7 @@ properties:
>>>   
>>>     adi,mux-delay-config-us:
>>>       description:
>>> -      The LTC2983 performs 2 or 3 internal conversion cycles per temperature
>>> +      The device 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
>>> @@ -145,7 +153,7 @@ patternProperties:
>>>         adi,three-conversion-cycles:
>>>           description:
>>>             Boolean property which set's three conversion cycles removing
>>> -          parasitic resistance effects between the LTC2983 and the diode.
>>> +          parasitic resistance effects between the device and the diode.
>>>           type: boolean
>>>   
>>>         adi,average-on:
>>> @@ -353,6 +361,41 @@ patternProperties:
>>>           description: Boolean property which set's the adc as single-ended.
>>>           type: boolean
>>>   
>>> +  "^temp@":
>>
>> There is already a property for thermocouple. Isn't a thermocouple a
>> temperature sensor? IOW, why new property is needed?
>>
> This node is needed for active analog temperature sensors.
> It has fewer options than the thermocouple, as it only supports
> a table to map from voltage to temperature and specifying whether
> the measurement is differential or single-ended.
> 
> If you did as much as glimpsed at the datasheet you would have
> understood.

We receive a lot of bindings to review. If I glimpse through every
datasheet, when would I work?

Instead of expecting reviewer to dive into datasheets for this one
particular sensor, make it explicit in commit msg.

> 
>>> +    type: object
>>> +    description:
>>> +      Represents a channel which is being used as an active analog temperature
>>> +      sensor.
>>> +
>>> +    properties:
>>> +      adi,sensor-type:
>>> +        description:
>>> +          Identifies the sensor as an active analog temperature sensor.
>>> +        $ref: /schemas/types.yaml#/definitions/uint32
>>> +        const: 31
>>> +
>>> +      adi,single-ended:
>>> +        description: Boolean property which sets the sensor as single-ended.
>>
>> Drop "Boolean property which sets" - it's obvious from the type.
>>
> 
> That's how the rest of the file is written.

Not really an argument... You can correct the other pieces in separate
patch.

> 
>>
>>
>>> +        type: boolean
>>> +
>>> +      adi,custom-temp:
>>> +        description:
>>> +          This is a table, where each entry should be a pair of
>>
>> "This is a table" - obvious from the type.
>>
> 
> That's how the rest of the file is written.
> 
>>> +          voltage(mv)-temperature(K). The entries must be given in nv and uK
>>
>> mv-K or nv-uK? Confusing...
> 
> That's how the rest of the file is written.

The same.

> 
> The chip uses mv-K, but the binding specifies nv-uK, the driver
> translates it into the appropriate unit.

It does not matter here, what the driver is doing. Use only one unit
here, matching the DTS.

> 
>>
>>> +          so that, the original values must be multiplied by 1000000. For
>>> +          more details look at table 71 and 72.
>>
>> There is no table 71 in the bindings... It seems you pasted it from
>> somewhere.
>>
> 
> It's pretty obvious that "Table" in a binding refers to the datasheet.

There are multiple datasheets and how would I know to which one this refers?

> But if you meant datasheet, not binding, you're looking at the wrong
> datasheet then.
> Also, that's how the rest of the file is written.

Not really an argument... Poor examples like to spread, it's an effort
to drop them.

> 
>>> +          Note should be signed, but dtc doesn't currently maintain the
>>> +          sign.
>>
>> What do you mean? "Maintain" as allow or keep when building FDT?  What's
>> the problem of using negative numbers here and why it should be part of
>> bindings?
>>
> 
> You're really clueless, I'll let you figure it out on your own.

Yes, I am clueless and that's not the way how the review conversation
should look like.

NAK.

> Also, that's how the rest of the file is written.
> 
>>> +        $ref: /schemas/types.yaml#/definitions/uint64-matrix
>>> +        minItems: 3
>>> +        maxItems: 64
>>> +        items:
>>> +          minItems: 2
>>> +          maxItems: 2
>>
>> Instead describe the items with "description" (and maybe constraints)
>> like here:
>>
>> https://elixir.bootlin.com/linux/v5.19/source/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml#L278
>>
> 
> That's how the rest of the file is written.
> If you really want to use something different, you can submit a
> patch later and fix the whole binding however you want.

Nope. I expect the new pieces to be correct, not incorrect because
"there is already poor pattern, so I will do the same".

If inconsistency bothers you, anyone can fix it in following up patch.
Also you.

Best regards,
Krzysztof