[v1,1/2] dt-bindings: iio: adc: adding dt-bindings for PAC193X

From: Marius Cristea <marius.cristea@microchip.com>

This is the device tree schema for iio driver for
Microchip PAC193X series of Power Monitors with Accumulator.

Signed-off-by: Marius Cristea <marius.cristea@microchip.com>
---
 .../bindings/iio/adc/microchip,pac193x.yaml   | 122 ++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml

On 20/02/2023 13:32, marius.cristea@microchip.com wrote:
> From: Marius Cristea <marius.cristea@microchip.com>

Subject: drop second/last, redundant "dt-bindings for". The
"dt-bindings" prefix is already stating that these are bindings.

> 
> This is the device tree schema for iio driver for
> Microchip PAC193X series of Power Monitors with Accumulator.

Do not use "This commit/patch".
https://elixir.bootlin.com/linux/v5.17.1/source/Documentation/process/submitting-patches.rst#L95

Use imperative - also for subject.

Please use scripts/get_maintainers.pl to get a list of necessary people
and lists to CC.  It might happen, that command when run on an older
kernel, gives you outdated entries.  Therefore please be sure you base
your patches on recent Linux kernel.


> 
> Signed-off-by: Marius Cristea <marius.cristea@microchip.com>
> ---
>  .../bindings/iio/adc/microchip,pac193x.yaml   | 122 ++++++++++++++++++
>  1 file changed, 122 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml
> new file mode 100644
> index 000000000000..e4ea560991e9
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml
> @@ -0,0 +1,122 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/microchip,pac193x.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Microchip PAC193X Power Monitors with Accumulator
> +
> +maintainers:
> +  - Marius Cristea <marius.cristea@microchip.com>
> +
> +properties:
> +  compatible:
> +    enum:
> +      - microchip,pac1934
> +      - microchip,pac1933
> +      - microchip,pac1932
> +      - microchip,pac1931

Maybe order these numerically (ascending)?

> +
> +  reg:
> +    maxItems: 1
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 0
> +
> +  microchip,samp-rate:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: Sampling rate for all device's channels.

What are the units? rate is usually in hz, which should be expressed in
unit suffix (property name)

> +    enum: [8, 64, 256, 1024]
> +    default: 1024
> +
> +required:

required goes after all properties, so after patternProperties

> +  - compatible
> +  - reg
> +  - microchip,samp-rate
> +  - "#address-cells"
> +  - "#size-cells"
> +
> +patternProperties:
> +  "^channel([1-4])@[1-4]+$":

Why first reg-pattern ([1-4])? For what do you need it?

> +    $ref: "adc.yaml"

Drop quotes

> +    type: object
> +    description: Represents the external channels which are connected to the ADC.
> +
> +    properties:
> +      reg:
> +        description: The channel number.
> +          It can have up to 4 channels, numbered from 1 to 4.
> +        items:
> +          - minimum: 1
> +            maximum: 4
> +
> +      microchip,uohms-shunt-res:

Not a correct unit suffix. Use standard properties:
git grep shunt -- Documentation/devicetree/


> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: |
> +          Value in micro Ohms of the shunt resistor connected between
> +          the SENSE+ and SENSE- inputs, across which the current is measured. Value
> +          is needed to compute the scaling of the measured current.
> +
> +      microchip,rail-name:
> +        $ref: /schemas/types.yaml#/definitions/string
> +        description: Name of the monitored power rail.

Why do you need it? Why this is a property of DT? Aren't you now
duplicating label?

> +
> +      microchip,bi-directional:
> +        description: Whether the channel is bi-directional.

Describe here what is a "bi-directional" channel for ADC... Maybe it is
obvious, maybe not. For me it is not and none of other devices have it.

