Re: [PATCH v9 7/8] dt-bindings: iio: adc: add ad4851

[Jonathan Cameron <jic23@kernel.org>]

On Fri, 20 Dec 2024 14:01:33 +0200
Antoniu Miclaus <antoniu.miclaus@analog.com> wrote:

> Add devicetree bindings for ad485x family.
> 
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com>
Mixed single end and differential channel devices that have per channel
child nodes need a more complex description to avoid reg have different
and possibly clashing meanings for the two types of channel.

See inline.

Thanks,

Jonathan

> ---
> changes in v9:
>  - add back diff-channels property.
>  .../bindings/iio/adc/adi,ad4851.yaml          | 142 ++++++++++++++++++
>  1 file changed, 142 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml
> new file mode 100644
> index 000000000000..5911f1cfc39d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml
> @@ -0,0 +1,142 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +# Copyright 2024 Analog Devices Inc.
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/adi,ad4851.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AD485X family
> +
> +maintainers:
> +  - Sergiu Cuciurean <sergiu.cuciurean@analog.com>
> +  - Dragos Bogdan <dragos.bogdan@analog.com>
> +  - Antoniu Miclaus <antoniu.miclaus@analog.com>
> +
> +description: |
> +  Analog Devices AD485X fully buffered, 8-channel simultaneous sampling,
> +  16/20-bit, 1 MSPS data acquisition system (DAS) with differential, wide
> +  common-mode range inputs.
> +
> +  https://www.analog.com/media/en/technical-documentation/data-sheets/ad4855.pdf
> +  https://www.analog.com/media/en/technical-documentation/data-sheets/ad4856.pdf
> +  https://www.analog.com/media/en/technical-documentation/data-sheets/ad4857.pdf
> +  https://www.analog.com/media/en/technical-documentation/data-sheets/ad4858.pdf
> +
> +$ref: /schemas/spi/spi-peripheral-props.yaml#
> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad4851
> +      - adi,ad4852
> +      - adi,ad4853
> +      - adi,ad4854
> +      - adi,ad4855
> +      - adi,ad4856
> +      - adi,ad4857
> +      - adi,ad4858
> +      - adi,ad4858i
> +
> +  reg:
> +    maxItems: 1
> +
> +  vcc-supply: true
> +
> +  vee-supply: true
> +
> +  vdd-supply: true
> +
> +  vddh-supply: true
> +
> +  vddl-supply: true
> +
> +  vio-supply: true
> +
> +  vrefbuf-supply: true
> +
> +  vrefio-supply: true
> +
> +  pwms:
> +    description: PWM connected to the CNV pin.
> +    maxItems: 1
> +
> +  io-backends:
> +    maxItems: 1
> +
> +  pd-gpios:
> +    maxItems: 1
> +
> +  spi-max-frequency:
> +    maximum: 25000000
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +patternProperties:
> +  "^channel(@[0-7])?$":
> +    $ref: adc.yaml
> +    type: object
> +    description: Represents the channels which are connected to the ADC.
> +
> +    properties:
> +      reg:
> +        description: The channel number in single-ended mode.

And what is it in differential mode?  (usually just an index).
Which is a problem if you have a mix.  That's why we added
single-channel.

So for devices where reg isn't enough, you can use:
reg: index of channel, not real meaning just makes them unique.
single-channel: The channel number for single ended.
diff-channels: The channel numbers for differential channels.

> +        minimum: 0
> +        maximum: 7
> +
> +      diff-channels: true

Should be constraints / information on the values possible.
I've no idea what the 8 is in your example for instance.

> +
> +      bipolar: true
> +
> +    required:
> +      - reg
> +
> +    additionalProperties: false
> +
> +required:
> +  - compatible
> +  - reg
> +  - vcc-supply
> +  - vee-supply
> +  - vdd-supply
> +  - vio-supply
> +  - pwms
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    spi {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        adc@0{
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            compatible = "adi,ad4858";
> +            reg = <0>;
> +            spi-max-frequency = <10000000>;
> +            vcc-supply = <&vcc>;
> +            vdd-supply = <&vdd>;
> +            vee-supply = <&vee>;
> +            vddh-supply = <&vddh>;
> +            vddl-supply = <&vddl>;
> +            vio-supply = <&vio>;
> +            pwms = <&pwm_gen 0 0>;
> +            io-backends = <&iio_backend>;
> +
> +            channel@0 {
> +              reg = <0>;
> +              diff-channels = <0 8>;
> +              bipolar;
> +            };
> +
> +            channel@1 {
> +              reg = <1>;
> +            };
> +        };
> +    };
> +...