Re: [PATCH v11 1/2] dt-bindings: adc: add AD7173

[Jonathan Cameron <Jonathan.Cameron@xxxxxxxxxx>]

On Mon, 15 Jan 2024 15:53:39 -0600
David Lechner <dlechner@xxxxxxxxxxxx> wrote:

> On Wed, Dec 20, 2023 at 4:48 AM Dumitru Ceclan <mitrutzceclan@xxxxxxxxx> wrote:
> >
> > The AD7173 family offer a complete integrated Sigma-Delta ADC solution
> > which can be used in high precision, low noise single channel applications
> > or higher speed multiplexed applications. The Sigma-Delta ADC is intended
> > primarily for measurement of signals close to DC but also delivers
> > outstanding performance with input bandwidths out to ~10kHz.
> >
> > Signed-off-by: Dumitru Ceclan <mitrutzceclan@xxxxxxxxx>
> > ---  
> 
> Sorry for the late reply as I see this has been applied already but...
We have plenty of time.  Rather than dropping the ad7173 from my tree,
I'd prefer to see additional patches on top to tidy up whatever
makes sense from David's feedback.

> 
> (I've been going over the datasheets for these and other related parts
> (AD411x) in detail today so please CC me on future updates to the
> bindings/driver for these if you don't mind)
> 
> >  .../bindings/iio/adc/adi,ad7173.yaml          | 188 ++++++++++++++++++
> >  1 file changed, 188 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
> > new file mode 100644
> > index 000000000000..7c8caef76528
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
> > @@ -0,0 +1,188 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +# Copyright 2023 Analog Devices Inc.
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/adi,ad7173.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Analog Devices AD7173 ADC
> > +
> > +maintainers:
> > +  - Ceclan Dumitru <dumitru.ceclan@xxxxxxxxxx>
> > +
> > +description: |
> > +  Bindings for the Analog Devices AD717X ADC's. Datasheets for supported chips:
> > +    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-2.pdf
> > +    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7173-8.pdf
> > +    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-2.pdf
> > +    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7176-2.pdf
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - adi,ad7172-2
> > +      - adi,ad7173-8
> > +      - adi,ad7175-2
> > +      - adi,ad7176-2
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1  
> 
> As discussed in v8 [1] it is not clear what signal this is. Based on
> that discussion, I'm assuming the RDY signal, but how would bindings
> consumers know that without a description since it is not the only
> digital output signal of the chip? And why the ERROR signal was
> omitted here was never addressed AFAICT.
> 
> [1]: https://lore.kernel.org/linux-iio/20231217135007.3e5d959a@jic23-huawei/

I'd forgotten about that.  Adding interrupt-names would be the easiest
way to resolve this.

> 
> > +
> > +  '#address-cells':
> > +    const: 1
> > +
> > +  '#size-cells':
> > +    const: 0
> > +
> > +  spi-max-frequency:
> > +    maximum: 20000000
> > +  
> 
> According to the timing diagram in the datasheet, SCLK is high during
> idle, so don't we need `spi-cpol: true` here?
> 
> Likewise, data is valid on the trailing SCLK edge, so don't we need
> `spi-cpha: true` here?
> 
> 
> > +  gpio-controller:
> > +    description: Marks the device node as a GPIO controller.
> > +
> > +  "#gpio-cells":
> > +    const: 2
> > +    description:
> > +      The first cell is the GPIO number and the second cell specifies
> > +      GPIO flags, as defined in <dt-bindings/gpio/gpio.h>.
> > +
> > +  refin-supply:
> > +    description: external reference supply, can be used as reference for conversion.  
> 
> If I'm understanding correctly, this represents both voltage inputs
> REF+ and REF-, correct? The datasheet says "Reference Input Negative
> Terminal. REF− can span from AVSS to AVDD1 − 1 V". It seems like they
> should be separate supplies in case REF- is non-zero. Otherwise, how
> can we know what voltage it is? (same comment applies to refin2.)

Agreed, in this case these are directly used as references (we recently
had another driver that could take a wide range of negative and positive
inputs but in that case an internal reference was generated that didn't
made it not matter exactly what was being supplied.  Not true here though!

> 
> > +
> > +  refin2-supply:
> > +    description: external reference supply, can be used as reference for conversion.
> > +
> > +  avdd-supply:
> > +    description: avdd supply, can be used as reference for conversion.
> > +
> > +  avdd2-supply:
> > +    description: avdd2 supply, used as the input to the internal voltage regulator.
> > +
> > +  iovdd-supply:
> > +    description: iovdd supply, used for the chip digital interface.
> > +  
> 
> I overlooked this before, but these chips also have an optional
> external clock input so it seems like they should have an optional
> clocks property as well.
> 
> > +patternProperties:
> > +  "^channel@[0-9a-f]$":
> > +    type: object
> > +    $ref: adc.yaml
> > +    unevaluatedProperties: false
> > +
> > +    properties:
> > +      reg:
> > +        minimum: 0
> > +        maximum: 15
> > +
> > +      diff-channels:
> > +        items:
> > +          minimum: 0
> > +          maximum: 31
> > +
> > +      adi,reference-select:
> > +        description: |
> > +          Select the reference source to use when converting on
> > +          the specific channel. Valid values are:
> > +          refin      : REFIN(+)/REFIN(−).
> > +          refin2     : REFIN2(+)/REFIN2(−)
> > +          refout-avss: REFOUT/AVSS (Internal reference)
> > +          avdd       : AVDD
> > +
> > +          External reference refin2 only available on ad7173-8.
> > +          If not specified, internal reference used.
> > +        $ref: /schemas/types.yaml#/definitions/string
> > +        enum:
> > +          - refin
> > +          - refin2
> > +          - refout-avss
> > +          - avdd
> > +        default: refout-avss
> > +
> > +    required:
> > +      - reg
> > +      - diff-channels
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts  
> 
> Why are interrupts required? What if the pin is not connected?
> 
Ah. I clearly failed to review this one closely enough.

Absolutely agree that interrupts should never be required.
No need for the driver to work if they aren't, but the binding
shouldn't require them!

Jonathan