> +        type: boolean
> +
> +    required:
> +      - reg
> +      - microchip,uohms-shunt-res
> +      - microchip,rail-name
> +
> +    additionalProperties: false
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        pac193x: pac193x@10 {

Node names should be generic.
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation

> +            compatible = "microchip,pac1934";
> +            reg = <0x10>;
> +
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            microchip,samp-rate = <64>;
> +
> +            channel1@1 {

1@1 is for sure not generic...



Best regards,
Krzysztof

Hi Marius

Welcome to IIO.

I'll comment on top of Krzystof's review to avoid duplication.


> > 
> > Signed-off-by: Marius Cristea <marius.cristea@microchip.com>
> > ---
> >  .../bindings/iio/adc/microchip,pac193x.yaml   | 122 ++++++++++++++++++

Wild cards in names bite us far too often.  Name this and the driver after one of
the supported parts.

> >  1 file changed, 122 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml
> > new file mode 100644
> > index 000000000000..e4ea560991e9
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/microchip,pac193x.yaml
> > @@ -0,0 +1,122 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/microchip,pac193x.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Microchip PAC193X Power Monitors with Accumulator
> > +
> > +maintainers:
> > +  - Marius Cristea <marius.cristea@microchip.com>
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - microchip,pac1934
> > +      - microchip,pac1933
> > +      - microchip,pac1932
> > +      - microchip,pac1931  
> 
> Maybe order these numerically (ascending)?
> 
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  "#address-cells":
> > +    const: 1
> > +
> > +  "#size-cells":
> > +    const: 0
> > +
> > +  microchip,samp-rate:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: Sampling rate for all device's channels.  
> 
> What are the units? rate is usually in hz, which should be expressed in
> unit suffix (property name)]

It's unusual for sampling rate to be a property of the hardware and hence
suitable for DT binding. Normally we make this a userspace control instead.
If there is a reason for doing it from DT, that wants to be mentioned here.

> 
> > +    enum: [8, 64, 256, 1024]
> > +    default: 1024
> > +
> > +required:  
> 
> required goes after all properties, so after patternProperties
> 
> > +  - compatible
> > +  - reg
> > +  - microchip,samp-rate
> > +  - "#address-cells"
> > +  - "#size-cells"
> > +
> > +patternProperties:
> > +  "^channel([1-4])@[1-4]+$":  
> 
> Why first reg-pattern ([1-4])? For what do you need it?
> 
> > +    $ref: "adc.yaml"  
> 
> Drop quotes
> 
> > +    type: object
> > +    description: Represents the external channels which are connected to the ADC.
> > +
> > +    properties:
> > +      reg:
> > +        description: The channel number.
> > +          It can have up to 4 channels, numbered from 1 to 4.
> > +        items:
> > +          - minimum: 1
> > +            maximum: 4
> > +
> > +      microchip,uohms-shunt-res:  
> 
> Not a correct unit suffix. Use standard properties:
> git grep shunt -- Documentation/devicetree/

Check for existing relevant properties. Here we have
shunt-resistor-micro-ohms in common use in both IIO and hwmon.


> 
> 
> > +        $ref: /schemas/types.yaml#/definitions/uint32
> > +        description: |
> > +          Value in micro Ohms of the shunt resistor connected between
> > +          the SENSE+ and SENSE- inputs, across which the current is measured. Value
> > +          is needed to compute the scaling of the measured current.
> > +
> > +      microchip,rail-name:
> > +        $ref: /schemas/types.yaml#/definitions/string
> > +        description: Name of the monitored power rail.  
> 
> Why do you need it? Why this is a property of DT? Aren't you now
> duplicating label?


Agreed. Sounds like label to me as well.

> 
> > +
> > +      microchip,bi-directional:
> > +        description: Whether the channel is bi-directional.  
> 
> Describe here what is a "bi-directional" channel for ADC... Maybe it is
> obvious, maybe not. For me it is not and none of other devices have it.
> 
From datasheet this seems to be a novel description of whether the ADC
is measuring just positive or allows for negative voltage as well (i.e.
the current through the shut resistor is going on the other direction).
Can we relate this to a biopolar / unipolar decision on a simple voltage ADC?
For that we have standard DT bindings in iio/adc/adc.yaml


> > +        type: boolean
> > +
> > +    required:
> > +      - reg
> > +      - microchip,uohms-shunt-res
> > +      - microchip,rail-name
> > +
> > +    additionalProperties: false
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    i2c {
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        pac193x: pac193x@10 {  
> 
> Node names should be generic.
> https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation
> 
> > +            compatible = "microchip,pac1934";
> > +            reg = <0x10>;
> > +
> > +            #address-cells = <1>;
> > +            #size-cells = <0>;
> > +            microchip,samp-rate = <64>;
> > +
> > +            channel1@1 {  
> 
> 1@1 is for sure not generic...

Standard naming for channel nodes in adc.yaml
Some bindings predate that, but for new ones please match it.

Thanks,

Jonathan



> 
> 
> 
> Best regards,
> Krzysztof
>

Hi Jonathan,

   Thank you so much! I'm happy to contribute to IIO.

I will remove some section because I agree with the propose solution.
For the rest I will comment below..



On Sat, 2023-02-25 at 17:17 +0000, Jonathan Cameron wrote:
> > > +
> > > +  microchip,samp-rate:
> > > +    $ref: /schemas/types.yaml#/definitions/uint32
> > > +    description: Sampling rate for all device's channels.
> > 
> > What are the units? rate is usually in hz, which should be
> > expressed in
> > unit suffix (property name)]
> 
> It's unusual for sampling rate to be a property of the hardware and
> hence
> suitable for DT binding. Normally we make this a userspace control
> instead.
> If there is a reason for doing it from DT, that wants to be mentioned
> here.
> 

Here I could change it into the datarate (as in
iio/adc/ti,ads1015.yaml). The units are samples per second. My
intention was to be alingned with the datasheet.

My intention was to let the user configure the sample rate as soon as
posile during the startup (the PAC device's own power consumtion will
increase with the sampling rate - default the chip will start with the
maximum samples per second).


> 

> 
> > 
> > > +
> > > +      microchip,bi-directional:
> > > +        description: Whether the channel is bi-directional.
> > 
> > Describe here what is a "bi-directional" channel for ADC... Maybe
> > it is
> > obvious, maybe not. For me it is not and none of other devices have
> > it.
> > 
> From datasheet this seems to be a novel description of whether the
> ADC
> is measuring just positive or allows for negative voltage as well
> (i.e.
> the current through the shut resistor is going on the other
> direction).
> Can we relate this to a biopolar / unipolar decision on a simple
> voltage ADC?
> For that we have standard DT bindings in iio/adc/adc.yaml
> 

Yes, the PAC device can measure voltages as unipolar or bipolar but
also current as unidirectional or bidirectional (we are measuring the
voltage across a shunt resistor). We are also reporting power and is
not a "usual" thing to report power as unipolar or bipolar. Bi-
directional power makes more sens if you are thinking to monitor a
charge discharge cycle for a battery pack.



Thanks,
Marius

On 06/03/2023 14:53, Marius.Cristea@microchip.com wrote:
> 
> Hi Jonathan,
> 
>    Thank you so much! I'm happy to contribute to IIO.
> 
> I will remove some section because I agree with the propose solution.
> For the rest I will comment below..
> 
> 
> 
> On Sat, 2023-02-25 at 17:17 +0000, Jonathan Cameron wrote:
>>>> +
>>>> +  microchip,samp-rate:
>>>> +    $ref: /schemas/types.yaml#/definitions/uint32
>>>> +    description: Sampling rate for all device's channels.
>>>
>>> What are the units? rate is usually in hz, which should be
>>> expressed in
>>> unit suffix (property name)]
>>
>> It's unusual for sampling rate to be a property of the hardware and
>> hence
>> suitable for DT binding. Normally we make this a userspace control
>> instead.
>> If there is a reason for doing it from DT, that wants to be mentioned
>> here.
>>
> 
> Here I could change it into the datarate (as in
> iio/adc/ti,ads1015.yaml). The units are samples per second. My
> intention was to be alingned with the datasheet.
> 
> My intention was to let the user configure the sample rate as soon as
> posile during the startup (the PAC device's own power consumtion will
> increase with the sampling rate - default the chip will start with the
> maximum samples per second).

Then maybe the default should be just lowest rate and user will adjust
it further? Since this is user-space knob, why this should be even
configurable per board?


Best regards,
Krzysztof

On Mon, 6 Mar 2023 13:53:27 +0000
<Marius.Cristea@microchip.com> wrote:

> Hi Jonathan,
> 
>    Thank you so much! I'm happy to contribute to IIO.
> 
> I will remove some section because I agree with the propose solution.
> For the rest I will comment below..
> 
> 
> 
> On Sat, 2023-02-25 at 17:17 +0000, Jonathan Cameron wrote:
> > > > +
> > > > +  microchip,samp-rate:
> > > > +    $ref: /schemas/types.yaml#/definitions/uint32
> > > > +    description: Sampling rate for all device's channels.  
> > > 
> > > What are the units? rate is usually in hz, which should be
> > > expressed in
> > > unit suffix (property name)]  
> > 
> > It's unusual for sampling rate to be a property of the hardware and
> > hence
> > suitable for DT binding. Normally we make this a userspace control
> > instead.
> > If there is a reason for doing it from DT, that wants to be mentioned
> > here.
> >   
> 
> Here I could change it into the datarate (as in
> iio/adc/ti,ads1015.yaml). The units are samples per second. My
> intention was to be alingned with the datasheet.
> 
> My intention was to let the user configure the sample rate as soon as
> posile during the startup (the PAC device's own power consumtion will
> increase with the sampling rate - default the chip will start with the
> maximum samples per second).

Feel free to have the driver set it to the minimum frequency unconditionally
in probe.

> 
> 
> >   
> 
> >   
> > >   
> > > > +
> > > > +      microchip,bi-directional:
> > > > +        description: Whether the channel is bi-directional.  
> > > 
> > > Describe here what is a "bi-directional" channel for ADC... Maybe
> > > it is
> > > obvious, maybe not. For me it is not and none of other devices have
> > > it.
> > >   
> > From datasheet this seems to be a novel description of whether the
> > ADC
> > is measuring just positive or allows for negative voltage as well
> > (i.e.
> > the current through the shut resistor is going on the other
> > direction).
> > Can we relate this to a biopolar / unipolar decision on a simple
> > voltage ADC?
> > For that we have standard DT bindings in iio/adc/adc.yaml
> >   
> 
> Yes, the PAC device can measure voltages as unipolar or bipolar but
> also current as unidirectional or bidirectional (we are measuring the
> voltage across a shunt resistor). We are also reporting power and is
> not a "usual" thing to report power as unipolar or bipolar. Bi-
> directional power makes more sens if you are thinking to monitor a
> charge discharge cycle for a battery pack.

I'm still a little confused. If you are bipolar and hence can measure
postive and negative voltage between two pins, how is that different
to bidirectional? Other than for bidirection we are talking current
rather than voltage.

> 
> 
> 
> Thanks,
> Marius