On Sat, Mar 23, 2024 at 1:45 PM Jonathan Cameron <jic23@xxxxxxxxxx> wrote: > > On Fri, 22 Mar 2024 19:05:08 -0300 > Marcelo Schmitt <marcelo.schmitt@xxxxxxxxxx> 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@xxxxxxxxxx> > > --- > > 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@xxxxxxxxxx> 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>; }; };
