dts/upstream/Bindings/iio/adc/adi,ad7944.yaml

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

title: Analog Devices PulSAR LFCSP Analog to Digital Converters

maintainers:
  - Michael Hennerich <Michael.Hennerich@analog.com>
  - Nuno Sá <nuno.sa@analog.com>

description: |
  A family of pin-compatible single channel differential analog to digital
  converters with SPI support in a LFCSP package.

  * https://www.analog.com/en/products/ad7944.html
  * https://www.analog.com/en/products/ad7985.html
  * https://www.analog.com/en/products/ad7986.html

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

properties:
  compatible:
    enum:
      - adi,ad7944
      - adi,ad7985
      - adi,ad7986

  reg:
    maxItems: 1

  spi-max-frequency:
    maximum: 111111111

  spi-cpol: true
  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

  avdd-supply:
    description: A 2.5V supply that powers the analog circuitry.

  dvdd-supply:
    description: A 2.5V supply that powers the digital circuitry.

  vio-supply:
    description:
      A 1.8V to 2.7V supply for the digital inputs and outputs.

  bvdd-supply:
    description:
      A voltage supply for the buffered power. When using an external reference
      without an internal buffer (PDREF high, REFIN low), this should be
      connected to the same supply as ref-supply. Otherwise, when using an
      internal reference or an external reference with an internal buffer, this
      is connected to a 5V supply.

  ref-supply:
    description:
      Voltage regulator for the external reference voltage (REF). This property
      is omitted when using an internal reference.

  refin-supply:
    description:
      Voltage regulator for the reference buffer input (REFIN). When using an
      external buffer with internal reference, this should be connected to a
      1.2V external reference voltage supply. Otherwise, this property is
      omitted.

  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

  turbo-gpios:
    description:
      GPIO connected to the TURBO line. If omitted, it is assumed that the TURBO
      line is hard-wired and the state is determined by the adi,always-turbo
      property.
    maxItems: 1

  adi,always-turbo:
    type: boolean
    description:
      When present, this property indicates that the TURBO line is hard-wired
      and the state is always high. If neither this property nor turbo-gpios is
      present, the TURBO line is assumed to be hard-wired and the state is
      always low.

  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
  - avdd-supply
  - dvdd-supply
  - vio-supply
  - bvdd-supply

allOf:
  # ref-supply and refin-supply are mutually exclusive (neither is also valid)
  - if:
      required:
        - ref-supply
    then:
      properties:
        refin-supply: false
  - if:
      required:
        - refin-supply
    then:
      properties:
        ref-supply: false
  # 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 and doesn't work when TURBO is enabled
  - if:
      required:
        - adi,spi-mode
      properties:
        adi,spi-mode:
          const: chain
    then:
      properties:
        spi-max-frequency:
          maximum: 90909090
        adi,always-turbo: false
      required:
        - '#daisy-chained-devices'
    else:
      properties:
        '#daisy-chained-devices': false
  # turbo-gpios and adi,always-turbo are mutually exclusive
  - if:
      required:
        - turbo-gpios
    then:
      properties:
        adi,always-turbo: false
  - if:
      required:
        - adi,always-turbo
    then:
      properties:
        turbo-gpios: false

unevaluatedProperties: false

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    spi {
        #address-cells = <1>;
        #size-cells = <0>;
        adc@0 {
            compatible = "adi,ad7944";
            reg = <0>;
            spi-cpha;
            spi-max-frequency = <111111111>;
            avdd-supply = <&supply_2_5V>;
            dvdd-supply = <&supply_2_5V>;
            vio-supply = <&supply_1_8V>;
            bvdd-supply = <&supply_5V>;
            cnv-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>;
            turbo-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>;
        };
    };