Re: [PATCH 1/2] dt-bindings: iio: adc: Add AD4000

David Lechner
2024-03-23T20:19:01Z

On Sat, Mar 23, 2024 at 1:45 PM Jonathan Cameron <jic23@kernel.org> wrote:
>
> On Fri, 22 Mar 2024 19:05:08 -0300
> Marcelo Schmitt <marcelo.schmitt@analog.com> wrote:
>
> > Add device tree documentation for AD4000 series of ADC devices.
> >
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ad4000-4004-4008.pdf
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ad4001-4005.pdf
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ad4002-4006-4010.pdf
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ad4003-4007-4011.pdf
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ad4020-4021-4022.pdf
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/adaq4001.pdf
> > Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/adaq4003.pdf
> >
> > Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
> > ---
> > Pasting relevant comment from cover letter here to aid reviewers.
> >
> > These devices have the same SPI (Strange Peripheral Interface) as AD7944
> > devices, which has been documented in ad7944.rst [1].
> > The device tree description for SPI connections and mode can be the same as of
> > ad7944 adi,spi-mode [2].
> > Because ad4000 driver does not currently support daisy-chain mode, I simplified
> > things a little bit. If having a more complete doc is preferred, I'm fine
> > changing to that.

Yes, having a complete binding is always preferred [1]. Bindings
should never omit anything just because it isn't implemented in the
driver.

[1]: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-bindings.html

...

> > +
> > + adi,spi-cs-mode:
>
> We've just merged a driver for the ad7944 and bindings which has a
> similar 3-wire-mode. Please share the approach used in that binding.
> Whilst it seems we don't have the other mode here, I think we still want
> to use a similar enum.

The ad40xx chips actually do have the same daisy chain mode. So the
exact same property and all enum values apply.

> +CC David to take a look at this one given he went through long
> discussions on how to deal with it for the driver he was working on
> so probably remembers the reasoning etc better than I do :)
>

In addition to the SPI wiring modes, the proposed bindings are also
missing power supplies and the busy interrupt.

Also, since the ADAQ chips are quite different from the AD chips, it
would be very helpful for reviewers (and git history) to split out
adding those chips to the DT bindings and driver into separate
patches. This way we can clearly see which features only apply to the
ADAQ chips.

Here is what I would consider a reasonably complete binding for the
AD40XX chips (excluding ADAQ for now as I suggested).

---
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/adc/adi,ad4000.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Analog Devices AD4000 and similar Analog to Digital Converters

maintainers:
- Marcelo Schmitt <marcelo.schmitt@analog.com>

description: |
Analog Devices AD4000 family of Analog to Digital Converters with SPI support.
Specifications can be found at:
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4000-4004-4008.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4001-4005.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4002-4006-4010.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4003-4007-4011.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ad4020-4021-4022.pdf

$ref: /schemas/spi/spi-peripheral-props.yaml#

properties:
compatible:
enum:
- adi,ad4000
- adi,ad4001
- adi,ad4002
- adi,ad4003
- adi,ad4004
- adi,ad4005
- adi,ad4006
- adi,ad4007
- adi,ad4008
- adi,ad4010
- adi,ad4011
- adi,ad4020
- adi,ad4021
- adi,ad4022

reg:
maxItems: 1

spi-max-frequency:
maximum: 102040816 # for VIO > 2.7 V, 81300813 for VIO > 1.7 V

spi-cpha: true

adi,spi-mode:
$ref: /schemas/types.yaml#/definitions/string
enum: [ single, chain ]
description: |
This property indicates the SPI wiring configuration.

When this property is omitted, it is assumed that the device is using what
the datasheet calls "4-wire mode". This is the conventional SPI mode used
when there are multiple devices on the same bus. In this mode, the CNV
line is used to initiate the conversion and the SDI line is connected to
CS on the SPI controller.

When this property is present, it indicates that the device is using one
of the following alternative wiring configurations:

* single: The datasheet calls this "3-wire mode". (NOTE: The datasheet's
definition of 3-wire mode is NOT at all related to the standard
spi-3wire property!) This mode is often used when the ADC is the only
device on the bus. In this mode, SDI is tied to VIO, and the CNV line
can be connected to the CS line of the SPI controller or to a GPIO, in
which case the CS line of the controller is unused.
* chain: The datasheet calls this "chain mode". This mode is used to save
on wiring when multiple ADCs are used. In this mode, the SDI line of
one chip is tied to the SDO of the next chip in the chain and the SDI of
the last chip in the chain is tied to GND. Only the first chip in the
chain is connected to the SPI bus. The CNV line of all chips are tied
together. The CS line of the SPI controller can be used as the CNV line
only if it is active high.

'#daisy-chained-devices': true

vdd-supply:
description: A 1.8V supply that powers the chip (VDD).

vio-supply:
description:
A 1.8V to 5V supply for the digital inputs and outputs (VIO).

ref-supply:
description:
A 2.5 to 5V supply for the external reference voltage (REF).

cnv-gpios:
description:
The Convert Input (CNV). This input has multiple functions. It initiates
the conversions and selects the SPI mode of the device (chain or CS). In
'single' mode, this property is omitted if the CNV pin is connected to the
CS line of the SPI controller.
maxItems: 1

interrupts:
description:
The SDO pin can also function as a busy indicator. This node should be
connected to an interrupt that is triggered when the SDO line goes low
while the SDI line is high and the CNV line is low ('single' mode) or the
SDI line is low and the CNV line is high ('multi' mode); or when the SDO
line goes high while the SDI and CNV lines are high (chain mode),
maxItems: 1

required:
- compatible
- reg
- vdd-supply
- vio-supply
- ref-supply

allOf:
# in '4-wire' mode, cnv-gpios is required, for other modes it is optional
- if:
not:
required:
- adi,spi-mode
then:
required:
- cnv-gpios
# chain mode has lower SCLK max rate
- if:
required:
- adi,spi-mode
properties:
adi,spi-mode:
const: chain
then:
properties:
spi-max-frequency:
maximum: 50000000 # for VIO > 2.7 V, 40000000 for VIO > 1.7 V
required:
- '#daisy-chained-devices'
else:
properties:
'#daisy-chained-devices': false

unevaluatedProperties: false

examples:
- |
#include <dt-bindings/gpio/gpio.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
adc@0 {
compatible = "adi,ad4020";
reg = <0>;
spi-max-frequency = <71000000>;
vdd-supply = <&supply_1_8V>;
vio-supply = <&supply_1_8V>;
ref-supply = <&supply_5V>;
cnv-gpios = <&gpio0 88 GPIO_ACTIVE_HIGH>;
};
};